base

base

Base module for named objects and their collections. Provides common functionality for serialization and management of named objects.

NamedObject

Bases: BaseModel

Base class for named objects with serialization support.

Attributes:

Name	Type	Description
type	str	Name of object class type (computed field)
name	str	Name of the object

Configuration

model_config (ConfigDict): Pydantic model configuration

type property

type: str

Returns the name of the object type.

__init_subclass__

__init_subclass__(*, registry_category: str = None, **kwargs)

Register subclasses in appropriate registry category.

Source code in src/data_handlers/base.py

def __init_subclass__(cls, *, registry_category: str = None, **kwargs):
    """Register subclasses in appropriate registry category."""
    super().__init_subclass__(**kwargs)
    if registry_category:
        cls._registry_category = registry_category
    ObjectRegistry.register(cls._registry_category, cls)

NamedObjectHash

Bases: BaseModel

Dictionary of named objects with type checking and conflict prevention.

Attributes:

Name	Type	Description
objects	dict	Dictionary of named objects

deserialize_objects classmethod

deserialize_objects(data: Any) -> Any

Deserialize objects during validation.

Source code in src/data_handlers/base.py

@model_validator(mode='before')
@classmethod
def deserialize_objects(cls, data: Any) -> Any:
    """Deserialize objects during validation."""
    if not isinstance(data, dict):
        return data

    objects = data.get('objects', {})
    if isinstance(objects, dict):
        for name, obj_data in objects.items():
            if isinstance(obj_data, dict):
                type_name = obj_data.get('type')
                if type_name:
                    # Remove type as it's not part of the constructor
                    obj_data = obj_data.copy()
                    obj_data.pop('type')
                    obj_type = ObjectRegistry.get(cls._registry_category, type_name)
                    data['objects'][name] = obj_type(**obj_data)
    return data

get_object

get_object(name: str) -> NamedObject

Get object by name.

Source code in src/data_handlers/base.py

def get_object(self, name: str) -> NamedObject:
    """Get object by name."""
    return self.objects[name]

get_object_names

get_object_names() -> Iterable[str]

Get names of all objects.

Source code in src/data_handlers/base.py

def get_object_names(self) -> Iterable[str]:
    """Get names of all objects."""
    return self.objects.keys()

get_objects

get_objects() -> Iterable[NamedObject]

Get all objects.

Source code in src/data_handlers/base.py

def get_objects(self) -> Iterable[NamedObject]:
    """Get all objects."""
    return self.objects.values()

register_object

register_object(obj: NamedObject) -> Self

Register a named object. Checks for naming conflicts.

Parameters:

Name	Type	Description	Default
obj	NamedObject	Object to register	required

Raises:

Type	Description
ValueError	If object with same name exists

Source code in src/data_handlers/base.py

def register_object(self, obj: NamedObject) -> Self:
    """
    Register a named object. Checks for naming conflicts.

    Args:
        obj (NamedObject): Object to register

    Raises:
        ValueError: If object with same name exists
    """
    if obj.name in self.objects:
        raise ValueError(
            f"Naming conflict: An object named '{obj.name}' already exists."
            f"\n\tExisting: \n{self.get_object(obj.name).model_dump_json(indent=4)}"
            f"\n\tNew: \n{obj.model_dump_json(indent=4)}"
        )
    self.objects[obj.name] = obj
    return self

NamedObjectList

Bases: BaseModel

List of named objects with type checking.

Attributes:

Name	Type	Description
objects	list	List of named objects

Example

obj_list = NamedObjectList()
obj_list.append(named_object)
obj_list.extend([obj1, obj2, obj3])

__getitem__

__getitem__(idx: int) -> NamedObject

Get object by index.

Source code in src/data_handlers/base.py

def __getitem__(self, idx: int) -> NamedObject:
    """Get object by index."""
    return self.objects[idx]

__iter__

__iter__() -> Iterable[NamedObject]

Iterate over objects in list.

Source code in src/data_handlers/base.py

def __iter__(self) -> Iterable[NamedObject]:
    """Iterate over objects in list."""
    return iter(self.objects)

__len__

__len__() -> int

Return number of objects in list.

Source code in src/data_handlers/base.py

def __len__(self) -> int:
    """Return number of objects in list."""
    return len(self.objects)

append

append(obj: NamedObject) -> Self

Append a single object to the list.

Parameters:

Name	Type	Description	Default
obj	NamedObject	Object to append	required

Returns:

Name	Type	Description
Self	Self	Returns self for chaining

Source code in src/data_handlers/base.py

def append(self, obj: NamedObject) -> Self:
    """
    Append a single object to the list.

    Args:
        obj (NamedObject): Object to append

    Returns:
        Self: Returns self for chaining
    """
    self.objects.append(obj)
    return self

extend

extend(objects: Iterable[NamedObject]) -> Self

Extend list with multiple objects.

Parameters:

Name	Type	Description	Default
objects	Iterable[NamedObject]	Objects to add	required

Returns:

Name	Type	Description
Self	Self	Returns self for chaining

Source code in src/data_handlers/base.py

def extend(self, objects: Iterable[NamedObject]) -> Self:
    """
    Extend list with multiple objects.

    Args:
        objects (Iterable[NamedObject]): Objects to add

    Returns:
        Self: Returns self for chaining
    """
    self.objects.extend(objects)
    return self

from_iterable classmethod

from_iterable(iterable: Iterable[NamedObject]) -> Self

Create instance from an iterable of named objects.

Parameters:

