values

values

Module for generating, sorting, and managing named values. This uses pydantic dataclasses for JSON serialization to avoid overloading system memory.

The module provides a robust framework for managing named values with type safety, serialization, and state management. It includes classes for individual named values, collections of named values in both list and hash (dictionary) formats, and utilities for type validation and serialization.

Classes:

Name	Description
NamedValueState	Enum for tracking the state of named values
NamedValue	Base class for type-safe named values with state management
NamedValueHash	Dictionary-like container for managing named values
NamedValueList	List-like container for managing ordered named values

Types

SerializableValue: Union type defining all allowed value types T: Generic type variable bound to SerializableValue

NamedValue

NamedValue(name: str, value: T | None = None, **data)

Bases: NamedObject, Generic[T]

A named value container with type safety and state management.

NamedValue provides a type-safe way to store and manage values with built-in state tracking, serialization, and validation. Values can be frozen after initial setting to prevent accidental modification.

Type Parameters

T: The type of value to store, must be a SerializableValue

Attributes:

Name	Type	Description
name	str	Unique identifier for the value
_stored_value	T | NamedValueState	The actual stored value or UNSET state
_state	NamedValueState	Current state of the value
_type	type	Runtime type information for validation

Properties

value (T): Access or modify the stored value

Example

# Create a named integer value
count = NamedValue[int]("item_count")
count.value = 42  # Sets and freezes the value
print(count.value)  # Outputs: 42
count.value = 50  # Raises ValueError - value is frozen
count.force_set_value(50)  # Allows value change

Source code in src/data_handlers/values.py

def __init__(self, name: str, value: T | None = None, **data):
    # print(f"Initializing NamedValue with class: {self.__class__}")
    # print(f"Class __args__: {getattr(self.__class__, '__args__', None)}")
    # print(f"Bases: {self.__class__.__bases__}")
    # for base in self.__class__.__bases__:
    #     print(f"Base __args__: {getattr(base, '__args__', None)}")

    data.pop('stored_value', None)
    data.pop('_stored_value', None)

    super().__init__(name=name, **data)
    self._type = self._extract_value_type()
    # print(f"Extracted type: {self._type}")
    object.__setattr__(self, '_stored_value', NamedValueState.UNSET)

    if value is not None:
        self.value = value

value property writable

value: T

Get the stored value.

Returns:

Name	Type	Description
T	T	The currently stored value

Raises:

Type	Description
ValueError	If attempting to access before a value has been set

Note

This property provides read access to the stored value. Once set, the value is frozen and can only be changed using force_set_value().

__setattr__

__setattr__(name: str, value: Any) -> None

Prevent direct modification of protected attributes.

Overrides attribute setting to prevent direct modification of internal state attributes. These attributes should only be modified through appropriate methods.

Parameters:

Name	Type	Description	Default
name	str	Name of the attribute to set	required
value	Any	Value to set	required

Raises:

Type	Description
AttributeError	If attempting to modify protected attributes directly

Example

value = NamedValue("example")
value._stored_value = 42  # Raises AttributeError

Source code in src/data_handlers/values.py

def __setattr__(self, name: str, value: Any) -> None:
    """
    Prevent direct modification of protected attributes.

    Overrides attribute setting to prevent direct modification of internal
    state attributes. These attributes should only be modified through
    appropriate methods.

    Args:
        name (str): Name of the attribute to set
        value (Any): Value to set

    Raises:
        AttributeError: If attempting to modify protected attributes directly

    Example:
        ```python
        value = NamedValue("example")
        value._stored_value = 42  # Raises AttributeError
        ```
    """
    if name in ('_stored_value', '_state'):
        raise AttributeError(f"Cannot modify {name} directly. Use appropriate methods instead.")
    super().__setattr__(name, value)

append_to_value_list

append_to_value_list(l: NamedValueList) -> Self

Appends this value instance to a NamedValueList.

Convenience method for adding this value to a list while enabling method chaining.

Parameters:

Name	Type	Description	Default
l	NamedValueList	The list to append this value to	required

Returns:

Name	Type	Description
Self	Self	This instance for method chaining

Example

value_list = NamedValueList()
value = NamedValue("example", 42)
value.append_to_value_list(value_list).force_set_value(43)

Source code in src/data_handlers/values.py

def append_to_value_list(self, l: NamedValueList) -> Self:
    """
    Appends this value instance to a NamedValueList.

    Convenience method for adding this value to a list while enabling
    method chaining.

    Args:
        l (NamedValueList): The list to append this value to

    Returns:
        Self: This instance for method chaining

    Example:
        ```python
        value_list = NamedValueList()
        value = NamedValue("example", 42)
        value.append_to_value_list(value_list).force_set_value(43)
        ```
    """
    l.append(self)
    return self

force_set_value

force_set_value(new_value: T) -> None

Force set the value regardless of its current state.

This method bypasses the normal freezing mechanism and allows changing an already-set value.

Parameters:

Name	Type	Description	Default
new_value	T	New value to store	required

Raises:

Type	Description
TypeError	If value doesn't match the expected type T

Source code in src/data_handlers/values.py

