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

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.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’, ‘_errors_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 errors: list[str]

Syntax errors detected by parso. Empty when source is 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.