cligram.state_manager

State management module for presistent application data.

class cligram.state_manager.JsonState

Bases: State

JSON-based state implementation.

changed()

Check if state changed since last reset.

Return type:

bool

Returns:

True if state has changed, False otherwise

data: Dict[str, Any]

Current state data

ensure_schema(data)

Ensure current data matches schema.

Parameters:

data (Dict[str, Any]) – Data to validate

Raises:

ValueError – If data does not match schema

Return type:

None

export()

Export current state data.

Return type:

str

Returns:

Current state data

get_hash()

Get a hash of the current state data.

Return type:

str

load(data)

Load state data from JSON string or dictionary.

Parameters:

data (Union[Dict[str, Any], str, None]) – Data to load into state, either as a dict or JSON string

Raises:

RuntimeError – If there are unsaved changes

Return type:

None

static parse(content)

Parse JSON state contents.

Parameters:

content (str) – Content of the state file

Return type:

Union[Dict[str, Any], list]

Returns:

Parsed state data

Raises:

ValueError – If file content is invalid

schema: Optional[Dict[str, Any]]

Optional schema for data validation

set_changed(changed)

Set the changed status of the state.

This method is used internally to mark the state as changed or unchanged.

Parameters:

changed (bool) – True to mark state as changed, False to mark as unchanged

Return type:

None

suffix: str = '.json'

File suffix for JSON state files

classmethod verify_structure(data, schema, path='')

Recursively verify that data matches the provided schema.

Parameters:

• data (Any) – Data to verify

• schema (Dict[str, Any]) – Schema definition

• path (str) – Current data path for error messages

Return type:

bool

Returns:

True if data matches schema, False otherwise

class cligram.state_manager.State

Bases: ABC

Abstract base class for state storage.

Defines interface for loading, exporting, and tracking changes to state data.

abstractmethod changed()

Check if state changed since last reset.

Return type:

bool

Returns:

True if state has changed, False otherwise

abstractmethod export()

Export current state data.

Return type:

Any

Returns:

Current state data

abstractmethod load(data)

Load state data.

Parameters:

data (Any) – Data to load into state

Return type:

None

static parse(content)

Parse state input contents.

Subclasses may override this method to implement custom parsing logic.

The default implementation returns the content as-is.

Parameters:

content (str) – Content of the state file

Return type:

Any

Returns:

Parsed state data, could be passed to load() method

abstractmethod set_changed(changed)

Set the changed status of the state.

This method is used internally to mark the state as changed or unchanged.

Parameters:

changed (bool) – True to mark state as changed, False to mark as unchanged

Return type:

None

suffix: str = '.state'

File suffix for state files

class cligram.state_manager.StateManager(data_dir, backup_dir=None)

Bases: object

Manages persistent application state and handles file-based storage operations.

Provides methods to register state types, load/save states, and perform backups/restores of state data.

backup()

Create backup of all registered states.

backup_dir

Directory for backup files

data_dir

Directory for state files

get(name, expected_type=None)

Get registered state by name.

Parameters:

• name (str) – Name of the state

• expected_type (Optional[type[State]]) – Optional expected type of the state

Return type:

State

Returns:

Registered state instance

Raises:

• KeyError – If state is not registered

• TypeError – If state type does not match expected_type

async load()

Load all states from disk.

lock

Lock for synchronizing state operations

classmethod register(name, state_class)

Register a new state type.

This method does not affect existing StateManager instances.

Parameters:

• name (str) – Name of the state

• state_class (type[State]) – State class to register

Raises:

• TypeError – If state_class is not a State subclass

• ArgumentError – If name is already registered

Return type:

None

restore(timestamp=None)

Restore all states from backup.

Restore just copies state files from the backup, overwriting current state files. But it does not load them into current StateManager. It’s highly recommended to create a new StateManager instance after restore.

Parameters:

timestamp (Optional[str]) – Timestamp of the backup to restore (format: YYYYMMDD_HHMMSS

async save()

Save changed states to disk.

states: Dict[str, State]

Registry of state handlers by name