Skip to content

stored_state_management

This directory provides a standardized, centralized system for managing persistent stored state across the Talon Community repository. By isolating state operations to a dedicated directory at the repository root, it prevents state file pollution and ensures consistent file access patterns.

How Stored State Management Works

The state management system operates dynamically, bootstrapping itself relative to the location of the codebase.

The primary entry point is stored_state.py, which performs the following initialization steps:

  1. Locates the Repository Root: It uses the file system path of the script itself and traverses upward by three levels (from community/core/stored_state_management/ to community/) to locate the root of the community directory.
  2. Bootstraps the State Directory: It ensures a directory named stored_state/ exists at the community root, creating it if it is missing.
  3. Exposes Talon Actions: It defines a set of global Talon actions under a custom module to allow other scripts and voices to interact with this state seamlessly.

Key APIs and Actions

The core functionality of this module is exposed through Talon actions defined in stored_state.py. These actions fall into two main patterns: Signal (or Flag) Files and KeyValue/Text Storage.

Signal File Actions

Signal files are empty sentinel files used to represent simple boolean flags or state toggles (e.g., indicating whether a specific feature or mode is active).

  • user.stored_state_does_file_exist(directory_name, name): Checks for the existence of a given file within a specified subdirectory of the state folder.
  • user.stored_state_create_signal_file(directory_name, name): Creates an empty placeholder file. It automatically ensures any intermediate parent directories are created first.
  • user.stored_state_remove_signal_file(directory_name, name): Safely deletes a flag file. This action includes safety checks to prevent destructive operations:
    • It asserts that the target path is a file, not a directory.
    • It ensures the file is truly empty (size 0) before deletion, preventing accidental loss of user data if a file was incorrectly targeted.

Text and Value Storage Actions

For more complex state tracking, these actions allow scripts to persist and retrieve string data.

  • user.stored_state_set_value(directory_name, name, value): Writes a raw string value to a specified file, creating parent directories dynamically if needed.
  • user.stored_state_get_text(directory_name, name): Reads and returns the complete text contents of a specified state file.