def force_set_value(self, new_value: T) -> None:
    """
    Force set the value regardless of its current state.

    This method bypasses the normal freezing mechanism and allows
    changing an already-set value.

    Args:
        new_value (T): New value to store

    Raises:
        TypeError: If value doesn't match the expected type T
    """
    object.__setattr__(self, '_stored_value', NamedValueState.UNSET)
    object.__setattr__(self, '_state', NamedValueState.UNSET)

    # if new_value == 'not a series':
    #     breakpoint()
    self.value = new_value

model_dump

model_dump(**kwargs) -> dict[str, Any]

Custom serialization to include value state and stored value.

Extends the parent class serialization to include the value's state and stored value (if set) in the serialized data.

Parameters:

Name	Type	Description	Default
**kwargs		Additional arguments passed to parent serialization	{}

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Dictionary containing serialized state

Example

value = NamedValue("example", 42)
data = value.model_dump()
print(data)  # Contains 'state' and 'stored_value'

Source code in src/data_handlers/values.py

def model_dump(self, **kwargs) -> dict[str, Any]:
    """
    Custom serialization to include value state and stored value.

    Extends the parent class serialization to include the value's state
    and stored value (if set) in the serialized data.

    Args:
        **kwargs: Additional arguments passed to parent serialization

    Returns:
        dict[str, Any]: Dictionary containing serialized state

    Example:
        ```python
        value = NamedValue("example", 42)
        data = value.model_dump()
        print(data)  # Contains 'state' and 'stored_value'
        ```
    """
    data = super().model_dump(**kwargs)
    data['state'] = self._state
    if self._state == NamedValueState.SET:
        data['stored_value'] = self._stored_value
    return data

model_dump_json

model_dump_json(**kwargs) -> str

Custom JSON serialization of the named value.

Serializes the named value instance to a JSON string, including all state information and stored value.

Parameters:

Name	Type	Description	Default
**kwargs		JSON serialization options like indent, ensure_ascii, etc.	{}

Returns:

Name	Type	Description
str	str	JSON string representation

Example

value = NamedValue("example", 42)
json_str = value.model_dump_json(indent=2)
print(json_str)  # Pretty-printed JSON

Source code in src/data_handlers/values.py

def model_dump_json(self, **kwargs) -> str:
    """
    Custom JSON serialization of the named value.

    Serializes the named value instance to a JSON string, including
    all state information and stored value.

    Args:
        **kwargs: JSON serialization options like indent, ensure_ascii, etc.

    Returns:
        str: JSON string representation

    Example:
        ```python
        value = NamedValue("example", 42)
        json_str = value.model_dump_json(indent=2)
        print(json_str)  # Pretty-printed JSON
        ```
    """
    # Separate JSON-specific kwargs from model_dump kwargs
    json_kwargs = {k: v for k, v in kwargs.items() if k in {'indent', 'ensure_ascii', 'separators'}}
    dump_kwargs = {k: v for k, v in kwargs.items() if k not in json_kwargs}

    # Get model data with stored value
    data = self.model_dump(**dump_kwargs)
    return json.dumps(data, **json_kwargs)

model_validate classmethod

model_validate(data: Any) -> NamedValue

Custom deserialization to restore value state and stored value.

Reconstructs a NamedValue instance from serialized data, properly restoring both the value state and any stored value.

Parameters:

Name	Type	Description	Default
data	Any	Serialized data to deserialize	required

Returns:

Name	Type	Description
NamedValue	NamedValue	New instance with restored state

Example

data = {'name': 'example', 'state': 'set', 'stored_value': 42}
value = NamedValue.model_validate(data)
print(value.value)  # Outputs: 42

Source code in src/data_handlers/values.py

@classmethod
def model_validate(cls, data: Any) -> NamedValue:
    """
    Custom deserialization to restore value state and stored value.

    Reconstructs a NamedValue instance from serialized data, properly
    restoring both the value state and any stored value.

    Args:
        data (Any): Serialized data to deserialize

    Returns:
        NamedValue: New instance with restored state

    Example:
        ```python
        data = {'name': 'example', 'state': 'set', 'stored_value': 42}
        value = NamedValue.model_validate(data)
        print(value.value)  # Outputs: 42
        ```
    """
    if not isinstance(data, dict):
        return super().model_validate(data)

    data_copy = data.copy()
    state = NamedValueState(data_copy.pop('state', NamedValueState.UNSET))
    stored_value = data_copy.pop('stored_value', None)

    instance = super().model_validate(data_copy)

    # Only set the value if state was SET
    if state == NamedValueState.SET and stored_value is not None:
        instance.force_set_value(stored_value)

    return instance

model_validate_json classmethod

model_validate_json(json_data: str, **kwargs) -> NamedValue

Custom JSON deserialization to NamedValue instance.

Reconstructs a NamedValue instance from a JSON string representation, restoring all state and stored value information.

Parameters:

Name	Type	Description	Default
json_data	str	JSON string to deserialize	required
**kwargs		Additional validation options	{}

Returns:

Name	Type	Description
NamedValue	NamedValue	New instance with restored state

Example

json_str = '{"name": "example", "state": "set", "stored_value": 42}'
value = NamedValue.model_validate_json(json_str)
print(value.value)  # Outputs: 42

Source code in src/data_handlers/values.py

