ddp_utils.fs_utils¶

import ddp_utils.fs_utils

Filesystem paths, directory creation/cleanup, UUIDs and random identifiers.

Examples

Use this public operation:

import ddp_utils.fs_utils

ddp_utils.fs_utils.make_dir(path: str | PathLike | Path, parents: bool = True, exist_ok: bool = True) → Path¶

Create a directory and return its expanded Path.

Parameters

Name	Type	Description
path	str \| PathLike \| Path	String or path-like directory; a leading tilde is expanded.
parents	bool	Create missing parents when True; otherwise they must exist.
exist_ok	bool	Accept an existing directory when True; never accept a file.

Returns

Type	Description
Path	Path of the created or existing directory; relative paths remain relative.

Raises

Exception	Description
FileExistsError	The target exists and exist_ok=False, or is a file.
FileNotFoundError	A parent is missing and parents=False.
OSError	Creation fails, for example because permission is denied.

Examples

Use this public operation:

result = ddp_utils.fs_utils.make_dir(path=path_value)

ddp_utils.fs_utils.clear_dir(path: str | PathLike | Path) → Path¶

Delete all directory contents, preserving the directory itself.

Destructive and not transactional: earlier deletions are not rolled back if a later deletion fails. A missing directory is created with its parents.

Parameters

Name	Type	Description
path	str \| PathLike \| Path	Directory path; a leading tilde is expanded.

Returns

Type	Description
Path	Path of the empty directory.

Raises

Exception	Description
ValueError	An existing target is not a directory.
OSError	Creation or deletion fails; directory symlinks may be rejected by shutil.rmtree rather than followed or unlinked.

Examples

Use this public operation:

result = ddp_utils.fs_utils.clear_dir(path=path_value)

ddp_utils.fs_utils.get_path(*parts: str | PathLike | Path) → str¶

Join one or more path-like parts and normalize for the current platform.

Each part is expanded with Path.expanduser before os.path.join. Absolute later components can replace earlier components according to platform rules. This is lexical normalization, not a filesystem existence check.

Parameters

Name	Type	Description
*parts	str \| PathLike \| Path	Strings, pathlib.Path or other supported os.PathLike objects.

Returns

Type	Description
str	Normalized string path, not necessarily absolute.

Raises

Exception	Description
ValueError	No parts were supplied, or a part is None.
TypeError	A part cannot be converted to a Path.

Examples

Use this public operation:

result = ddp_utils.fs_utils.get_path()

ddp_utils.fs_utils.norm_str_path(path: str | PathLike | Path) → str¶

Expand the user directory and apply os.path.normpath.

Does not resolve symlinks, verify existence, or make relative paths absolute. Separators and parent-component normalization follow the current platform.

Parameters

Name	Type	Description
path	str \| PathLike \| Path	String or path-like value.

Returns

Type	Description
str	Normalized string; an empty input becomes the current-directory marker.

Examples

Use this public operation:

result = ddp_utils.fs_utils.norm_str_path(path=path_value)

ddp_utils.fs_utils.is_valid_path_format(path: str | None) → bool¶

Check whether a nonempty string is absolute on the current platform.

Parameters

Name	Type	Description
path	str \| None	Candidate string; None, nonstrings and whitespace return False.

Returns

Type	Description
bool	True if Path(path.strip()).expanduser().is_absolute(), else False. This does not check existence or validate foreign-platform path syntax.

Examples

Use this public operation:

result = ddp_utils.fs_utils.is_valid_path_format(path=path_value)

ddp_utils.fs_utils.generate_uuid(version: int = 4, as_hex: bool = False, short: bool = False, name: str | None = None, namespace: UUID | None = None) → str | UUID¶

Generate a UUID with optional formatting.

Parameters

Name	Type	Description
version	int	UUID version (1, 3, 4, or 5). Default 4 (random).
as_hex	bool	If True, return the 32‑character hex string without hyphens.
short	bool	Compatibility parameter; currently ignored for both output modes. Use generate_short_uuid for a separately generated short identifier.
name	str \| None	Required for versions 3 and 5 (the name to hash).
namespace	UUID \| None	Required for versions 3 and 5. Can be a UUID or one of the predefined namespaces (uuid.NAMESPACE_*).

Returns

Type	Description
str \| UUID	A UUID object if as_hex=False, otherwise all 32 hexadecimal characters. Versions 3 and 5 are deterministic for the same namespace and name. Versions 1 and 4 do not use name or namespace.

Raises

Exception	Description
ValueError	If required arguments for a version are missing, or if an unsupported version is requested.

Examples

Use this public operation:

result = ddp_utils.fs_utils.generate_uuid()

ddp_utils.fs_utils.generate_short_uuid(length: int = 8) → str¶

Generate a cryptographically random short identifier of hex characters.

Parameters

Name	Type	Description
length	int	Nonnegative even number of hex characters; zero returns an empty string.

Returns

Type	Description
str	A random hex string of the given length.

Raises

Exception	Description
ValueError	Length is odd or negative.
TypeError	Length cannot be used as a byte count.

Examples

Generate an eight-character hexadecimal identifier:

from ddp_utils.fs_utils import generate_short_uuid

identifier = generate_short_uuid(8)
assert len(identifier) == 8
assert all(character in "0123456789abcdef" for character in identifier)