home_secret_toml

Home Secrets Management Module (TOML Version)

This module provides a flexible and secure mechanism for loading secrets from a TOML file. It implements a flat key-value structure for easy navigation and editing, with lazy loading of secrets and automatic synchronization between development and runtime environments.

Architecture Overview

The module is built around three core concepts:

1. Flat Structure: All secrets are stored as flat key-value pairs with dot-separated keys

2. Lazy Loading: Secrets are only loaded from disk when actually accessed

3. Token System: Values are represented as tokens that resolve to actual values on demand

File Location Strategy

By default, the secret file is expected to be located at ${HOME}/home_secret.toml. You can also specify a custom path when creating a HomeSecretToml instance.

Key Features

• Flat Key Structure: Each key contains the full path, making context immediately visible

• Comment Support: TOML natively supports # comments for documentation

• Lazy Loading: Secrets are only read from disk when accessed via .v property

• Token-based Access: Flexible reference system for delayed value resolution

• Robust Error Handling: Clear error messages for missing or malformed secrets

• IDE Support: Generated enum class provides full autocomplete support

• Configurable Path: Custom secret file path can be specified for testing

Direct value access:

# Get a secret value immediately
api_key = hs.v("github.accounts.personal.users.dev.secrets.api_token.value")

Token-based access:

# Create a token for later use
token = hs.t("github.accounts.personal.users.dev.secrets.api_token.value")
# Resolve the token when needed
api_key = token.v

Custom path for testing:

# Use a custom path for testing
hs_test = HomeSecretToml(path=Path("/path/to/test/secrets.toml"))

class home_secret_toml.home_secret_toml.Token(data: dict[str, Any], path: str)

A lazy-loading token that represents a reference to a secret value.

Tokens are placeholders for values that aren’t resolved when the token object is created. Instead, the actual secret value is loaded from the TOML file only when accessed via the .v property. This enables:

• Deferred Loading: Values are only read from disk when actually needed

• Reference Flexibility: Tokens can be passed around and stored before resolution

• Error Isolation: TOML parsing errors only occur when values are accessed

Parameters:

• data – Reference to the loaded TOML data dictionary

• path – Dot-separated path to the secret value within the TOML structure

property v: Any

Lazily load and return the secret value from the TOML data.

Returns:

The secret value at the specified path

class home_secret_toml.home_secret_toml.HomeSecretToml(path: ~pathlib.Path = <factory>, _cache_v: dict[str, ~typing.Any] = <factory>, _cache_t: dict[str, ~home_secret_toml.home_secret_toml.Token] = <factory>)

Main interface for loading and accessing secrets from a home_secret.toml file.

This class provides the core functionality for the secrets management system:

• Configurable Path: Specify custom path for testing or different environments

• Lazy Loading: TOML is only parsed when first accessed

• Caching: Parsed TOML data is cached for subsequent access

• Flexible Access: Supports both direct value access and token creation

Parameters:

path – Path to the TOML secrets file. Defaults to $HOME/home_secret.toml

property data: dict[str, Any]

Load and cache the secret data from the TOML file.

Raises:

FileNotFoundError – If the secrets file does not exist at the specified path

v(path: str) → Any

Direct access to secret values using dot-separated path notation.

This method provides immediate access to secret values without creating intermediate token objects. It’s the most direct way to retrieve secrets when you need the value immediately.

Note

V stands for Value.

t(path: str) → Token

Create a Token object for deferred access to secret values.

This method creates a token that can be stored, passed around, and resolved later when the actual value is needed. This is useful for:

• Configuration Objects: Store tokens in config classes

• Dependency Injection: Pass tokens to components that resolve them later

• Conditional Access: Create tokens but only resolve them when needed

Note

T stands for Token.

home_secret_toml.home_secret_toml.silent_error_handler(func: Callable) → Callable

Decorator that provides optional silent error handling for CLI commands.

When the decorated function is called with silent=True, any exception will be caught and printed in a structured format instead of raising. This is useful for scripting scenarios where you want to:

1. Check if an error occurred by examining the output prefix

2. Get a consistent exit code (2) for error cases

3. Avoid traceback noise in automated pipelines

Behavior:

• silent=False (default): Exceptions propagate normally with full traceback

• silent=True: Exceptions are caught, printed as [HST_ERROR] repr(e), and the process exits with code 2

Usage in shell scripts:

output=$(hst get -s some.key)
if [[ $output == "[HST_ERROR]"* ]]; then
    echo "Error occurred: $output"
fi

Parameters:

func – The CLI function to wrap

Returns:

Wrapped function with silent error handling capability

home_secret_toml.home_secret_toml.walk(dct: dict[str, Any], _parent_path: str = '') → Iterable[tuple[str, Any]]

Recursively traverse a nested dictionary structure to extract all leaf paths and values.

This function performs a depth-first traversal of the secrets TOML structure, yielding dot-separated paths to all non-dictionary values while filtering out metadata fields and placeholder values.

Filtering Logic:

• Recursively descends into dictionary values

• Skips ‘description’ keys (metadata)

• Skips values equal to UNKNOWN (”…” placeholder)

• Yields complete dot-separated paths for all other leaf values

