ddp_utils.env_store

import ddp_utils.env_store

Persistent key/value storage scoped to the active Python environment.

Values are isolated by interpreter executable, prefix, base prefix, and Python major/minor version. A process environment variable can override the stored value, which keeps shell, CI, and one-off process configuration authoritative.

The backend is intentionally not encrypted. It keeps values outside project source trees, applies restrictive permissions where supported, and masks list output by default, but it is not an operating-system credential vault.

Examples

Use this public operation:

import ddp_utils.env_store

ddp_utils.env_store.ENV_STORE_HOME_VARIABLE = 'DDP_UTILS_ENV_STORE_HOME'

Environment variable overriding the root of persistent environment stores.

class ddp_utils.env_store.PythonEnvStore(storage_root: Path | str | None = None)

Bases: object

Store string values for the currently running Python environment.

Scope identity intentionally excludes the project directory. Separate virtual environments, interpreter locations, or Python major/minor versions receive separate storage directories.

Parameters

Name	Type	Description
storage_root	Optional[Union[str, Path]]	Optional root override, primarily for explicit isolation or tests. The default follows the DDP per-user runtime layout.

Stored data is plain JSON and is not encrypted. Process environment variables take precedence by default.

Examples

Use this public operation:

instance = PythonEnvStore(...)

Initialize a store without creating directories or files.

property scope_id: str

Return the deterministic identifier of the active Python scope.

Returns

First 24 hexadecimal characters of the scope SHA-256 digest.

Examples

Use this public operation:

result = instance.scope_id()

property storage_path: Path

Return the JSON storage path without creating it.

Returns

Absolute path to the scope-specific env.json file.

Examples

Use this public operation:

result = instance.storage_path()

property is_venv: bool

Return whether the active interpreter belongs to a virtual environment.

Returns

True when sys.prefix differs from sys.base_prefix.

Examples

Use this public operation:

result = instance.is_venv()

property prefix: str

Return the canonical active Python prefix.

Returns

Absolute, platform-normalized sys.prefix.

Examples

Use this public operation:

result = instance.prefix()

property executable: str

Return the canonical active Python executable path.

Returns

Absolute, platform-normalized sys.executable.

Examples

Use this public operation:

result = instance.executable()

get(key: str, default: str | None = None, *, prefer_process: bool = True) → str | None

Return a process or persistent value.

Parameters

Name	Type	Description
key	str	Environment-compatible key.
default	str | None	Result when neither source contains the key.
prefer_process	bool	Check os.environ before persistent storage.

Returns

Type	Description
str | None	Resolved string value or default.

Raises

Exception	Description
TypeError	If key is not a string.
ValueError	If key is not environment-compatible.
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = instance.get(key=key_value)

require(key: str, *, prefer_process: bool = True) → str

Return a configured value or raise KeyError.

Parameters

Name	Type	Description
key	str	Environment-compatible key.
prefer_process	bool	Check os.environ before persistent storage.

Returns

Type	Description
str	Resolved string value.

Raises

Exception	Description
KeyError	If the key is absent from both sources.

Examples

Use this public operation:

result = instance.require(key=key_value)

set(key: str, value: object, *, sync_process: bool = True) → str

Persist a value and optionally synchronize os.environ.

Parameters

Name	Type	Description
key	str	Environment-compatible key.
value	object	String-compatible value; None and bytes are rejected.
sync_process	bool	Also set the value for the current process.

Returns

Type	Description
str	Stored string representation.

Raises

Exception	Description
TypeError	If the key or value type is unsupported.
ValueError	If the key is invalid or value is None.
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = instance.set(key=key_value, value=value_value)

delete(key: str, *, sync_process: bool = True) → bool

Delete a stored value while preserving a different process override.

Parameters

Name	Type	Description
key	str	Environment-compatible key.
sync_process	bool	Remove the matching current-process value.

Returns

Type	Description
bool	True if a persistent value existed.

Raises

Exception	Description
TypeError	If key is not a string.
ValueError	If key is not environment-compatible.
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = instance.delete(key=key_value)

has(key: str, *, include_process: bool = True) → bool

Return whether a key exists in the selected sources.

Parameters

Name	Type	Description
key	str	Environment-compatible key.
include_process	bool	Include os.environ in the lookup.

Returns

Type	Description
bool	True when the key is configured.

Raises

Exception	Description
TypeError	If key is not a string.
ValueError	If key is not environment-compatible.
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = instance.has(key=key_value)

list(*, include_values: bool = False, mask: str = '********') → Dict[str, str]

List persistent values, masked by default.

Parameters

Name	Type	Description
include_values	bool	Return actual values instead of a mask.
mask	str	Replacement used when values are hidden.

Returns

Type	Description
Dict[str, str]	Key-sorted dictionary from persistent storage only.

Raises

Exception	Description
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = instance.list()

keys() → list[str]

Return sorted persistent key names without exposing values.

