sda.dashboard.state
===================

.. py:module:: sda.dashboard.state

.. autoapi-nested-parse::

   State Management Package.

   =========================

   Consolidated state management for the SDA Dashboard.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /_api/sda/dashboard/state/manager/index


Classes
-------

.. autoapisummary::

   sda.dashboard.state.DashboardState
   sda.dashboard.state.StateDefinition
   sda.dashboard.state.StateManager
   sda.dashboard.state.StateScope


Functions
---------

.. autoapisummary::

   sda.dashboard.state.get_state_manager


Package Contents
----------------

.. py:class:: DashboardState(verbose = False)

   Centralized dashboard state management.


   .. py:attribute:: verbose
      :value: False



   .. py:method:: define_state(definition)

      Define a new state variable.

      :param definition: State variable definition
      :type definition: :py:class:`StateDefinition`



   .. py:method:: create_stores(initial_values = None)

      Create Dash Store components for all defined state.

      :param initial_values: Initial values to set in stores
      :type initial_values: :py:class:`Dict[str`, :py:class:`Any]`, *optional*

      :returns: List of Store components to add to layout
      :rtype: :py:class:`List[dcc.Store]`



   .. py:method:: get_store_id(state_key)

      Get the store ID for a state key.

      :param state_key: State key name
      :type state_key: :py:class:`str`

      :returns: Dash Store component ID
      :rtype: :py:class:`str`



   .. py:method:: validate_state(state_key, value)

      Validate a state value.

      :param state_key: State key name
      :type state_key: :py:class:`str`
      :param value: Value to validate
      :type value: :py:class:`Any`

      :returns: Whether the value is valid
      :rtype: :py:class:`bool`



   .. py:method:: get_dependencies(state_key)

      Get dependencies for a state variable.

      :param state_key: State key name
      :type state_key: :py:class:`str`

      :returns: List of dependency state keys
      :rtype: :py:class:`List[str]`



   .. py:method:: add_watcher(state_key, callback)

      Add a watcher function for state changes.

      :param state_key: State key to watch
      :type state_key: :py:class:`str`
      :param callback: Function to call when state changes
      :type callback: :py:class:`callable`



.. py:class:: StateDefinition

   Definition of a state variable.


   .. py:attribute:: key
      :type:  str


   .. py:attribute:: default_value
      :type:  Any
      :value: None



   .. py:attribute:: scope
      :type:  StateScope


   .. py:attribute:: description
      :type:  str
      :value: ''



   .. py:attribute:: validation_fn
      :type:  Optional[Callable]
      :value: None



   .. py:attribute:: dependencies
      :type:  List[str]
      :value: []



.. py:class:: StateManager(dashboard_state, verbose = False)

   High-level state management interface.


   .. py:attribute:: state


   .. py:attribute:: verbose
      :value: False



   .. py:method:: batch_update(updates)

      Batch multiple state updates.

      :param updates: Dictionary of state_key: new_value pairs
      :type updates: :py:class:`Dict[str`, :py:class:`Any]`

      :returns: List of validation errors, if any
      :rtype: :py:class:`List[str]`



   .. py:method:: get_update_queue()

      Get and clear the update queue.

      :returns: Queued updates
      :rtype: :py:class:`List[Dict[str`, :py:class:`Any]]`



   .. py:method:: create_consolidated_layout()

      Create consolidated state layout component.

      :returns: Div containing all state stores
      :rtype: :py:class:`html.Div`



.. py:class:: StateScope(*args, **kwds)

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


   Scope of state storage.


   .. py:attribute:: SESSION
      :value: 'session'



   .. py:attribute:: LOCAL
      :value: 'local'



   .. py:attribute:: MEMORY
      :value: 'memory'



.. py:function:: get_state_manager(verbose = False)

   Get the global state manager instance.

   :param verbose: Whether to enable verbose logging
   :type verbose: :py:class:`bool`

   :returns: Global state manager instance
   :rtype: :py:class:`StateManager`