flowstab.state_tracking
=======================

.. py:module:: flowstab.state_tracking

.. autoapi-nested-parse::

   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
-------

.. autoapisummary::

   flowstab.state_tracking.OrderedEnum
   flowstab.state_tracking.State
   flowstab.state_tracking.StateMeta


Module Contents
---------------

.. py:class:: OrderedEnum

   Bases: :py:obj:`enum.Enum`


   Enum with total ordering based on values.

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


   .. py:method:: __eq__(other)


   .. py:method:: __hash__()


   .. py:method:: __lt__(other)


   .. py:method:: __str__()


.. py:class:: 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.

   :param states: Enumeration of possible states.
   :type states: Enum
   :param properties_required: Mapping of state to required property names.
   :type properties_required: dict or None, optional
   :param properties_set: Mapping of property names to their set status.
   :type properties_set: dict or None, optional
   :param methods_required: Mapping of state to required method names.
   :type methods_required: dict or None, optional
   :param \*\*kwargs: Additional attributes to set.


   .. py:attribute:: current


   .. py:attribute:: methods_required


   .. py:property:: missing_parameters

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

      :returns: Property names still required for the current state.
      :rtype: list


   .. py:property:: next

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

      :returns: (list of missing properties, next method name or None)
      :rtype: tuple


   .. py:attribute:: properties_required


   .. py:attribute:: properties_set


.. py:class:: StateMeta

   Bases: :py:obj:`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.

   :param name: Class name.
   :type name: str
   :param bases: Base classes.
   :type bases: tuple
   :param namespace: Class namespace.
   :type namespace: dict
   :param states: Enum defining possible states.
   :type states: Enum


   .. py:method:: attach_state(namespace)

      Attach the state property and custom __init__ to the class.

      :param namespace: The class namespace to mutate.
      :type namespace: dict



   .. py:method:: init_state(namespace, states: enum.Enum)
      :classmethod:


      Populate the given namespace with state tracking metadata.

      :param namespace: The class namespace to mutate.
      :type namespace: dict
      :param states: Enum of possible states.
      :type states: Enum



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


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

      :param next_state: State the object will be in after successful call.
      :type next_state: Enum
      :param minimal_state: Minimal state required to execute the method/setter.
      :type minimal_state: Enum or None, optional
      :param ignore_none: If True, value=None will mark the property unset.
      :type ignore_none: bool, optional

      :returns: Decorated method or property setter.
      :rtype: function