Parameters:

• dct – Dictionary to traverse (typically the loaded secrets TOML)

• _parent_path – Current path prefix for recursive calls (internal use)

Yields:

Tuples of (path, value) where path is dot-separated and value is the leaf data

Example:

data = {
    "github": {
        "description": "GitHub platform",  # Skipped (description)
        "accounts": {
            "personal": {
                "account_id": "user123",
                "admin_email": "...",  # Skipped (UNKNOWN)
            }
        }
    }
}

# Results in:
# ("github.accounts.personal.account_id", "user123")

home_secret_toml.home_secret_toml.gen_enum_code(hs_instance: HomeSecretToml | None = None, output_path: Path | None = None) → None

Generate a flat enumeration class providing direct attribute access to all secrets.

This function creates an alternative access pattern by generating a flat class where each secret path becomes a simple attribute name. The generated code provides:

• Flat Access: All secrets accessible as Secret.github__accounts__personal__…

• Auto-Generation: Automatically discovers all paths in the TOML structure

• Validation Function: Includes a function to test all generated paths

• Simple Imports: Minimal dependencies for the generated file

Path Transformation Logic:

• Converts dots to double underscores for valid Python identifiers

• Preserves the complete path hierarchy in the attribute name

Parameters:

• hs_instance – HomeSecretToml instance to use for reading secrets. Defaults to the global hs instance.

• output_path – Path to write the generated file. Defaults to ./home_secret_enum.py

home_secret_toml.home_secret_toml.mask_value(value: Any) → str

Mask a secret value for safe display.

Masking Rules:

• Non-string values: replaced with “*”

• Strings longer than 8 characters: show first 2 and last 2 chars with “***” in between

• Strings 8 characters or shorter: replaced with “***”

Parameters:

value – The value to mask

Returns:

Masked string representation

home_secret_toml.home_secret_toml.list_secrets(path: Path | None = None, query: str | None = None) → list[tuple[str, str]]

List all secrets with masked values.

This is the underlying function for the hst ls command.

Query Matching Rules:

• Case-insensitive matching

• Dashes (-) and underscores (_) are treated as equivalent

• Spaces and commas in query are treated as separators for multiple facets

• All facets must match (AND logic) for a key to be included

Parameters:

• path – Path to the TOML secrets file. Defaults to $HOME/home_secret.toml

• query – Optional query string to filter keys. Supports multiple facets separated by spaces or commas.

Returns:

List of (key, masked_value) tuples

home_secret_toml.home_secret_toml.cmd_ls(path: Path | None = None, query: str | None = None) → None

CLI wrapper for list_secrets. Prints results to stdout.

Parameters:

• path – Path to the TOML secrets file. Defaults to $HOME/home_secret.toml

• query – Optional substring to filter keys

Note

This function is wrapped by silent_error_handler() decorator. When called via CLI with -s flag, the silent parameter is passed to the decorator wrapper, not to this function directly.

home_secret_toml.home_secret_toml.get_secret(key: str, path: Path | None = None) → Any

Get a secret value by its key.

This is the underlying function for the hst get command.

Parameters:

• key – Dot-separated path to the secret value (e.g., “github.accounts.personal.token”)

• path – Path to the TOML secrets file. Defaults to $HOME/home_secret.toml

Raises:

• FileNotFoundError – If the secrets file does not exist

• KeyError – If the key does not exist in the secrets file

Returns:

The secret value

home_secret_toml.home_secret_toml.cmd_get(key: str, path: Path | None = None, clipboard: bool = False, no_newline: bool = False) → None

CLI wrapper for get_secret. Prints result to stdout or copies to clipboard.

Parameters:

• key – Dot-separated path to the secret value

• path – Path to the TOML secrets file. Defaults to $HOME/home_secret.toml

• clipboard – If True, copy to clipboard instead of printing

• no_newline – If True, don’t print trailing newline

Note

This function is wrapped by silent_error_handler() decorator. When called via CLI with -s flag, the silent parameter is passed to the decorator wrapper, not to this function directly.

home_secret_toml.home_secret_toml.generate_enum(path: Path | None = None, output: Path | None = None, overwrite: bool = False) → Path

Generate the home_secret_enum.py file.

This is the underlying function for the hst gen-enum command.

Parameters:

• path – Path to the TOML secrets file. Defaults to $HOME/home_secret.toml

• output – Output path (directory or file). Defaults to ./home_secret_enum.py

• overwrite – If True, allow overwriting existing files

Raises:

• FileExistsError – If output file exists and overwrite is False

• FileNotFoundError – If secrets file does not exist

Returns:

The path where the enum file was written

home_secret_toml.home_secret_toml.cmd_gen_enum(path: Path | None = None, output: Path | None = None, overwrite: bool = False) → None

CLI wrapper for generate_enum. Prints result to stdout.

Parameters:

• path – Path to the TOML secrets file. Defaults to $HOME/home_secret.toml

• output – Output path (directory or file). Defaults to ./home_secret_enum.py

• overwrite – If True, allow overwriting existing files

home_secret_toml.home_secret_toml.main() → None

Main CLI entry point for the hst command.