@classmethod
def model_validate_json(cls, json_data: str, **kwargs) -> NamedValue:
    """
    Custom JSON deserialization to NamedValue instance.

    Reconstructs a NamedValue instance from a JSON string representation,
    restoring all state and stored value information.

    Args:
        json_data (str): JSON string to deserialize
        **kwargs: Additional validation options

    Returns:
        NamedValue: New instance with restored state

    Example:
        ```python
        json_str = '{"name": "example", "state": "set", "stored_value": 42}'
        value = NamedValue.model_validate_json(json_str)
        print(value.value)  # Outputs: 42
        ```
    """
    data = json.loads(json_data)
    return cls.model_validate(data, **kwargs)

register_to_value_hash

register_to_value_hash(h: NamedValueHash) -> Self

Registers this value instance in a NamedValueHash.

Registers this value in the provided hash container. If the hash contains value overrides, this value's current value may be overridden during registration.

Parameters:

Name	Type	Description	Default
h	NamedValueHash	The hash to register this value in	required

Returns:

Name	Type	Description
Self	Self	This instance for method chaining

Example

value_hash = NamedValueHash()
value = NamedValue("example", 42)
value.register_to_value_hash(value_hash).force_set_value(43)

Source code in src/data_handlers/values.py

def register_to_value_hash(self, h: NamedValueHash) -> Self:
    """
    Registers this value instance in a NamedValueHash.

    Registers this value in the provided hash container. If the hash contains
    value overrides, this value's current value may be overridden during
    registration.

    Args:
        h (NamedValueHash): The hash to register this value in

    Returns:
        Self: This instance for method chaining

    Example:
        ```python
        value_hash = NamedValueHash()
        value = NamedValue("example", 42)
        value.register_to_value_hash(value_hash).force_set_value(43)
        ```
    """
    h.register_value(self)
    return self

NamedValueHash

Bases: NamedObjectHash

A type-safe dictionary for storing and managing NamedValue objects.

NamedValueHash provides a dictionary-like interface for managing a collection of NamedValue instances, using their names as keys. It ensures type safety and provides convenient methods for accessing and managing the stored values.

The hash maintains unique naming across all stored values and supports serialization/deserialization of the entire collection.

Attributes:

Name	Type	Description
_registry_category	str	Category identifier for object registration
model_config	ConfigDict	Pydantic configuration for model behavior

Example

value_hash = NamedValueHash()
value_hash.register_value(NamedValue("count", 42))
print(value_hash.get_raw_value("count"))  # Outputs: 42

get_raw_value

get_raw_value(name: str) -> Any

Get the underlying value by name.

Parameters:

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

Returns:

Name	Type	Description
Any	Any	The actual value stored in the named value

Raises:

Type	Description
KeyError	If no value exists with the given name
ValueError	If the value hasn't been set yet

Example

hash = NamedValueHash()
hash.register_value(NamedValue("price", 10.99))
print(hash.get_raw_value("price"))  # Outputs: 10.99

Source code in src/data_handlers/values.py

def get_raw_value(self, name: str) -> Any:
    """
    Get the underlying value by name.

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

    Returns:
        Any: The actual value stored in the named value

    Raises:
        KeyError: If no value exists with the given name
        ValueError: If the value hasn't been set yet

    Example:
        ```python
        hash = NamedValueHash()
        hash.register_value(NamedValue("price", 10.99))
        print(hash.get_raw_value("price"))  # Outputs: 10.99
        ```
    """
    return self.get_value(name).value

get_raw_values

get_raw_values() -> Iterable[Any]

Get the underlying values of all named values.

Returns:

Type	Description
Iterable[Any]	Iterable[Any]: Iterator over the actual values stored in each NamedValue

Example

hash = NamedValueHash()
hash.register_value(NamedValue("x", 1))
hash.register_value(NamedValue("y", 2))
print(list(hash.get_raw_values()))  # Outputs: [1, 2]

Source code in src/data_handlers/values.py

def get_raw_values(self) -> Iterable[Any]:
    """
    Get the underlying values of all named values.

    Returns:
        Iterable[Any]: Iterator over the actual values stored in each NamedValue

    Example:
        ```python
        hash = NamedValueHash()
        hash.register_value(NamedValue("x", 1))
        hash.register_value(NamedValue("y", 2))
        print(list(hash.get_raw_values()))  # Outputs: [1, 2]
        ```
    """
    return (val.value for val in self.get_values())

get_value

get_value(name: str) -> NamedValue

Retrieve a named value by its name.

Parameters:

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

Returns:

Name	Type	Description
NamedValue	NamedValue	The requested named value

Raises:

Type	Description
KeyError	If no value exists with the given name

Example

hash = NamedValueHash()
hash.register_value(NamedValue("price", 10.99))
price = hash.get_value("price")
print(price.value)  # Outputs: 10.99

Source code in src/data_handlers/values.py

def get_value(self, name: str) -> NamedValue:
    """
    Retrieve a named value by its name.

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

    Returns:
        NamedValue: The requested named value

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

    Example:
        ```python
        hash = NamedValueHash()
        hash.register_value(NamedValue("price", 10.99))
        price = hash.get_value("price")
        print(price.value)  # Outputs: 10.99
        ```
    """
    return self.get_object(name)

