simvx.core.scene_io.scene_module

Folder-as-scene editing surface.

This is Tier 4 of the scene I/O layer. A scene module is a Python package whose __init__.py (or, as a namespaced fallback, <folder>/<folder>.py) defines the primary :class:Node subclass; sibling .py files inside the folder hold sub-scenes that the root imports relatively. SceneModule is the multi-file analog of :class:SceneFile: it owns one root SceneFile plus zero or more sibling SceneFile instances, all editable, with

meth:

save flushing every dirty file in one pass.

Module Contents

Classes

SceneModule

A folder scene: a Python package whose __init__.py (or a <folder>/<folder_name>.py namespaced fallback) defines the primary Node subclass, with sibling .py files holding sub-scenes that the root imports.

Data

__all__

API

simvx.core.scene_io.scene_module.__all__

[‘NotASceneModuleError’, ‘SceneModule’]

exception simvx.core.scene_io.scene_module.NotASceneModuleError

Bases: ValueError

Raised when a folder doesn’t qualify as a scene module.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class __cause__

class __context__

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getstate__()

__gt__()

__hash__()

__le__()

__lt__()

__ne__()

__new__()

__reduce__()

__reduce_ex__()

__repr__()

__setattr__()

__setstate__()

__sizeof__()

__str__()

__subclasshook__()

class __suppress_context__

class __traceback__

add_note()

class args

with_traceback()

class simvx.core.scene_io.scene_module.SceneModule(folder: pathlib.Path, root_path: pathlib.Path, root: simvx.core.scene_io.scene_file.SceneFile)

A folder scene: a Python package whose __init__.py (or a <folder>/<folder_name>.py namespaced fallback) defines the primary Node subclass, with sibling .py files holding sub-scenes that the root imports.

SceneModule is the multi-file analog of SceneFile: it owns one root SceneFile plus zero or more sibling SceneFiles, all editable, with save() flushing every dirty file.

Initialization

__slots__

(‘_folder’, ‘_root_path’, ‘_root’, ‘_files’, ‘_to_delete’, ‘_added’)

classmethod load(folder: str | pathlib.Path) → simvx.core.scene_io.scene_module.SceneModule

Open a folder scene. Resolution order:

1. folder/__init__.py if it defines exactly one Node subclass.

2. folder/<folder_name>.py as a namespaced fallback.

Raises :class:NotASceneModuleError if neither matches. Raises

Class:

AmbiguousSceneError if either matching file has multiple Node subclasses.

static is_folder_scene(path: str | pathlib.Path) → bool

True iff path qualifies as a scene module under the same rules as :meth:load. False for files, missing paths, and folders that don’t match either resolution rule.

property folder: pathlib.Path

The folder path.

property root: simvx.core.scene_io.scene_file.SceneFile

SceneFile for the root scene definition (whichever of __init__.py or <folder_name>.py was selected).

property root_path: pathlib.Path

Path to the root file selected by the resolver.

files() → list[simvx.core.scene_io.scene_file.SceneFile]

Every .py SceneFile open for editing under this module (the root plus any opened sub-scenes), in stable order.

file(name: str) → simvx.core.scene_io.scene_file.SceneFile

Open (or return cached) the sibling file <name>.py as a SceneFile. name is the module stem, not a full path.

Raises :class:FileNotFoundError if the file doesn’t exist.

add_file(name: str, source: str) → simvx.core.scene_io.scene_file.SceneFile

Create a new sibling file <name>.py with the given source.

Returns the cached SceneFile. Raises :class:FileExistsError if the file already exists. The file is staged in memory until

Meth:

save.

remove_file(name: str) → None

Mark a sibling file for deletion on :meth:save.

Raises :class:FileNotFoundError if the file doesn’t exist on disk and wasn’t staged via :meth:add_file. The corresponding SceneFile cache entry is dropped immediately.

split_child(child_var: str, into_file: str) → simvx.core.scene_io.scene_file.SceneFile

Extract the child constructed by <child_var> in the root’s __init__ into a sibling file <into_file>.py.

The new file contains a Node subclass whose body matches the original child construction plus any subsequent __init__ statements that reference <child_var> (e.g. <child_var>.add_child(Weapon()) or <child_var>.scale = ...). The root’s child line becomes <child_var> = <NewClass>() and a relative import is added; the lifted statements are removed from the root’s __init__.

Refuses (raises :class:ValueError) if any lift candidate:

• lives inside a loop / conditional / try / with block

• depends on a helper variable assigned earlier in __init__ (the user must inline the helper into the lifted construction first, or restructure manually).

Returns the new SceneFile. Raises if <child_var> is not in the root, or if <into_file>.py already exists.

inline_file(child_path: str) → None

Inverse of :meth:split_child. Inline the named sub-scene back into the root: replace the <var> = <CustomClass>() line with a construction call (and child kwargs) matching the inlined class, remove the relative import, and :meth:remove_file the named file.

Raises if the named class is not currently used by the root, or if the file is not a clean leaf scene module (e.g. has procedural construction).

save() → list[pathlib.Path]

Write every dirty/added/removed file. Returns the list of paths written or removed (in stable order). Idempotent: a SceneModule with no edits writes nothing and returns [].

assert_idempotent() → None

Test helper: assert root and every cached file dump unchanged (no edits).