Name	Type	Description	Default
iterable	Iterable[NamedObject]	Objects to add to list	required

Returns:

Name	Type	Description
Self	Self	New instance containing the objects

Source code in src/data_handlers/base.py

@classmethod
def from_iterable(cls, iterable: Iterable[NamedObject]) -> Self:
    """
    Create instance from an iterable of named objects.

    Args:
        iterable (Iterable[NamedObject]): Objects to add to list

    Returns:
        Self: New instance containing the objects
    """
    return cls(objects=list(iterable))

get_object

get_object(name: str) -> NamedObject

Get a registered object by name.

Parameters:

Name	Type	Description	Default
name	str	Name of the object to retrieve	required

Returns:

Name	Type	Description
NamedObject	NamedObject	The requested object

Raises:

Type	Description
KeyError	If no object exists with the given name

Example

obj_list = NamedObjectList()
obj_list.append(NamedObject("x"))
x = obj_list.get_object("x")

Source code in src/data_handlers/base.py

def get_object(self, name: str) -> NamedObject:
    """
    Get a registered object by name.

    Args:
        name (str): Name of the object to retrieve

    Returns:
        NamedObject: The requested object

    Raises:
        KeyError: If no object exists with the given name

    Example:
        ```python
        obj_list = NamedObjectList()
        obj_list.append(NamedObject("x"))
        x = obj_list.get_object("x")
        ```
    """
    for obj in self.objects:
        if obj.name == name:
            return obj
    raise KeyError(f"No object found with name '{name}'")

get_objects

get_objects() -> Iterable[NamedObject]

Get all registered objects.

Returns:

Type	Description
Iterable[NamedObject]	Iterable[NamedObject]: Iterator over all stored objects

Example

obj_list = NamedObjectList()
obj_list.extend([NamedObject("x"), NamedObject("y")])
for obj in obj_list.get_objects():
    print(obj.name)

Source code in src/data_handlers/base.py

def get_objects(self) -> Iterable[NamedObject]:
    """
    Get all registered objects.

    Returns:
        Iterable[NamedObject]: Iterator over all stored objects

    Example:
        ```python
        obj_list = NamedObjectList()
        obj_list.extend([NamedObject("x"), NamedObject("y")])
        for obj in obj_list.get_objects():
            print(obj.name)
        ```
    """
    return iter(self.objects)

register_object

register_object(obj: NamedObject) -> Self

Register a named object to the list with duplicate name checking.

Parameters:

Name	Type	Description	Default
obj	NamedObject	Object to register	required

Returns:

Name	Type	Description
Self	Self	Returns self for method chaining

Raises:

Type	Description
ValueError	If an object with the same name already exists

Example

obj_list = NamedObjectList()
obj_list.register_object(NamedObject("x"))

Source code in src/data_handlers/base.py

def register_object(self, obj: NamedObject) -> Self:
    """
    Register a named object to the list with duplicate name checking.

    Args:
        obj (NamedObject): Object to register

    Returns:
        Self: Returns self for method chaining

    Raises:
        ValueError: If an object with the same name already exists

    Example:
        ```python
        obj_list = NamedObjectList()
        obj_list.register_object(NamedObject("x"))
        ```
    """
    # Check for duplicates
    for existing_obj in self.objects:
        if existing_obj.name == obj.name:
            raise ValueError(
                f"Naming conflict: An object named '{obj.name}' already exists.\n"
                f"\tExisting: \n{existing_obj.model_dump_json(indent=4)}\n"
                f"\tNew: \n{obj.model_dump_json(indent=4)}"
            )
    self.objects.append(obj)
    return self

ObjectRegistry

Generic registry for named object types.

Stores object types for deserialization from JSON files. Types are stored at the class level for consistent access across modules.

Types are stored at the class level for consistent access across modules.

Methods:

Name	Description
register	Register an object type
get	Get an object type by name
get_all	Get all registered object types

get classmethod

get(category: str, name: str) -> Type[NamedObject]

Get an object type by category and name.

Source code in src/data_handlers/base.py

@classmethod
def get(cls, category: str, name: str) -> Type[NamedObject]:
    """Get an object type by category and name."""
    registry = cls.get_registry(category)
    if name not in registry:
        raise ValueError(f"{name} not found in {category} registry")
    return registry[name]

get_all classmethod

get_all(category: str) -> list[Type[NamedObject]]

Get all registered types for a category.

Source code in src/data_handlers/base.py

@classmethod
def get_all(cls, category: str) -> list[Type[NamedObject]]:
    """Get all registered types for a category."""
    return list(cls.get_registry(category).values())

get_registry classmethod

get_registry(category: str) -> Dict[str, Type[NamedObject]]

Get or create registry for a category.

Source code in src/data_handlers/base.py

@classmethod
def get_registry(cls, category: str) -> Dict[str, Type[NamedObject]]:
    """Get or create registry for a category."""
    # Get the actual string value if it's a PrivateAttr
    if hasattr(category, 'default'):
        category = category.default
    if category not in cls._registries:
        cls._registries[category] = {}
    return cls._registries[category]

register classmethod

register(category: str, obj_type: Type[NamedObject]) -> None

Register an object type in its category.

Source code in src/data_handlers/base.py

@classmethod
def register(cls, category: str, obj_type: Type[NamedObject]) -> None:
    """Register an object type in its category."""
    # Get the actual string value if it's a PrivateAttr
    if hasattr(category, 'default'):
        category = category.default
    registry = cls.get_registry(category)
    registry[obj_type.__name__] = obj_type