get_value_by_type

get_value_by_type(value_type: Type) -> Iterable[NamedValue]

Get all values of a specific type.

Parameters:

Name	Type	Description	Default
value_type	Type	Type to filter values by	required

Returns:

Type	Description
Iterable[NamedValue]	Iterable[NamedValue]: Values matching the specified type

Example

hash = NamedValueHash()
hash.register_value(NamedValue("x", 1))
hash.register_value(NamedValue("name", "test"))
integers = list(hash.get_value_by_type(int))

Source code in src/data_handlers/values.py

def get_value_by_type(self, value_type: Type) -> Iterable[NamedValue]:
    """
    Get all values of a specific type.

    Args:
        value_type (Type): Type to filter values by

    Returns:
        Iterable[NamedValue]: Values matching the specified type

    Example:
        ```python
        hash = NamedValueHash()
        hash.register_value(NamedValue("x", 1))
        hash.register_value(NamedValue("name", "test"))
        integers = list(hash.get_value_by_type(int))
        ```
    """
    return [val for val in self.get_values() if isinstance(val, value_type)]

get_value_names

get_value_names() -> Iterable[str]

Get names of all registered values.

Returns:

Type	Description
Iterable[str]	Iterable[str]: An iterator over all value names

Example

hash = NamedValueHash()
hash.register_value(NamedValue("x", 1))
hash.register_value(NamedValue("y", 2))
print(list(hash.get_value_names()))  # Outputs: ['x', 'y']

Source code in src/data_handlers/values.py

def get_value_names(self) -> Iterable[str]:
    """
    Get names of all registered values.

    Returns:
        Iterable[str]: An iterator over all value names

    Example:
        ```python
        hash = NamedValueHash()
        hash.register_value(NamedValue("x", 1))
        hash.register_value(NamedValue("y", 2))
        print(list(hash.get_value_names()))  # Outputs: ['x', 'y']
        ```
    """
    return self.get_object_names()

get_values

get_values() -> Iterable[NamedValue]

Get all registered named values.

Returns:

Type	Description
Iterable[NamedValue]	Iterable[NamedValue]: An iterator over all stored named values

Example

hash = NamedValueHash()
hash.register_value(NamedValue("x", 1))
hash.register_value(NamedValue("y", 2))
for value in hash.get_values():
    print(f"{value.name}: {value.value}")

Source code in src/data_handlers/values.py

def get_values(self) -> Iterable[NamedValue]:
    """
    Get all registered named values.

    Returns:
        Iterable[NamedValue]: An iterator over all stored named values

    Example:
        ```python
        hash = NamedValueHash()
        hash.register_value(NamedValue("x", 1))
        hash.register_value(NamedValue("y", 2))
        for value in hash.get_values():
            print(f"{value.name}: {value.value}")
        ```
    """
    return self.get_objects()

model_dump

model_dump(**kwargs) -> dict[str, Any]

Custom serialization to preserve stored values and their states.

Creates a dictionary representation of the hash that includes full serialization of all contained NamedValue objects, preserving their values and states.

Parameters:

Name	Type	Description	Default
**kwargs		Additional serialization options passed to all nested objects	{}

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Dictionary containing the complete hash state

Example

hash = NamedValueHash()
hash.register_value(NamedValue("x", 1))
data = hash.model_dump()
print(data['objects']['x']['stored_value'])  # Outputs: 1

Source code in src/data_handlers/values.py

def model_dump(self, **kwargs) -> dict[str, Any]:
    """
    Custom serialization to preserve stored values and their states.

    Creates a dictionary representation of the hash that includes full
    serialization of all contained NamedValue objects, preserving their
    values and states.

    Args:
        **kwargs: Additional serialization options passed to all nested objects

    Returns:
        dict[str, Any]: Dictionary containing the complete hash state

    Example:
        ```python
        hash = NamedValueHash()
        hash.register_value(NamedValue("x", 1))
        data = hash.model_dump()
        print(data['objects']['x']['stored_value'])  # Outputs: 1
        ```
    """
    data = super().model_dump(**kwargs)
    # Ensure each object's stored value is included
    if 'objects' in data:
        for name, obj in self.objects.items():
            if isinstance(obj, NamedValue):
                # Get the full dump including stored value
                obj_data = obj.model_dump(**kwargs)
                data['objects'][name] = obj_data
    return data

model_dump_json

model_dump_json(**kwargs) -> str

Custom JSON serialization of the entire hash.

Serializes the NamedValueHash instance and all contained NamedValue objects to a JSON string representation. Handles both the hash structure and the nested value serialization.

Parameters:

Name	Type	Description	Default
**kwargs		JSON serialization options such as: - indent: Number of spaces for pretty printing - ensure_ascii: Escape non-ASCII characters - separators: Tuple of (item_sep, key_sep) for custom formatting	{}

Returns:

Name	Type	Description
str	str	JSON string representation of the hash

Example

hash = NamedValueHash()
hash.register_value(NamedValue("x", 1))
json_str = hash.model_dump_json(indent=2)
print(json_str)  # Pretty-printed JSON with nested values

Source code in src/data_handlers/values.py