Returns

Type	Description
list[str]	Sorted list of keys from persistent storage only.

Raises

Exception	Description
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = instance.keys()

load_into_process(*, overwrite: bool = False) → int

Copy persistent values into the current process.

Parameters

Name	Type	Description
overwrite	bool	Replace already configured process variables.

Returns

Type	Description
int	Number of values copied.

Raises

Exception	Description
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = instance.load_into_process()

clear(*, sync_process: bool = True) → int

Delete all persistent values for this Python scope.

Parameters

Name	Type	Description
sync_process	bool	Remove current-process values that still match storage.

Returns

Type	Description
int	Number of deleted persistent values.

Raises

Exception	Description
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = instance.clear()

info() → PythonEnvStoreInfo

Return JSON-compatible diagnostics without secret values.

Returns

Type	Description
PythonEnvStoreInfo	Scope, interpreter, storage path, and existence information.

Examples

Use this public operation:

result = instance.info()

exception ddp_utils.env_store.PythonEnvStoreError

Bases: RuntimeError

A persistent environment store could not be read or validated.

Examples

Use this public operation:

instance = PythonEnvStoreError(...)

class ddp_utils.env_store.PythonEnvStoreInfo

Bases: TypedDict

Typed diagnostic information returned by PythonEnvStore.info().

Examples

Use this public operation:

instance = PythonEnvStoreInfo(...)

ddp_utils.env_store.clear_env(*, sync_process: bool = True) → int

Clear every value in the default Python environment store.

Parameters

Name	Type	Description
sync_process	bool	Remove current-process values that still match storage.

Returns

Type	Description
int	Number of deleted persistent values.

Raises

Exception	Description
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = ddp_utils.env_store.clear_env()

ddp_utils.env_store.delete_env(key: str, *, sync_process: bool = True) → bool

Delete a value from the default Python environment store.

Parameters

Name	Type	Description
key	str	Environment-compatible key.
sync_process	bool	Remove a matching value from the current process.

Returns

Type	Description
bool	True when a persistent value existed.

Raises

Exception	Description
TypeError	If key is not a string.
ValueError	If key is not environment-compatible.
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = ddp_utils.env_store.delete_env(key=key_value)

ddp_utils.env_store.env_info() → PythonEnvStoreInfo

Return default-store diagnostics without secret values.

Returns

Type	Description
PythonEnvStoreInfo	Scope, interpreter, storage path, and existence information.

Examples

Use this public operation:

result = ddp_utils.env_store.env_info()

ddp_utils.env_store.get_env(key: str, default: str | None = None, *, prefer_process: bool = True) → str | None

Return a value from the default Python environment store.

Parameters

Name	Type	Description
key	str	Environment-compatible key.
default	str | None	Result when the key is not configured.
prefer_process	bool	Check os.environ before persistent storage.

Returns

Type	Description
str | None	Resolved string value or default.

Raises

Exception	Description
TypeError	If key is not a string.
ValueError	If key is not environment-compatible.
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = ddp_utils.env_store.get_env(key=key_value)

ddp_utils.env_store.has_env(key: str, *, include_process: bool = True) → bool

Check whether the default store or process contains a key.

Parameters

Name	Type	Description
key	str	Environment-compatible key.
include_process	bool	Include os.environ in the lookup.

Returns

Type	Description
bool	True when the key is configured.

Raises

Exception	Description
TypeError	If key is not a string.
ValueError	If key is not environment-compatible.
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = ddp_utils.env_store.has_env(key=key_value)

ddp_utils.env_store.list_env(include_values: bool = False, *, mask: str = '********') → Dict[str, str]

List persistent values from the default store.

Parameters

Name	Type	Description
include_values	bool	Return actual values instead of a mask.
mask	str	Replacement used when values are hidden.

Returns

Type	Description
Dict[str, str]	Key-sorted persistent values, masked by default.

Raises

Exception	Description
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = ddp_utils.env_store.list_env()

ddp_utils.env_store.load_env(*, overwrite: bool = False) → int

Load default-store values into the current process.

Parameters

Name	Type	Description
overwrite	bool	Replace already configured process variables.

Returns

Type	Description
int	Number of values copied.

Raises

Exception	Description
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = ddp_utils.env_store.load_env()

ddp_utils.env_store.set_env(key: str, value: object, *, sync_process: bool = True) → str

Persist a value in the default Python environment store.

Parameters

Name	Type	Description
key	str	Environment-compatible key.
value	object	String-compatible value; None and bytes are rejected.
sync_process	bool	Also set the value for the current process.

Returns

Type	Description
str	Stored string representation.

Raises

Exception	Description
TypeError	If the key or value type is unsupported.
ValueError	If the key is invalid or value is None.
PythonEnvStoreError	If persistent storage is invalid.

Examples

Use this public operation:

result = ddp_utils.env_store.set_env(key=key_value, value=value_value)