ddp_utils.runtime.cleanup

import ddp_utils.runtime.cleanup

Manage expiration-based cleanup records for files and directories.

The module registers and unregisters cleanup targets, removes expired targets, and clears individual targets immediately. Registry state is persisted as JSON through the public read and write helpers.

Examples

Read a cleanup registry without creating it:

from pathlib import Path
from ddp_utils.runtime.cleanup import read_cleanup_registry

registry = read_cleanup_registry(Path("cleanup.json"))

ddp_utils.runtime.cleanup.register_cleanup_target(*, registry_path: Path, global_root: Path, 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

Register a file or directory for automatic cleanup.

The registry stores absolute target paths and expiration datetimes. By default, cleanup targets must be located inside the global DDP runtime root. External targets are allowed only when allow_external=True is passed explicitly.

Parameters

Name	Type	Description
registry_path	Path	Path to the runtime cleanup registry file.
global_root	Path	Global DDP runtime root.
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, for example "tools", "scripts", or "shared".
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, stopping at the global DDP root for internal targets.

Returns

Type	Description
str	Stable cleanup target id.

Raises

Exception	Description
ValueError	If auto_remove cannot be parsed, or if the target is outside the global DDP root while allow_external is False.

Examples

Use this public operation:

result = ddp_utils.runtime.cleanup.register_cleanup_target(registry_path=registry_path_value, global_root=global_root_value, path=path_value, auto_remove=auto_remove_value)

ddp_utils.runtime.cleanup.unregister_cleanup_target(*, registry_path: Path, target_id: str) → None

Remove a cleanup target record by id.

Parameters

Name	Type	Description
registry_path	Path	Path to the runtime cleanup registry file.
target_id	str	Target id returned by register_cleanup_target.

Examples

Use this public operation:

result = ddp_utils.runtime.cleanup.unregister_cleanup_target(registry_path=registry_path_value, target_id=target_id_value)

ddp_utils.runtime.cleanup.unregister_matching_targets(*, registry_path: Path, path: Path | str, namespace: str | None = None, scope: str | None = None) → None

Remove cleanup target records matching a path and optional metadata.

Parameters

Name	Type	Description
registry_path	Path	Path to the runtime cleanup registry file.
path	Path | str	Target path.
namespace	str | None	Optional namespace filter.
scope	str | None	Optional scope filter.

Examples

Use this public operation:

result = ddp_utils.runtime.cleanup.unregister_matching_targets(registry_path=registry_path_value, path=path_value)

ddp_utils.runtime.cleanup.cleanup_expired_targets(*, registry_path: Path, global_root: Path) → list[dict[str, Any]]

Remove all expired cleanup targets.

The cleanup is best-effort. A locked file or a failed delete operation does not stop processing of other targets; the error is written into the returned result entry.

Parameters

Name	Type	Description
registry_path	Path	Path to the runtime cleanup registry file.
global_root	Path	Global DDP runtime root.

Returns

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

Examples

Use this public operation:

result = ddp_utils.runtime.cleanup.cleanup_expired_targets(registry_path=registry_path_value, global_root=global_root_value)

ddp_utils.runtime.cleanup.clear_target(*, path: Path | str, global_root: Path, allow_external: bool = False, remove_empty_parents: bool = False) → bool

Remove a file, symlink, or directory target.

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

Parameters

Name	Type	Description
path	Path | str	File or directory to remove.
global_root	Path	Global DDP runtime root.
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, stopping at the global DDP root for internal targets.

Returns

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

Raises

Exception	Description
ValueError	If the target is outside the global DDP root while allow_external is False.

Examples

Use this public operation:

result = ddp_utils.runtime.cleanup.clear_target(path=path_value, global_root=global_root_value)

ddp_utils.runtime.cleanup.read_cleanup_registry(registry_path: Path) → dict[str, Any]

Read cleanup registry file.

Parameters

Name	Type	Description
registry_path	Path	Path to the runtime cleanup registry file.

Returns

Type	Description
dict[str, Any]	Registry dictionary.

Examples

Use this public operation:

result = ddp_utils.runtime.cleanup.read_cleanup_registry(registry_path=registry_path_value)

ddp_utils.runtime.cleanup.write_cleanup_registry(registry_path: Path, registry: dict[str, Any]) → None

Write cleanup registry file.

Parameters

Name	Type	Description
registry_path	Path	Path to the runtime cleanup registry file.
registry	dict[str, Any]	Registry dictionary.

Examples

Use this public operation:

result = ddp_utils.runtime.cleanup.write_cleanup_registry(registry_path=registry_path_value, registry=registry_value)