jangada.system.System#

class jangada.system.System(*args, **kwargs)#

Bases: Persistable, Displayable, Identifiable, Taggable, Nameable, Describable

Hierarchical namespace container for organizing subsystems.

System provides a framework for building tree-structured hierarchies with automatic bidirectional parent-child relationship management. Subsystems can be accessed via tag using either dict-style (system['tag']) or attribute-style (system.tag) syntax.

Key features: - Automatic parent-child relationship management - Tag-based namespace access (dict and attribute style) - Dynamic tag reorganization via observers - Circular dependency prevention - Persistence of entire hierarchies - Rich terminal display integration

Attributes:
subsystemsdict[str, System]

Dictionary mapping tags to subsystem objects. Managed automatically.

supersystemSystem or None

Get parent system.

supersystem_chainlist[System]

Get list of all ancestors.

See also

Persistable

Serialization base class

Displayable

Terminal display base class

Identifiable

Unique identification mixin

Taggable

Tag-based identification mixin

Notes

Hierarchy Structure

Systems form a tree structure (not DAG). Each system has at most one parent. Circular dependencies are prevented automatically.

Tag Requirements

Subsystems must have tags to be registered. Tags must be valid Python identifiers and cannot be Python keywords.

Tag Observers

When a subsystem’s tag changes, the parent’s subsystems dict is automatically updated. This is achieved through the observer pattern.

Identity vs Content Equality

  • sys1 == sys2 uses Identifiable (ID-based equality)

  • sys1.equal(sys2) uses Persistable (content-based equality)

Persistence

Saving a system saves its entire subtree. Parent references are stored as IDs, allowing proper reconstruction on load.

Reserved Attributes

Avoid using subsystem tags that conflict with System’s methods and properties (e.g., ‘add’, ‘remove’, ‘subsystems’, ‘tag’, ‘id’).

Examples

Create simple hierarchy:

root = System(tag='root', name='Root System')
child = System(tag='child', name='Child System')

root.add(child)

# Access via dict or attribute
assert root['child'] is child
assert root.child is child

Dict-style registration:

root = System(tag='root')
root['sensor'] = System(name='Temperature Sensor')

# Tag is automatically set from key
assert root['sensor'].tag == 'sensor'

Build complex hierarchy:

system = System(tag='system')

# Using dict-style
system['sensors'] = System(name='Sensors')
system['sensors']['temperature'] = System(name='Temp Sensor')
system['sensors']['pressure'] = System(name='Pressure Sensor')

# Navigate
temp = system.sensors.temperature
assert temp.name == 'Temp Sensor'

Dynamic reorganization:

root = System(tag='root')
child = System(tag='old_tag')
root.add(child)

# Change tag - dict keys update automatically
child.tag = 'new_tag'
assert 'new_tag' in root
assert 'old_tag' not in root

Save and load hierarchies:

root = System(tag='root')
root['child'] = System(tag='child', name='Child')

root.save('hierarchy.sys')

loaded = System.load('hierarchy.sys')
assert loaded.child.name == 'Child'

Content comparison:

sys1 = System(tag='test', name='Name')
sys2 = System(tag='test', name='Name')

# Different IDs, so ID-based equality is False
assert sys1 != sys2

# But same content, so content equality is True
assert sys1.equal(sys2)
__init__(*args, **kwargs) → None#

Initialize a Persistable object.

Supports three modes based on arguments:

  1. Normal construction: obj = MyClass(prop1=val1)

  2. Load from file: obj = MyClass('/path/file.hdf5')

  3. Context manager prep: obj = MyClass('/path/file.hdf5', mode='r')

Parameters:
*argstuple

If empty: normal Serializable construction with kwargs If single Path/str: load from that file If single Path/str with kwargs: prepare for context manager

**kwargsdict

For mode 1: property values For mode 3: must include ‘mode’ parameter (HDF5 file mode)

Raises:
ValueError

