aeat.core._config_state_root module¶

Installed-vs-checkout detection and the platform user-data storage root.

The central settings facade (Settings) roots the encrypted profile store at aeat_local_storage_root, from which the token, log, secret, blob and audit roots derive. Historically that root defaulted to PROJECT_ROOT / "var" / "storage", which is correct for a source checkout but wrong for an installed distribution: under a wheel it resolves inside the virtualenv, and under uvx inside uv’s ephemeral cache, where a cache prune could silently destroy the taxpayer’s encrypted store.

This module owns the two decisions that fix that defect without disturbing the dev loop: whether the process runs from a source checkout or an installed distribution (detect_run_mode()), and where the platform user-data base lives per operating system (platform_user_data_root()). A checkout keeps the PROJECT_ROOT / "var" / "storage" default; an installed run lands under the platform user-data directory (%LOCALAPPDATA% on Windows, $XDG_DATA_HOME with the ~/.local/share fallback on Linux, ~/Library/Application Support on macOS).

Every input the resolution reads — the project-root candidate, the platform string, the environment mapping, and the home directory — is captured in the frozen StateRootInputs seam so the detection is deterministic and testable without mutating the ambient process. default_storage_root() is the live entry point Settings binds as its aeat_local_storage_root default factory.

See also

Settings: Central settings aggregate whose storage-root default is resolved here.
PROJECT_ROOT: Checkout-root anchor mirrored when source-tree defaults are preserved.
StateRootInputs: Frozen seam that captures every environmental input used by resolution.
detect_run_mode(): Checkout-versus-installed classifier used before selecting a root.
resolve_state_root(): Pure resolver that returns the effective storage root.
default_storage_root(): Live default factory bound into the settings model.

class RunMode(*values)[source]¶

Bases: StrEnum

Whether the process runs from a source checkout or an installed build.

detect_run_mode() returns a member; resolve_state_root() branches on it to pick the checkout var/storage default or the platform user-data directory.

CHECKOUT¶

INSTALLED¶

class StateRootInputs(**data)[source]¶

Bases: BaseModel

Injectable, frozen seam for state-root resolution.

Capturing every environmental input as an explicit field makes both detect_run_mode() and platform_user_data_root() pure functions of their argument, so tests construct an installed or checkout context deterministically rather than mutating os.environ or patching sys.platform.

Parameters:

project_root_candidate (Path)
platform (str)
environ (dict[str, str])
home (Path)

project_root_candidate: Path¶

platform: str¶

environ: dict[str, str]¶

home: Path¶

class StateRootResolution(**data)[source]¶

Bases: BaseModel

Typed outcome of resolving the storage state root.

Carries the decided RunMode, the project-root candidate it was decided from, the platform user-data base, and the effective storage_root that Settings should default aeat_local_storage_root to.

Parameters:

run_mode (RunMode)
project_root (Path)
platform_user_data_root (Path)
storage_root (Path)

run_mode: RunMode¶

project_root: Path¶

platform_user_data_root: Path¶

storage_root: Path¶

live_state_root_inputs()[source]¶

Capture the running process’s state-root inputs.

Snapshots the module-derived project-root candidate, platform, a copy of os.environ, and the user’s home directory into a frozen StateRootInputs for resolve_state_root().

Return type:: StateRootInputs

detect_run_mode(inputs)[source]¶

Classify the run as a source checkout or an installed distribution.

A source checkout carries the repository markers at its project root: a pyproject.toml file and a .git entry (a directory in a normal clone, a pointer file inside a git worktree — so presence, not directory-ness, is the test). An installed wheel resolves the candidate under site-packages where neither marker exists, so the absence of either marker classifies the run as installed.

Return type:: RunMode
Parameters:: inputs (StateRootInputs)

platform_user_data_root(inputs)[source]¶

Resolve the aeat platform user-data directory for the given inputs.

Windows resolves under %LOCALAPPDATA% (~/AppData/Local when the variable is unset or not absolute); macOS under ~/Library/Application Support; every other platform under $XDG_DATA_HOME (~/.local/share when unset or not absolute). The aeat application directory name is appended to the resolved base.

Return type:: Path
Parameters:: inputs (StateRootInputs)

resolve_state_root(inputs)[source]¶

Resolve the effective storage state root for the given inputs.

A checkout keeps the historical PROJECT_ROOT / "var" / "storage" default; an installed run lands at <platform-user-data>/aeat/storage so the encrypted store never resolves inside a virtualenv or uv cache.

Return type:: StateRootResolution
Parameters:: inputs (StateRootInputs)

default_storage_root()[source]¶

Return the aeat_local_storage_root default for the live process.

Bound as the Settings aeat_local_storage_root default factory: a checkout resolves to PROJECT_ROOT / "var" / "storage" (unchanged), an installed run to the platform user-data storage directory.

Return type:: Path