simvx.core.scene_io.source_tree

Lossless parse and re-emit of Python source via parso.

parse_source returns a SourceTree whose dump() is byte-identical to the input when nothing has been edited. Edits are applied directly to the underlying parso tree (see simvx.core.scene_io.edits); dump() serialises the current state via parso’s get_code().

Module Contents

Classes

SourceTree

A parsed Python source file with byte-perfect re-emit.

Functions

is_node	True when node is a composite node carrying a children list.
is_leaf	True when node is a terminal :class:Leaf carrying value.
parse_source	Parse Python source into a lossless SourceTree.
parse_snippet	Parse a fragment for splicing into another tree.

API

simvx.core.scene_io.source_tree.is_node(node: parso.tree.NodeOrLeaf) → TypeGuard[parso.tree.BaseNode]

True when node is a composite node carrying a children list.

parso’s :class:NodeOrLeaf is a union of :class:BaseNode (which has children) and :class:Leaf (which has value/prefix instead). Narrow with this guard before touching .children.

simvx.core.scene_io.source_tree.is_leaf(node: parso.tree.NodeOrLeaf) → TypeGuard[parso.tree.Leaf]

True when node is a terminal :class:Leaf carrying value.

simvx.core.scene_io.source_tree.parse_source(text: str, *, error_recovery: bool = True) → SourceTree

Parse Python source into a lossless SourceTree.

With error_recovery=True (default), broken sources still return a tree and any parser issues are exposed via :attr:SourceTree.errors. With error_recovery=False, malformed input raises parso.ParserSyntaxError.

simvx.core.scene_io.source_tree.parse_snippet(text: str) → parso.tree.NodeOrLeaf

Parse a fragment for splicing into another tree.

Accepts whole statements, single expressions, or suites. Returns the lifted inner node: the first child of the wrapping file_input module, with the trailing endmarker stripped, not the module itself. Caller is responsible for prefix/indent fixup before insertion (see

Mod:

simvx.core.scene_io.edits).

class simvx.core.scene_io.source_tree.SourceTree(module: parso.python.tree.Module, *, original_text: str)

A parsed Python source file with byte-perfect re-emit.

Holds the parso :class:Module plus the original source text so callers can detect a no-op round-trip via :meth:is_unchanged without diffing bytes themselves.

Initialization

__slots__

(‘_module’, ‘_original_text’, ‘_issues_cache’)

property module: parso.python.tree.Module

The underlying parso module. Edit in place via scene_io.edits.

property original_text: str

The text passed to :func:parse_source.

dump() → str

Return current source text via parso’s get_code().

Round-trip identity is guaranteed when no edits have been made: see

Meth:

is_unchanged.

is_unchanged() → bool

True iff :meth:dump equals the original input text.

property issues: list[simvx.core.scene_io.syntax.SyntaxIssue]

Every place parso could not read this source, classified, in order.

Empty when the source parses. Each carries the construct it holds where that is one of the ones the scene format documents as unreadable (:mod:simvx.core.scene_io.syntax), so a refusal can name it.

property errors: list[str]

Syntax errors detected by parso, as messages. Empty when valid.

find_class(name: str) → parso.python.tree.Class | None

First top-level class with matching name, else None.

iter_classes() → collections.abc.Iterator[parso.python.tree.Class]

Yield top-level class definitions in source order.

iter_imports() → collections.abc.Iterator[parso.tree.NodeOrLeaf]

Yield top-level import_name and import_from nodes in source order.

position_of(node: parso.tree.NodeOrLeaf) → tuple[int, int]

1-indexed (line, column) of node’s first leaf.

Matches the editor cursor convention; parso’s start_pos is already (line:1-indexed, column:0-indexed) so the column value is column 0 for the first character on a line.