ddp_utils.runtime.paths¶

import ddp_utils.runtime.paths

Provide cross-platform paths for namespaced runtime data.

RuntimePaths organizes isolated and shared temporary, cache, state, driver, configuration, data, log, and lock locations and integrates them with deferred cleanup registration.

Examples

Use this public operation:

from ddp_utils.runtime.paths import RuntimePaths

paths = RuntimePaths("example", create_now=False)

class ddp_utils.runtime.paths.RuntimePaths(namespace: str | None = None, *, isolated: bool = True, scope: str = 'tools', create_now: bool = True)¶

Bases: object

Cross-platform runtime path manager for a single namespace.

cleanup_expired() is rate-limited to once per 60 seconds at the class level to avoid file I/O on every instantiation in hot paths.

The class provides a stable per-user storage layout under a global ddp root. The root location is OS-dependent:

Supports 3 scenarios:

isolated tool namespace: ddp/tools/<namespace>/{temp,cache,drivers,config,data,logs,locks}
script namespace: ddp/scripts/<namespace>/{temp,cache,drivers,config,data,logs,locks}
shared root: ddp/{temp,cache,drivers,config,data,logs,locks}

Windows: %LOCALAPPDATA%\ddp
macOS: ~/Library/Application Support/ddp
Linux: $XDG_DATA_HOME/ddp or ~/.local/share/ddp
Fallback: ~/ddp

Each namespace receives its own isolated directory tree:

ddp/
    tools/
        <namespace>/
            temp/
            cache/
            drivers/
            config/
            data/
            logs/
            locks/
    scripts/
        <namespace>/
            temp/
            cache/
            drivers/
            config/
            data/
            logs/
            locks/

Parameters

Name	Type	Description
namespace	Optional[str]	Logical namespace of the library, module, tool, or script, for example `"ddp-utils"`, `"screenmatch-kit"`, or `"business-client"`.
create_now	bool	If `True`, all main directories are created immediately.

Raises

Exception	Description
ValueError	If `namespace` is empty for isolated runtime modes.

Examples

Use this public operation:

instance = RuntimePaths(...)

Configure shared or isolated runtime paths and perform due cleanup.

Expired cleanup targets are processed at most once per class-level interval. When create_now is true, all standard runtime directories are created before initialization returns.

Parameters

Name	Type	Description
namespace	Optional[str]	Namespace required for isolated paths. `None` is valid only for shared mode.
isolated	bool	Place paths below a normalized namespace when true; use the shared root when false.
scope	str	Isolated namespace group such as `"tools"` or `"scripts"`. Ignored in shared mode.
create_now	bool	Create every standard runtime directory immediately.

Raises

Exception	Description
ValueError	Isolated mode receives an empty namespace or an invalid scope.
OSError	Expired cleanup processing or directory creation fails.

Examples

Configure isolated paths without eagerly creating the layout:

paths = RuntimePaths("reports", create_now=False)

classmethod shared(*, create_now: bool = True) → RuntimePaths¶

Return the shared (non-isolated) RuntimePaths instance, creating its directories if requested.

Parameters

Name	Type	Description
create_now	bool	If `True`, the main directories are created immediately.

Returns

Type	Description
RuntimePaths	Shared (non-isolated) `RuntimePaths` instance.

Examples

Use this public operation:

result = instance.shared()

classmethod isolated(namespace: str, *, create_now: bool = True) → RuntimePaths¶

Return a RuntimePaths instance isolated in the tools scope.

The directories are created immediately when create_now is true.

Parameters

Name	Type	Description
namespace	str	Logical namespace of the tool.
create_now	bool	If `True`, the main directories are created immediately.

Returns

Type	Description
RuntimePaths	`RuntimePaths` instance isolated in the `tools` scope.

Examples

Use this public operation:

result = instance.isolated(namespace=namespace_value)

classmethod script(namespace: str, *, create_now: bool = True) → RuntimePaths¶

Return a script runtime namespace.

Script runtimes are intended for business/project executions whose working files are runtime cookies for a single project or process.

The namespace is created under:

ddp/scripts/<namespace>/

Parameters

Name	Type	Description
namespace	str	Script or business project namespace.
create_now	bool	If `True`, all main directories are created immediately.