def model_dump_json(self, **kwargs) -> str:
    """
    Custom JSON serialization of the entire hash.

    Serializes the NamedValueHash instance and all contained NamedValue
    objects to a JSON string representation. Handles both the hash structure
    and the nested value serialization.

    Args:
        **kwargs: JSON serialization options such as:
            - indent: Number of spaces for pretty printing
            - ensure_ascii: Escape non-ASCII characters
            - separators: Tuple of (item_sep, key_sep) for custom formatting

    Returns:
        str: JSON string representation of the hash

    Example:
        ```python
        hash = NamedValueHash()
        hash.register_value(NamedValue("x", 1))
        json_str = hash.model_dump_json(indent=2)
        print(json_str)  # Pretty-printed JSON with nested values
        ```
    """
    # Separate JSON-specific kwargs from model_dump kwargs
    json_kwargs = {k: v for k, v in kwargs.items() if k in {'indent', 'ensure_ascii', 'separators'}}
    dump_kwargs = {k: v for k, v in kwargs.items() if k not in json_kwargs}

    # Get model data
    data = self.model_dump(**dump_kwargs)
    # Serialize to JSON
    return json.dumps(data, **json_kwargs)

model_validate classmethod

model_validate(data: Any) -> NamedValueHash

Custom validation to restore hash state from serialized data.

Reconstructs a NamedValueHash instance from serialized data, including all contained NamedValue objects with their values and states.

Parameters:

Name	Type	Description	Default
data	Any	Serialized data to deserialize. Should be a dictionary containing an 'objects' key with serialized NamedValue instances	required

Returns:

Name	Type	Description
NamedValueHash	NamedValueHash	New instance with all values restored

Example

data = {
    'objects': {
        'x': {'name': 'x', 'type': 'NamedValue', 'stored_value': 1}
    }
}
hash = NamedValueHash.model_validate(data)
print(hash.get_raw_value('x'))  # Outputs: 1

Source code in src/data_handlers/values.py

@classmethod
def model_validate(cls, data: Any) -> NamedValueHash:
    """
    Custom validation to restore hash state from serialized data.

    Reconstructs a NamedValueHash instance from serialized data, including
    all contained NamedValue objects with their values and states.

    Args:
        data (Any): Serialized data to deserialize. Should be a dictionary
            containing an 'objects' key with serialized NamedValue instances

    Returns:
        NamedValueHash: New instance with all values restored

    Example:
        ```python
        data = {
            'objects': {
                'x': {'name': 'x', 'type': 'NamedValue', 'stored_value': 1}
            }
        }
        hash = NamedValueHash.model_validate(data)
        print(hash.get_raw_value('x'))  # Outputs: 1
        ```
    """
    if not isinstance(data, dict):
        return super().model_validate(data)

    instance = cls()

    # Process each object in the data
    for name, obj_data in data.get('objects', {}).items():
        if isinstance(obj_data, dict):
            obj_type = obj_data.get('type')
            if obj_type:
                # Get the appropriate class from registry
                value_class = ObjectRegistry.get(cls._registry_category, obj_type)
                # Create and validate the object with its stored value
                value_obj = value_class.model_validate(obj_data)
                instance.register_value(value_obj)

    return instance

model_validate_json classmethod

model_validate_json(json_data: str, **kwargs) -> NamedValueHash

Custom JSON deserialization to NamedValueHash instance.

Reconstructs a NamedValueHash instance from a JSON string representation, including all contained NamedValue objects with their complete state.

Parameters:

Name	Type	Description	Default
json_data	str	JSON string containing serialized hash data	required
**kwargs		Additional validation options for nested objects	{}

Returns:

Name	Type	Description
NamedValueHash	NamedValueHash	New instance with all values restored

Example

json_str = '''
{
    "objects": {
        "x": {"name": "x", "type": "NamedValue", "stored_value": 1}
    }
}
'''
hash = NamedValueHash.model_validate_json(json_str)
print(hash.get_raw_value('x'))  # Outputs: 1

Source code in src/data_handlers/values.py

@classmethod
def model_validate_json(cls, json_data: str, **kwargs) -> NamedValueHash:
    """
    Custom JSON deserialization to NamedValueHash instance.

    Reconstructs a NamedValueHash instance from a JSON string representation,
    including all contained NamedValue objects with their complete state.

    Args:
        json_data (str): JSON string containing serialized hash data
        **kwargs: Additional validation options for nested objects

    Returns:
        NamedValueHash: New instance with all values restored

    Example:
        ```python
        json_str = '''
        {
            "objects": {
                "x": {"name": "x", "type": "NamedValue", "stored_value": 1}
            }
        }
        '''
        hash = NamedValueHash.model_validate_json(json_str)
        print(hash.get_raw_value('x'))  # Outputs: 1
        ```
    """
    data = json.loads(json_data)
    return cls.model_validate(data, **kwargs)

register_value

register_value(value: NamedValue) -> Self

Register a named value in the hash.

Parameters:

Name	Type	Description	Default
value	NamedValue	The value to register	required

Returns:

Name	Type	Description
Self	Self	Returns self for method chaining

Raises:

Type	Description
ValueError	If a value with the same name already exists

Example

