Path utilities

Shared user-level directory utilities for Klea packages.

Wraps platformdirs.PlatformDirs to provide OS-appropriate paths for cache, data, and config directories (~/.cache/klea/, ~/.local/share/klea/, ~/.config/klea/ on Linux, with equivalents on macOS and Windows).

Consumers pass an app_name so that different packages (klea, nml_mcp) get isolated directories without repeating the boilerplate.

File: klea_utils/paths.py

Copyright 2026 Ankur Sinha Author: Ankur Sinha <sanjay DOT ankur AT gmail DOT com>

klea_utils.paths.cleanup_dir(path: str | Path) → None[source]

Remove all contents of path but keep the directory itself.

klea_utils.paths.get_cache_dir(dirs: Unix) → Path[source]

Return the OS-appropriate per-user cache directory for dirs.

On Linux: ~/.cache/{app_name}/ On macOS: ~/Library/Caches/{app_name}/ On Windows: C:\Users\<user>\AppData\Local\{app_name}\cache\

klea_utils.paths.get_config_dir(dirs: Unix) → Path[source]

Return the OS-appropriate per-user config directory for dirs.

On Linux: ~/.config/{app_name}/ On macOS: ~/Library/Preferences/{app_name}/ On Windows: C:\Users\<user>\AppData\Roaming\{app_name}\

klea_utils.paths.get_data_dir(dirs: Unix) → Path[source]

Return the OS-appropriate per-user data directory for dirs.

On Linux: ~/.local/share/{app_name}/ On macOS: ~/Library/Application Support/{app_name}/ On Windows: C:\Users\<user>\AppData\Local\{app_name}\

klea_utils.paths.init_dir(path: str | Path) → Path[source]

Create path (and parents) if it doesn’t exist.

Returns:

The same path as a Path for chaining.

klea_utils.paths.resolve_app_config_path(config_file: str, conf_dir: str | Path, cwd: str | Path | None = None) → Path[source]

Locate the application config file, checking the working directory first.

config_file may be an absolute path or a relative name/path. The working directory is searched before conf_dir (the per-app config directory), so a profile dropped in CWD overrides one installed in the config directory.

Parameters:

  • config_file – App config file path or bare filename

  • conf_dir – Config directory searched after the working directory

  • cwd – Working directory to search first (defaults to Path.cwd())

Returns:

The first existing match

Raises: