haive.core.common.mixins.general.state

State management mixin for tracking object state changes with history.

This module provides a Pydantic-based mixin for adding state tracking capabilities to any BaseModel. It maintains a current state string and a complete history of all state changes with timestamps and optional reasons.

Usage:

from pydantic import BaseModel from haive.core.common.mixins.general.state import StateMixin

class MyComponent(StateMixin, BaseModel):

name: str

# Create component and change states component = MyComponent(name=”test”) component.change_state(“processing”, “Starting work”) component.change_state(“complete”, “Finished successfully”)

# Check current state if component.is_in_state(“complete”):

print(“Component is done!”)

# Review state history for change in component.get_state_changes():

print(f”{change[‘timestamp’]}: {change[‘from_state’]} -> {change[‘to_state’]}”)

Classes

StateMixin

Mixin for state tracking with validation and comprehensive history.

Module Contents

class haive.core.common.mixins.general.state.StateMixin(/, **data)

Bases: pydantic.BaseModel

Mixin for state tracking with validation and comprehensive history.

This mixin adds state management capabilities to Pydantic models, allowing objects to track their current state and maintain a complete history of state transitions with timestamps and optional reasons.

The mixin is designed to be composable with other BaseModel classes and provides thread-safe state transitions with automatic history tracking.

Parameters:

data (Any)

state

Current state of the object (defaults to “active”).

state_history

Chronological list of all state changes with metadata.

Examples

>>> class Task(StateMixin, BaseModel):
...     name: str
>>> task = Task(name="Process data")
>>> task.change_state("running", "Starting execution")
>>> task.change_state("complete", "Finished successfully")
>>> task.is_in_state("complete")
True
>>> len(task.get_state_changes())
2

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

change_state(new_state, reason=None)

Change state and automatically track the transition in history.

This method updates the current state and records the transition in the state history with a timestamp and optional reason.

Parameters:

• new_state (str) – The new state to transition to.

• reason (str | None) – Optional explanation for the state change.

Return type:

None

Examples

>>> task.change_state("paused", "Waiting for user input")
>>> task.state
'paused'

get_state_changes()

Get a copy of the complete state change history.

Returns:

• from_state: Previous state

• to_state: New state

• timestamp: When the change occurred

• reason: Optional explanation for the change

Return type:

List of state change records, each containing

Examples

>>> changes = task.get_state_changes()
>>> print(changes[0]["from_state"])
'active'

is_in_state(state)

Check if the object is currently in the specified state.

Parameters:

state (str) – State name to check against current state.

Returns:

True if current state matches the specified state, False otherwise.

Return type:

bool

Examples

>>> task.is_in_state("complete")
False
>>> task.change_state("complete")
>>> task.is_in_state("complete")
True