If unknown kwargs are provided in context manager mode.

FileNotFoundError

If loading from non-existent file.

Examples

Normal construction:

exp = Experiment(name="Test", temperature=300.0)

Load from file:

exp = Experiment('data.hdf5')

Prepare for context manager:

exp = Experiment('data.hdf5', mode='r+')
with exp as e:
    # Use e
    pass

Or directly:

with Experiment('data.hdf5', mode='r+') as exp:
    # Use exp
    pass

Methods

__contains__(obj)

Check if subsystem is registered.

__copy__()

Support for the copy module.

__delattr__(name, /)

Implement delattr(self, name).

__dir__(/)

Default dir() implementation.

__enter__()

Enter context manager mode.

__eq__(other)

Compare equality based on ID.

__exit__(exc_type, exc_val, exc_tb)

Exit context manager mode.

__format__(format_spec, /)

Default object formatter.

__ge__(value, /)

Return self>=value.

__getattribute__(name, /)

Return getattr(self, name).

__getitem__(tag)

Get subsystem by tag (dict-style access).

__getstate__(/)

Helper for pickle.

__gt__(value, /)

Return self>value.

__hash__()

Compute hash based on ID.

__init__(*args, **kwargs)

Initialize a Persistable object.

__init_subclass__

This method is called when a class is subclassed.

__iter__()

Iterate over direct subsystems.

__le__(value, /)

Return self<=value.

__len__()

Return number of direct subsystems.

__lt__(value, /)

Return self<value.

__ne__(value, /)

Return self!=value.

__reduce__(/)

Helper for pickle.

__reduce_ex__(protocol, /)

Helper for pickle.

__repr__(/)

Return repr(self).

__rich__()

Rich protocol for direct rendering.

__setitem__(tag, value)

Register subsystem via dict-style assignment.

__sizeof__(/)

Size of object in memory, in bytes.

__str__()

String representation with Rich formatting.

__subclasshook__

Abstract classes can override this to customize issubclass().

_content()

Generate display content.

_display_panel()

Create formatted panel with current settings.

_get_tag_observer(subsystem)

Create tag change observer for a subsystem.

_initialize_from_data(data)

Initialize object properties from a dictionary.

_load_data_from_h5py_tree(value[, ...])

Recursively load data from HDF5 structure.

_save_data_in_group(key, value, group)

Recursively save data to an HDF5 group.

_title()

Generate display title.

add(*subsystems)

Add one or more subsystems.

copy()

Create an independent copy of this object.

deserialize(data)

Recursively deserialize data to reconstruct objects.

equal(system)

Compare content equality with another system.

format_as_form(data)

Format data as key-value form.

format_as_table(frame[, show_index, ...])

Format DataFrame as Rich table.

get_instance(id_)

Retrieve an Identifiable instance by its ID.

load(path)

Load an object from an HDF5 file.

load_serialized_data(path)

Load serialized data dictionary from HDF5 file.

remove(subsystem)

Remove a subsystem.

save(path[, overwrite, use_default_extension])

Save this object to an HDF5 file.

save_serialized_data(path, data)

Save serialized data dictionary to HDF5 file.

serialize(obj[, is_copy])

Recursively serialize an object to a dictionary structure.

to_html([width])

Export display as HTML.

to_svg([width])

Export display as SVG.

Attributes

__abstractmethods__

__annotations__

__slots__

_abc_impl

_dataset_types

_instances

_primitive_types

_serializable_properties

_subclasses

_supersystem_id

Parent system ID.

_tag_observers

Get tag observer registry.

description

Free-form descriptive text.

display_settings

Configuration for display formatting and styling.

extension

File extension for saved System files.

id

Globally unique identifier (UUID v4).

name

Human-readable display name.

subsystems

Dictionary mapping tags to subsystem objects.

supersystem

Get parent system.

supersystem_chain

Get list of all ancestors.

tag

Symbolic identifier for namespace-style access.
On this page

This Page