simvx.core.cst_codegen

CST-aware code generation – read/write Python scene files preserving structure.

Provides utilities for detecting scene scripts, generating updated Python source from live node trees, and checking for ambiguous procedural patterns.

Public API: is_scene_script(path) – check if a Python file defines a scene codegen_scene_file(path) – generate updated source from a scene file has_ambiguities(source, class_name) – detect procedural add_child patterns save_tree_to_source(root) – generate Python source from a live node tree

Module Contents

Functions

is_scene_script	Check if a Python file defines a scene (contains Node subclass with init).
codegen_scene_file	Generate updated Python source from a scene file.
has_ambiguities	Check if init has procedural code (loops, conditionals with add_child).
save_tree_to_source	Generate Python source from a live node tree.

Data

log
__all__

API

simvx.core.cst_codegen.log

‘getLogger(…)’

simvx.core.cst_codegen.__all__

[‘is_scene_script’, ‘codegen_scene_file’, ‘has_ambiguities’, ‘save_tree_to_source’]

simvx.core.cst_codegen.is_scene_script(path: str | pathlib.Path) → bool

Check if a Python file defines a scene (contains Node subclass with init).

Uses stdlib ast for lightweight parsing – no imports needed. Returns False for non-existent files or parse errors.

simvx.core.cst_codegen.codegen_scene_file(path: str | pathlib.Path) → str | None

Generate updated Python source from a scene file.

Imports the module, finds the primary Node class, instantiates it, reads the live tree, and generates updated source via save_tree_to_source(). Returns the new source string (does NOT write to disk). Returns None on failure.

simvx.core.cst_codegen.has_ambiguities(source: str, class_name: str | None = None) → bool

Check if init has procedural code (loops, conditionals with add_child).

Uses stdlib ast to detect patterns like for ... add_child() or if ... add_child() that cannot be round-tripped losslessly.

simvx.core.cst_codegen.save_tree_to_source(root: simvx.core.node.Node, class_name: str | None = None, imports: list[str] | None = None) → str

Generate Python source from a live node tree.

Produces a Python class with an __init__ that reconstructs the tree via add_child() calls, writing only non-default kwargs.

Args: root: The root node of the tree to serialize. class_name: Name of the generated class. Defaults to type(root).__name__. imports: Optional list of import lines to include at the top.

Returns: Complete Python source string.