Skip to content

core.paths

Platform-aware base directory resolution for taskclf.

TASKCLF_HOME resolution order

All data, model, and artifact paths are anchored to a single root directory resolved by taskclf_home():

Priority Source Example
1 TASKCLF_HOME env var export TASKCLF_HOME=~/my-taskclf
2 macOS default ~/Library/Application Support/taskclf/
3 XDG default (Linux) ~/.local/share/taskclf/
4 Windows default %LOCALAPPDATA%/taskclf/

Directory layout

<TASKCLF_HOME>/
├── data/
│   ├── raw/aw/
│   └── processed/
├── models/
├── artifacts/
│   └── telemetry/
└── configs/

API reference

taskclf.core.paths

Platform-aware base directory resolution for taskclf.

Provides :func:taskclf_home which resolves the root data directory using the following precedence:

  1. TASKCLF_HOME environment variable (if set)
  2. ~/Library/Application Support/taskclf/ on macOS
  3. $XDG_DATA_HOME/taskclf/ (or ~/.local/share/taskclf/) on Linux
  4. %LOCALAPPDATA%/taskclf/ on Windows

All DEFAULT_* path constants in :mod:taskclf.core.defaults are derived from the value returned by this function.

logger = logging.getLogger(__name__) module-attribute

taskclf_home()

Return the resolved base directory for all taskclf data.

The result is always an absolute :class:~pathlib.Path.

Source code in src/taskclf/core/paths.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def taskclf_home() -> Path:
    """Return the resolved base directory for all taskclf data.

    The result is always an absolute :class:`~pathlib.Path`.
    """
    env = os.environ.get(_ENV_VAR)
    if env:
        return Path(env).expanduser().resolve()

    if sys.platform == "darwin":
        return Path.home() / "Library" / "Application Support" / "taskclf"

    if sys.platform == "win32":
        local = os.environ.get("LOCALAPPDATA")
        if local:
            return Path(local) / "taskclf"
        return Path.home() / "AppData" / "Local" / "taskclf"

    # Linux / BSDs / other POSIX
    xdg = os.environ.get("XDG_DATA_HOME", str(Path.home() / ".local" / "share"))
    return Path(xdg) / "taskclf"

ensure_taskclf_dirs()

Create the standard subdirectory tree under :func:taskclf_home.

Safe to call repeatedly — existing directories are left untouched. Returns the home path.

Source code in src/taskclf/core/paths.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
def ensure_taskclf_dirs() -> Path:
    """Create the standard subdirectory tree under :func:`taskclf_home`.

    Safe to call repeatedly — existing directories are left untouched.
    Returns the home path.
    """
    home = taskclf_home()
    for sub in _SUBDIRS:
        d = home / sub
        if not d.exists():
            d.mkdir(parents=True, exist_ok=True)
            logger.info("Created directory: %s", d)
    return home