hash = NamedValueHash()
value = NamedValue("price", 10.99)
hash.register_value(value).register_value(NamedValue("qty", 5))

Source code in src/data_handlers/values.py

def register_value(self, value: NamedValue) -> Self:
    """
    Register a named value in the hash.

    Args:
        value (NamedValue): The value to register

    Returns:
        Self: Returns self for method chaining

    Raises:
        ValueError: If a value with the same name already exists

    Example:
        ```python
        hash = NamedValueHash()
        value = NamedValue("price", 10.99)
        hash.register_value(value).register_value(NamedValue("qty", 5))
        ```
    """
    return self.register_object(value)

set_raw_value

set_raw_value(name: str, value: Any) -> None

Set the underlying value for a named value.

Parameters:

Name	Type	Description	Default
name	str	Name of the value to update	required
value	Any	New value to set	required

Raises:

Type	Description
KeyError	If no value exists with the given name
TypeError	If value type doesn't match the expected type

Example

hash = NamedValueHash()
hash.register_value(NamedValue("price", 10.99))
hash.set_raw_value("price", 11.99)

Source code in src/data_handlers/values.py

def set_raw_value(self, name: str, value: Any) -> None:
    """
    Set the underlying value for a named value.

    Args:
        name (str): Name of the value to update
        value (Any): New value to set

    Raises:
        KeyError: If no value exists with the given name
        TypeError: If value type doesn't match the expected type

    Example:
        ```python
        hash = NamedValueHash()
        hash.register_value(NamedValue("price", 10.99))
        hash.set_raw_value("price", 11.99)
        ```
    """
    self.get_value(name).value = value

NamedValueList

Bases: NamedObjectList

An ordered list container for managing NamedValue objects.

NamedValueList maintains an ordered collection of NamedValue objects while providing type safety and convenient access methods. It preserves insertion order while also allowing access by name.

Attributes:

Name	Type	Description
_registry_category	str	Category identifier for object registration
objects	List[SerializeAsAny[InstanceOf[NamedValue]]]	The list of stored values

Example

value_list = NamedValueList()
value_list.append(NamedValue("first", 1))
value_list.append(NamedValue("second", 2))
print([v.value for v in value_list])  # Outputs: [1, 2]

__getitem__

__getitem__(idx: int) -> NamedValue

Get a named value by its index in the list.

Parameters:

Name	Type	Description	Default
idx	int	Index of the named value to retrieve	required

Returns:

Name	Type	Description
NamedValue	NamedValue	The named value at the specified index

Raises:

Type	Description
IndexError	If the index is out of range

Example

value_list = NamedValueList()
value_list.append(NamedValue(name="price", value=10.5))
first_value = value_list[0] # Get first named value

Source code in src/data_handlers/values.py

def __getitem__(self, idx: int) -> NamedValue:
    """Get a named value by its index in the list.

    Args:
        idx (int): Index of the named value to retrieve

    Returns:
        NamedValue: The named value at the specified index

    Raises:
        IndexError: If the index is out of range

    Example:
        ```python
        value_list = NamedValueList()
        value_list.append(NamedValue(name="price", value=10.5))
        first_value = value_list[0] # Get first named value
        ```
    """
    return super().__getitem__(idx)

append

append(value: NamedValue) -> Self

Append a named value to the end of the list.

Parameters:

Name	Type	Description	Default
value	NamedValue	Named value to append	required

Returns:

Name	Type	Description
Self	Self	The list instance for method chaining

Example

value_list = NamedValueList()
value_list.append(NamedValue("x", 1)).append(NamedValue("y", 2))

Source code in src/data_handlers/values.py

def append(self, value: NamedValue) -> Self:
    """
    Append a named value to the end of the list.

    Args:
        value (NamedValue): Named value to append

    Returns:
        Self: The list instance for method chaining

    Example:
        ```python
        value_list = NamedValueList()
        value_list.append(NamedValue("x", 1)).append(NamedValue("y", 2))
        ```
    """
    return super().append(value)

extend

extend(values: Iterable[NamedValue]) -> Self

Extend the list with multiple named values.

Parameters:

Name	Type	Description	Default
values	Iterable[NamedValue]	Collection of named values to add	required

Returns:

Name	Type	Description
Self	Self	The list instance for method chaining

Example

value_list = NamedValueList()
new_values = [NamedValue("x", 1), NamedValue("y", 2)]
value_list.extend(new_values)

Source code in src/data_handlers/values.py

def extend(self, values: Iterable[NamedValue]) -> Self:
    """
    Extend the list with multiple named values.

    Args:
        values (Iterable[NamedValue]): Collection of named values to add

    Returns:
        Self: The list instance for method chaining

    Example:
        ```python
        value_list = NamedValueList()
        new_values = [NamedValue("x", 1), NamedValue("y", 2)]
        value_list.extend(new_values)
        ```
    """
    return super().extend(values)

get_value

get_value(name: str) -> NamedValue

Get a registered named value by name.

Parameters:

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

Returns:

Name	Type	Description
NamedValue	NamedValue	The requested named value

Raises:

Type	Description
KeyError	If no value exists with the given name

Example

value_list = NamedValueList()
value_list.append(NamedValue("x", 1))
x = value_list.get_value("x")
print(x.value)  # Outputs: 1

