flowstab.state_tracking

State tracking utilities for a multi-step analysis

This sub-module implements a state machine system for analysis classes, enabling fine-grained tracking of computation progress through method and property transitions. It provides a metaclass (StateMeta) and decorator (register) that augment classes with state management, enforcing method order and prerequisite satisfaction based on user-defined enumerated states.

Usage Example

To use state tracking in a custom analysis class:

>>> from enum import Enum
>>> from flowstab.state_tracking import StateMeta, OrderedEnum
>>>
>>> class MyStates(OrderedEnum):
>>>     INIT = 0
>>>     STEP1 = 1
>>>     STEP2 = 2
>>>
>>> class MyAnalysis(metaclass=StateMeta, states=MyStates):
>>>     @property
>>>     def data(self):
>>>         '''Access the data attribute.'''
>>>         return self._data
>>>
>>>     @register(next_state=MyStates.STEP1)
>>>     @data.setter
>>>     def data(self, value):
>>>         '''Set the data attribute.'''
>>>         self._data = value
>>>
>>>     @register(minimal_state=MyStates.INIT, next_state=MyStates.STEP1)
>>>     def do_step_1(self):
>>>         '''Perform analysis step requiring data.'''
>>>         pass
>>>
>>>     @register(minimal_state=MyStates.STEP1, next_state=MyStates.STEP2)
>>>     def do_step_2(self):
>>>         '''Perform analysis step requiring data.'''
>>>         pass

This setup ensures:

• method do_step_1 is run first

• whenever data is set, run_step_2 must be re-run

• run_step_2 can only be run after run_step_1 was run once and after data is set.

Classes

OrderedEnum	Enum with total ordering based on values.
State	State machine for managing analysis workflow progress.
StateMeta	Metaclass for state-tracked analysis classes.

Module Contents

class flowstab.state_tracking.OrderedEnum

Bases: enum.Enum

Enum with total ordering based on values.

Allows comparison operators (<, <=, >, >=, ==, !=) between enum members, using their assigned values.

__eq__(other)

__hash__()

__lt__(other)

__str__()

class flowstab.state_tracking.State(states: OrderedEnum, properties_required: dict | None = None, properties_set: dict | None = None, methods_required: dict | None = None, **kwargs)

State machine for managing analysis workflow progress.

Holds information about the current state, required properties, and required methods. Used internally by classes using StateMeta.

Initialize the State object.

Parameters:

• states (Enum) – Enumeration of possible states.

• properties_required (dict or None, optional) – Mapping of state to required property names.

• properties_set (dict or None, optional) – Mapping of property names to their set status.

• methods_required (dict or None, optional) – Mapping of state to required method names.

• **kwargs – Additional attributes to set.

current

methods_required

property missing_parameters

List of required parameters not yet set for the current state.

Returns:

Property names still required for the current state.

Return type:

list

property next

Get required properties still missing and the next method for the state.

Returns:

(list of missing properties, next method name or None)

Return type:

tuple

properties_required

properties_set

class flowstab.state_tracking.StateMeta

Bases: type

Metaclass for state-tracked analysis classes.

This metaclass augments target classes with state management, attaching state tracking attributes and logic based on user-defined states and decorators.

Create a new class with state tracking.

Parameters:

• name (str) – Class name.

• bases (tuple) – Base classes.

• namespace (dict) – Class namespace.

• states (Enum) – Enum defining possible states.

attach_state(namespace)

Attach the state property and custom __init__ to the class.

Parameters:

namespace (dict) – The class namespace to mutate.

classmethod init_state(namespace, states: enum.Enum)

Populate the given namespace with state tracking metadata.

Parameters:

• namespace (dict) – The class namespace to mutate.

• states (Enum) – Enum of possible states.

static register(*, next_state: enum.Enum, minimal_state: enum.Enum | None = None, ignore_none: bool = True)

Decorator to register a method or property setter for state management.

Parameters:

• next_state (Enum) – State the object will be in after successful call.

• minimal_state (Enum or None, optional) – Minimal state required to execute the method/setter.

• ignore_none (bool, optional) – If True, value=None will mark the property unset.

Returns:

Decorated method or property setter.

Return type:

function