topos.core.object

Object Module

In Category Theory, an ‘Object’ is an abstract entity that serves as the domain or codomain of morphisms. In the category of Programs, we model the Abstract Syntax Tree (AST) as our primary object.

Mathematical Inspiration:

An object in our category represents the ‘shape’ or ‘structure’ of a computation—not what the program does, but how it is organized. Two programs with isomorphic ASTs are considered structurally equivalent, even if their surface syntax differs.

This abstraction allows us to reason about code structurally: transformations (refactorings) that preserve the AST structure are isomorphisms in the category of Programs.

class topos.core.object.ProgramObject(root, source, language='python', native_ast=None, uast_root=None, parser_name='tree-sitter', parser_version='tree-sitter>=0.23', native_node_kind='module', _node_count=None)

Bases: object

The AST lifted into the category of Programs.

A ProgramObject wraps a tree-sitter AST node and provides methods for structural analysis. It represents the ‘shape’ of code—the invariant structure that remains after stripping away surface syntax.

root

The root node of the parsed AST.

Type:

Node

source

The original source code (for reference).

Type:

str

language

The programming language of the source.

Type:

str

Categorical Interpretation:

Objects in our category are ASTs. A morphism f: A → B represents a program that transforms computations of shape A into shape B.

root

source

language = 'python'

native_ast = None

uast_root = None

parser_name = 'tree-sitter'

parser_version = 'tree-sitter>=0.23'

native_node_kind = 'module'

property node_count

Total number of nodes in the AST.

property depth

Maximum depth of the AST.

property is_valid

Check if the AST has no syntax errors.

traverse()

Depth-first traversal of all nodes.

Yields:

Each node in the AST in depth-first order.

nodes_of_type(*types)

Find all nodes matching the given type(s).

Parameters:

types – Node type strings to match (e.g., ‘function_definition’).

Yields:

Nodes whose type matches any of the given types.