Returns

Type	Description
RuntimePaths	`RuntimePaths` instance bound to `ddp/scripts/<namespace>`.

Raises

Exception	Description
ValueError	If `namespace` is empty.

Examples

Use this public operation:

result = instance.script(namespace=namespace_value)

classmethod global_root() → Path¶

Return the global DDP root for the current user.

Platform conventions:

Windows: %LOCALAPPDATA%\ddp
macOS: ~/Library/Application Support/ddp
Linux: $XDG_DATA_HOME/ddp or ~/.local/share/ddp
Fallback: ~/ddp

Returns

Type	Description
Path	Global DDP root directory of the current user.

Examples

Use this public operation:

result = instance.global_root()

classmethod cleanup_registry_path() → Path¶

Return the runtime cleanup registry path.

The registry stores auto-cleanup targets for all runtime namespaces and explicit runtime files/directories.

Returns

Type	Description
Path	Absolute path to `ddp/.runtime_cleanup.json`.

Examples

Use this public operation:

result = instance.cleanup_registry_path()

classmethod cleanup_expired() → list[dict[str, Any]]¶

Remove expired runtime cleanup targets.

This is a global cleanup pass for the current user DDP root. It is called automatically when RuntimePaths is initialized.

Returns

Type	Description
list[dict[str, Any]]	List of cleanup result dictionaries.

Examples

Use this public operation:

result = instance.cleanup_expired()

classmethod register_cleanup(path: Path | str, *, auto_remove: Any, namespace: str | None = None, scope: str | None = None, reason: str | None = None, allow_external: bool = False, remove_empty_parents: bool = False) → str¶

By default, cleanup targets must be located inside the global DDP root. External targets are allowed only when allow_external=True is passed explicitly.

Parameters

Name	Type	Description
path	Path \| str	File or directory path to remove when expired.
auto_remove	Any	Expiration datetime. Supported values: `datetime` instance ISO datetime string UNIX timestamp as `int` or `float`
namespace	str \| None	Optional logical namespace for audit/debugging.
scope	str \| None	Optional runtime scope for audit/debugging.
reason	str \| None	Optional human-readable cleanup reason.
allow_external	bool	If `True`, paths outside the global DDP root are allowed.
remove_empty_parents	bool	If `True`, empty parent directories are removed after target cleanup.

Returns

Type	Description
str	Cleanup target id.

Examples

Use this public operation:

result = instance.register_cleanup(path=path_value, auto_remove=auto_remove_value)

classmethod unregister_cleanup(target_id: str) → None¶

Remove a cleanup target record by id.

Parameters

Name	Type	Description
target_id	str	Target id returned by `register_cleanup` or `runtime.cleanup`.

Examples

Use this public operation:

result = instance.unregister_cleanup(target_id=target_id_value)

classmethod clear_path(path: Path | str, *, allow_external: bool = False, remove_empty_parents: bool = False) → bool¶

Remove a file, symlink, or directory path immediately.

By default, the target must be inside the global DDP runtime root.

Parameters

Name	Type	Description
path	Path \| str	File or directory to remove.
allow_external	bool	If `True`, paths outside the global DDP root are allowed.
remove_empty_parents	bool	If `True`, empty parent directories are removed after target cleanup.

Returns

Type	Description
bool	`True` if something existed and was removed, otherwise `False`.

Examples

Use this public operation:

result = instance.clear_path(path=path_value)

property root: Path¶

Return the namespace root.

Returns

ddp/tools/<namespace> Absolute path to for isolated tool mode, ddp/scripts/<namespace> for script mode, or ddp for shared mode.

Examples

Use this public operation:

result = instance.root()

livetime(auto_remove: Any, *, target: Path | str | None = None, reason: str | None = None, allow_external: bool = False, remove_empty_parents: bool = False) → str¶

Set auto-cleanup lifetime for this runtime or for a concrete target.

If target is not provided, the current runtime root is registered. If target is provided, that concrete file or directory is registered.

Parameters

