Path Utils

GitHub Link to Code.

Central path normalization and cache path helpers.

class mdxplain.utils.path_utils.PathUtils

Central utility methods for path handling.

Provides normalized absolute path handling and cache file path generation.

static prepare_file_path(path: str | PathLike, create_parent: bool = False, purpose: str = 'file path', resolve_symlinks: bool = True) → str

Normalize a filesystem path and optionally create its parent directory.

Parameters

pathstr or os.PathLike: Input file path.
create_parentbool, default=False: If True, create the parent directory of the normalized path.
purposestr, default=”file path”: Human-readable purpose for error messages.
resolve_symlinksbool, default=True: If True, canonicalize path aliases/symlinks via os.path.realpath.

Returns

str: Normalized absolute path.

static prepare_directory_path(path: str | PathLike, create: bool = False, purpose: str = 'directory path', resolve_symlinks: bool = True) → str

Normalize a directory path and optionally create it.

Parameters

pathstr or os.PathLike: Input directory path.
createbool, default=False: If True, create the directory after normalization.
purposestr, default=”directory path”: Human-readable purpose for error messages.
resolve_symlinksbool, default=True: If True, canonicalize path aliases/symlinks via os.path.realpath.

Returns

str: Normalized absolute directory path.

static get_cache_file_path(cache_name: str, cache_path: str = './cache') → str

Build a normalized absolute cache file path.

Parameters

cache_namestr: Cache file name (e.g. "distances.dat").
cache_pathstr, default=”./cache”: Cache directory or explicit cache file path.

Returns

str: Normalized absolute cache file path.

static create_pipeline_cache_dir(base_cache_dir: str | PathLike, *, pipeline_uuid: str | None = None, pipeline_timestamp: str | None = None, purpose: str = 'cache directory') → str

Create and return a per-pipeline scoped cache directory.

The resulting layout is: <base_cache_dir>/cache_<pipeline_uuid>_<YYYYMMDD_HHMMSS>.

Parameters

base_cache_dirstr or os.PathLike: User-provided cache root directory.
pipeline_uuidstr, optional: Stable pipeline instance UUID. Generated when omitted.
pipeline_timestampstr, optional: Stable timestamp tag for the pipeline. Generated when omitted.
purposestr, default=”cache directory”: Human-readable purpose for path validation errors.

Returns

str: Canonical absolute path to the scoped cache directory.