Source code in src/data_handlers/values.py

def get_value(self, name: str) -> NamedValue:
    """
    Get a registered named value by name.

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

    Returns:
        NamedValue: The requested named value

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

    Example:
        ```python
        value_list = NamedValueList()
        value_list.append(NamedValue("x", 1))
        x = value_list.get_value("x")
        print(x.value)  # Outputs: 1
        ```
    """
    return self.get_object(name)

get_value_by_type

get_value_by_type(value_type: Type) -> Iterable[NamedValue]

Get all values whose stored value is of a specific type.

Parameters:

Name	Type	Description	Default
value_type	Type	Type to filter values by	required

Returns:

Type	Description
Iterable[NamedValue]	Iterable[NamedValue]: Values whose stored value matches the specified type

Example

value_list = NamedValueList()
value_list.append(NamedValue("x", 1))
value_list.append(NamedValue("name", "test"))
integers = list(value_list.get_value_by_type(int))

Source code in src/data_handlers/values.py

def get_value_by_type(self, value_type: Type) -> Iterable[NamedValue]:
    """
    Get all values whose stored value is of a specific type.

    Args:
        value_type (Type): Type to filter values by

    Returns:
        Iterable[NamedValue]: Values whose stored value matches the specified type

    Example:
        ```python
        value_list = NamedValueList()
        value_list.append(NamedValue("x", 1))
        value_list.append(NamedValue("name", "test"))
        integers = list(value_list.get_value_by_type(int))
        ```
    """
    for value in self.get_values():
        try:
            if isinstance(value.value, value_type):
                yield value
        except ValueError:
            # Skip unset values
            continue

get_values

get_values() -> Iterable[NamedValue]

Get all registered named values.

Returns:

Type	Description
Iterable[NamedValue]	Iterable[NamedValue]: Iterator over all stored named values

Example

value_list = NamedValueList()
value_list.extend([NamedValue("x", 1), NamedValue("y", 2)])
for value in value_list.get_values():
    print(f"{value.name}: {value.value}")

Source code in src/data_handlers/values.py

def get_values(self) -> Iterable[NamedValue]:
    """
    Get all registered named values.

    Returns:
        Iterable[NamedValue]: Iterator over all stored named values

    Example:
        ```python
        value_list = NamedValueList()
        value_list.extend([NamedValue("x", 1), NamedValue("y", 2)])
        for value in value_list.get_values():
            print(f"{value.name}: {value.value}")
        ```
    """
    return self.get_objects()

model_dump

model_dump(**kwargs) -> dict[str, Any]

Custom serialization to preserve stored values.

Extends the parent class serialization to ensure proper serialization of all stored named values and their states.

Parameters:

Name	Type	Description	Default
**kwargs		Additional serialization options	{}

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Dictionary containing serialized state

Source code in src/data_handlers/values.py

def model_dump(self, **kwargs) -> dict[str, Any]:
    """
    Custom serialization to preserve stored values.

    Extends the parent class serialization to ensure proper serialization
    of all stored named values and their states.

    Args:
        **kwargs: Additional serialization options

    Returns:
        dict[str, Any]: Dictionary containing serialized state
    """
    data = super().model_dump(**kwargs)
    if 'objects' in data:
        # Ensure each object's stored value is included
        data['objects'] = [
            obj.model_dump(**kwargs) if isinstance(obj, NamedValue) else obj
            for obj in self.objects
        ]
    return data

model_dump_json

model_dump_json(**kwargs) -> str

Custom JSON serialization of the value list.

Serializes the NamedValueList instance and all contained NamedValue objects to a JSON string representation. Preserves the order of values and their complete state.

Parameters:

Name	Type	Description	Default
**kwargs		JSON serialization options such as: - indent: Number of spaces for pretty printing - ensure_ascii: Escape non-ASCII characters - separators: Tuple of (item_sep, key_sep) for custom formatting	{}

Returns:

Name	Type	Description
str	str	JSON string representation of the list

Example

value_list = NamedValueList()
value_list.append(NamedValue("x", 1))
value_list.append(NamedValue("y", 2))
json_str = value_list.model_dump_json(indent=2)
print(json_str)  # Pretty-printed JSON with ordered values

Source code in src/data_handlers/values.py

def model_dump_json(self, **kwargs) -> str:
    """
    Custom JSON serialization of the value list.

    Serializes the NamedValueList instance and all contained NamedValue
    objects to a JSON string representation. Preserves the order of values
    and their complete state.

    Args:
        **kwargs: JSON serialization options such as:
            - indent: Number of spaces for pretty printing
            - ensure_ascii: Escape non-ASCII characters
            - separators: Tuple of (item_sep, key_sep) for custom formatting

    Returns:
        str: JSON string representation of the list

    Example:
        ```python
        value_list = NamedValueList()
        value_list.append(NamedValue("x", 1))
        value_list.append(NamedValue("y", 2))
        json_str = value_list.model_dump_json(indent=2)
        print(json_str)  # Pretty-printed JSON with ordered values
        ```
    """
    # Separate JSON-specific kwargs from model_dump kwargs
    json_kwargs = {k: v for k, v in kwargs.items() if k in {'indent', 'ensure_ascii', 'separators'}}
    dump_kwargs = {k: v for k, v in kwargs.items() if k not in json_kwargs}

    # Get model data
    data = self.model_dump(**dump_kwargs)
    # Serialize to JSON
    return json.dumps(data, **json_kwargs)