Name	Type	Description
auto_remove	Any	Expiration datetime. Supported values: `datetime` instance ISO datetime string UNIX timestamp as `int` or `float`
target	Path \| str \| None	Optional concrete cleanup target. If omitted, `self.root` is used.
reason	str \| None	Optional human-readable cleanup reason.
allow_external	bool	If `True`, paths outside the global DDP root are allowed.
remove_empty_parents	bool	If `True`, empty parent directories are removed after target cleanup.

Returns

Type	Description
str	Cleanup target id.

Examples

Use this public operation:

result = instance.livetime(auto_remove=auto_remove_value)

cleanup(*, auto_remove: Any, target: Path | str | None = None, reason: str | None = None, allow_external: bool = False, remove_empty_parents: bool = False) → str¶

If target is not provided, the current runtime root is registered. If target is provided, that concrete file or directory is registered.

Parameters

Name	Type	Description
auto_remove	Any	Expiration datetime. Supported values: `datetime` instance ISO datetime string UNIX timestamp as `int` or `float`
target	Path \| str \| None	Optional concrete cleanup target. If omitted, `self.root` is used.
reason	str \| None	Optional human-readable cleanup reason.
allow_external	bool	If `True`, paths outside the global DDP root are allowed.
remove_empty_parents	bool	If `True`, empty parent directories are removed after target cleanup.

Returns

Type	Description
str	Cleanup target id.

Examples

Use this public operation:

result = instance.cleanup(auto_remove=auto_remove_value)

clear(target: Path | str | None = None, *, allow_external: bool = False, remove_empty_parents: bool = False) → bool¶

Remove this runtime or a concrete target immediately.

If target is not provided, the current runtime root is removed. If target is provided, that concrete file or directory is removed.

Parameters

Name	Type	Description
target	Path \| str \| None	Optional concrete cleanup target. If omitted, `self.root` is used.
allow_external	bool	If `True`, paths outside the global DDP root are allowed.
remove_empty_parents	bool	If `True`, empty parent directories are removed after target cleanup.

Returns

Type	Description
bool	`True` if something existed and was removed, otherwise `False`.

Examples

Use this public operation:

result = instance.clear()

property temp_root: Path¶

Return the temp storage root.

Returns

Absolute path to ddp/<namespace>/temp.

Examples

Use this public operation:

result = instance.temp_root()

property cache_root: Path¶

Return the cache storage root.

Returns

Absolute path to ddp/<namespace>/cache.

Examples

Use this public operation:

result = instance.cache_root()

property state_root: Path¶

Return the cache storage root.

Returns

Absolute path to ddp/<namespace>/state.

Examples

Use this public operation:

result = instance.state_root()

property drivers_root: Path¶

Return the driver storage root.

Returns

Absolute path to ddp/<namespace>/drivers.

Examples

Use this public operation:

result = instance.drivers_root()

property config_root: Path¶

Return the config storage root.

Returns

Absolute path to ddp/<namespace>/config.

Examples

Use this public operation:

result = instance.config_root()

property data_root: Path¶

Return the data storage root.

Returns

Absolute path to ddp/<namespace>/data.

Examples

Use this public operation:

result = instance.data_root()

property logs_root: Path¶

Return the logs storage root.

Returns

Absolute path to ddp/<namespace>/logs.

Examples

Use this public operation:

result = instance.logs_root()

property locks_root: Path¶

Return the locks storage root.

Returns

Absolute path to ddp/<namespace>/locks.

Examples

Use this public operation:

result = instance.locks_root()

ensure_root() → Path¶

Ensure the global and namespace roots exist.

Returns

Type	Description
Path	The namespace root path.

Examples

Use this public operation:

result = instance.ensure_root()

ensure_all() → None¶

Ensure only system runtime directories exist eagerly.

This method creates:

root
temp
logs
locks

Other directories are created lazily on first access.

Examples

Use this public operation:

result = instance.ensure_all()

directory(*parts: object) → Path¶

Ensure and return a directory inside the runtime root.

Supported inputs:

plain strings
strings containing path separators
Path objects
tuples/lists with nested parts

Only relative paths inside the runtime root are allowed. Absolute paths and .. traversal are forbidden.

Parameters

Name	Type	Description
parts	object	Path fragments relative to the runtime root.

Returns

Type	Description
Path	Created or existing directory path.

Examples

Use this public operation:

result = instance.directory()