StateStorage API

StateStorage - Persistent state storage for Qtile.

This module provides a simple key-value storage that persists across Qtile config reloads and restarts. Data is stored as JSON in the Qtile cache directory.

Features: - Automatic loading/saving of state - Thread-safe operations - Support for primitive types (str, int, float, bool, list, dict) - Namespace support for organizing state - Hook integration for automatic save on config reload

Usage:

from qtile_expanded.storage import StateStorage

# Create a storage instance storage = StateStorage(“my_app”)

# Set values storage.set(“counter”, 42) storage.set(“settings”, {“theme”: “dark”, “notifications”: True})

# Get values counter = storage.get(“counter”, default=0) settings = storage.get(“settings”, default={})

# Delete values storage.delete(“counter”)

# Save explicitly storage.save()

# Use as context manager (auto-saves) with storage:

storage.set(“temporary”, “value”)

class qtile_expanded.storage.StateStorage(namespace: str, cache_dir: str | Path | None = None, auto_save: bool = True)

Bases: object

Persistent key-value storage for Qtile that survives config reloads.

Data is stored as JSON in ~/.cache/qtile/qtile_expanded/{namespace}.json

Args:

namespace: Unique identifier for this storage (e.g., “my_widget”) cache_dir: Override the Qtile cache directory (default: ~/.cache/qtile) auto_save: Whether to automatically save after each write (default: True)

Attributes:

data: The loaded state dictionary

__contains__(key: str) → bool

Check if key exists (supports ‘in’ operator).

__delitem__(key: str) → None

Delete value using bracket notation.

__enter__() → StateStorage

Context manager entry.

__exit__(exc_type, exc_val, exc_tb) → None

Context manager exit - save on exit.

__getitem__(key: str) → Any

Get value using bracket notation.

__init__(namespace: str, cache_dir: str | Path | None = None, auto_save: bool = True)

Initialize StateStorage with a namespace.

__len__() → int

Get number of items in storage.

__setitem__(key: str, value: Any) → None

Set value using bracket notation.

clear() → None

Clear all data from the storage.

decrement(key: str, amount: int = 1) → int

Decrement a numeric value in the storage.

Args:

key: The key to decrement amount: The amount to decrement by (default: 1)

Returns:

The new value

delete(key: str) → bool

Delete a value from the storage.

Args:

key: The key to delete

Returns:

True if the key existed and was deleted, False otherwise

get(key: str, default: Any | None = None) → Any

Get a value from the storage.

Args:

key: The key to retrieve default: Default value if key doesn’t exist

Returns:

The stored value, or default if not found

classmethod get_instance(namespace: str, **kwargs) → StateStorage

Get or create a StateStorage instance with the given namespace.

This ensures only one instance per namespace exists.

Args:

namespace: The storage namespace **kwargs: Additional arguments passed to StateStorage constructor

Returns:

The StateStorage instance

has(key: str) → bool

Check if a key exists in the storage.

increment(key: str, amount: int = 1) → int

Increment a numeric value in the storage.

Args:

key: The key to increment amount: The amount to increment by (default: 1)

Returns:

The new value

items() → list[tuple[str, Any]]

Get all key-value pairs in the storage.

keys() → list[str]

Get all keys in the storage.

save() → None

Save state to the JSON file.

classmethod save_all() → None

Save all registered StateStorage instances.

set(key: str, value: Any) → None

Set a value in the storage.

Args:

key: The key to store the value under value: The value to store (must be JSON-serializable)

toggle(key: str, default: bool = False) → bool

Toggle a boolean value in the storage.

Args:

key: The key to toggle default: Default value if key doesn’t exist

Returns:

The new value

update(other: dict[str, Any]) → None

Update the storage with multiple key-value pairs.

Args:

other: Dictionary of key-value pairs to update

values() → list[Any]

Get all values in the storage.

qtile_expanded.storage.setup_qtile_hooks(qtile) → None

Set up Qtile hooks to automatically save state before reload/shutdown.

This function should be called from your Qtile config:

from qtile_expanded.storage import setup_qtile_hooks

def main(q):

setup_qtile_hooks(q) # … rest of your config

Args:

qtile: The Qtile instance (usually ‘q’ in config.py)

Classes

StateStorage

class qtile_expanded.storage.StateStorage(namespace: str, cache_dir: str | Path | None = None, auto_save: bool = True)

Bases: object

Persistent key-value storage for Qtile that survives config reloads.

Data is stored as JSON in ~/.cache/qtile/qtile_expanded/{namespace}.json

Args:

namespace: Unique identifier for this storage (e.g., “my_widget”) cache_dir: Override the Qtile cache directory (default: ~/.cache/qtile) auto_save: Whether to automatically save after each write (default: True)

Attributes:

data: The loaded state dictionary

__contains__(key: str) → bool

Check if key exists (supports ‘in’ operator).

__delitem__(key: str) → None

Delete value using bracket notation.

__enter__() → StateStorage

Context manager entry.

__exit__(exc_type, exc_val, exc_tb) → None

Context manager exit - save on exit.

__getitem__(key: str) → Any

Get value using bracket notation.

__init__(namespace: str, cache_dir: str | Path | None = None, auto_save: bool = True)

Initialize StateStorage with a namespace.

__len__() → int

Get number of items in storage.

__setitem__(key: str, value: Any) → None

Set value using bracket notation.

clear() → None

Clear all data from the storage.

decrement(key: str, amount: int = 1) → int

Decrement a numeric value in the storage.

Args:

key: The key to decrement amount: The amount to decrement by (default: 1)

Returns:

The new value

delete(key: str) → bool

Delete a value from the storage.

Args:

key: The key to delete

Returns:

True if the key existed and was deleted, False otherwise

get(key: str, default: Any | None = None) → Any

Get a value from the storage.

Args:

key: The key to retrieve default: Default value if key doesn’t exist

Returns:

The stored value, or default if not found

classmethod get_instance(namespace: str, **kwargs) → StateStorage

Get or create a StateStorage instance with the given namespace.

This ensures only one instance per namespace exists.

Args:

namespace: The storage namespace **kwargs: Additional arguments passed to StateStorage constructor

Returns:

The StateStorage instance

has(key: str) → bool

Check if a key exists in the storage.

increment(key: str, amount: int = 1) → int

Increment a numeric value in the storage.

Args:

key: The key to increment amount: The amount to increment by (default: 1)

Returns:

The new value

items() → list[tuple[str, Any]]

Get all key-value pairs in the storage.

keys() → list[str]

Get all keys in the storage.

save() → None

Save state to the JSON file.

classmethod save_all() → None

Save all registered StateStorage instances.

set(key: str, value: Any) → None

Set a value in the storage.

Args:

key: The key to store the value under value: The value to store (must be JSON-serializable)

toggle(key: str, default: bool = False) → bool

Toggle a boolean value in the storage.

Args:

key: The key to toggle default: Default value if key doesn’t exist

Returns:

The new value

update(other: dict[str, Any]) → None

Update the storage with multiple key-value pairs.

Args:

other: Dictionary of key-value pairs to update

values() → list[Any]

Get all values in the storage.

Functions

qtile_expanded.storage.setup_qtile_hooks(qtile) → None

Set up Qtile hooks to automatically save state before reload/shutdown.

This function should be called from your Qtile config:

from qtile_expanded.storage import setup_qtile_hooks

def main(q):

setup_qtile_hooks(q) # … rest of your config

Args:

qtile: The Qtile instance (usually ‘q’ in config.py)