model_validate classmethod

model_validate(data: Any) -> NamedValueList

Custom validation to restore stored values.

Reconstructs a NamedValueList instance from serialized data, properly restoring all contained named values and their states.

Parameters:

Name	Type	Description	Default
data	Any	Serialized data to deserialize	required

Returns:

Name	Type	Description
NamedValueList	NamedValueList	New instance with restored values

Source code in src/data_handlers/values.py

@classmethod
def model_validate(cls, data: Any) -> NamedValueList:
    """
    Custom validation to restore stored values.

    Reconstructs a NamedValueList instance from serialized data,
    properly restoring all contained named values and their states.

    Args:
        data (Any): Serialized data to deserialize

    Returns:
        NamedValueList: New instance with restored values
    """
    if not isinstance(data, dict):
        return super().model_validate(data)

    instance = cls()

    # Process each object in the data
    for obj_data in data.get('objects', []):
        if isinstance(obj_data, dict):
            obj_type = obj_data.get('type')
            if obj_type:
                # Get the appropriate class from registry
                value_class = ObjectRegistry.get(cls._registry_category, obj_type)
                # Create and validate the object
                value_obj = value_class.model_validate(obj_data)
                instance.append(value_obj)

    return instance

model_validate_json classmethod

model_validate_json(json_data: str, **kwargs) -> NamedValueList

Custom JSON deserialization to NamedValueList instance.

Reconstructs a NamedValueList instance from a JSON string representation, preserving the order of values and restoring their complete state.

Parameters:

Name	Type	Description	Default
json_data	str	JSON string containing serialized list data	required
**kwargs		Additional validation options for nested objects	{}

Returns:

Name	Type	Description
NamedValueList	NamedValueList	New instance with all values restored in order

Example

json_str = '''
{
    "objects": [
        {"name": "x", "type": "NamedValue", "stored_value": 1},
        {"name": "y", "type": "NamedValue", "stored_value": 2}
    ]
}
'''
value_list = NamedValueList.model_validate_json(json_str)
print([v.value for v in value_list])  # Outputs: [1, 2]

Source code in src/data_handlers/values.py

@classmethod
def model_validate_json(cls, json_data: str, **kwargs) -> NamedValueList:
    """
    Custom JSON deserialization to NamedValueList instance.

    Reconstructs a NamedValueList instance from a JSON string representation,
    preserving the order of values and restoring their complete state.

    Args:
        json_data (str): JSON string containing serialized list data
        **kwargs: Additional validation options for nested objects

    Returns:
        NamedValueList: New instance with all values restored in order

    Example:
        ```python
        json_str = '''
        {
            "objects": [
                {"name": "x", "type": "NamedValue", "stored_value": 1},
                {"name": "y", "type": "NamedValue", "stored_value": 2}
            ]
        }
        '''
        value_list = NamedValueList.model_validate_json(json_str)
        print([v.value for v in value_list])  # Outputs: [1, 2]
        ```
    """
    data = json.loads(json_data)
    return cls.model_validate(data, **kwargs)

register_value

register_value(value: NamedValue) -> Self

Register a named value to the list.

Similar to append but uses the register_object method internally, which may perform additional validation.

Parameters:

Name	Type	Description	Default
value	NamedValue	Named value to register	required

Returns:

Name	Type	Description
Self	Self	The list instance for method chaining

Example

value_list = NamedValueList()
value_list.register_value(NamedValue("x", 1))

Source code in src/data_handlers/values.py

def register_value(self, value: NamedValue) -> Self:
    """
    Register a named value to the list.

    Similar to append but uses the register_object method internally,
    which may perform additional validation.

    Args:
        value (NamedValue): Named value to register

    Returns:
        Self: The list instance for method chaining

    Example:
        ```python
        value_list = NamedValueList()
        value_list.register_value(NamedValue("x", 1))
        ```
    """
    return self.register_object(value)

NamedValueState

Bases: str, Enum

State enumeration for NamedValue objects.

This enum tracks whether a named value has been set or remains unset. Once set, values are typically frozen unless explicitly forced to change.

Attributes:

Name	Type	Description
UNSET		Indicates no value has been set yet
SET		Indicates value has been set and is frozen

__repr__

__repr__() -> str

Get string representation for debugging.

Returns:

Name	Type	Description
str	str	The state value as a string ("unset" or "set")

Source code in src/data_handlers/values.py

def __repr__(self) -> str:
    """
    Get string representation for debugging.

    Returns:
        str: The state value as a string ("unset" or "set")
    """
    return self.value  # Returns just "unset" or "set"

__str__

__str__() -> str

Convert state to string representation.

Returns:

Name	Type	Description
str	str	The state value as a string ("unset" or "set")

Source code in src/data_handlers/values.py

def __str__(self) -> str:
    """
    Convert state to string representation.

    Returns:
        str: The state value as a string ("unset" or "set")
    """
    return self.value  # Returns just "unset" or "set"