platformdirs 4.11.0: PlatformDirs, user_cache_dir, user_config_dir

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:pypi/platformdirs@4.11.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/platformdirs@4.11.0
Demonstrate these symbols/APIs:
  - platformdirs.PlatformDirs
  - platformdirs.user_cache_dir
  - platformdirs.user_config_dir
  - platformdirs.user_data_dir
  - platformdirs.user_data_path
  - platformdirs.user_log_dir
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:a88c6b2941098ad7ecc8824df2cab021912dfdd5343859c6c09516821cfbf996","constraints":{"executionContext":"python"},"contract":["assert PlatformDirs constructs standard directory paths for user data, cache, config, and logs","assert user_data_dir, user_cache_dir, user_config_dir, and user_log_dir match PlatformDirs property values","assert user_data_path returns a pathlib.Path instance matching user_data_dir","assert XDG environment variables override default directory paths","assert opinion flag controls appending log subdirectory in user_log_dir","assert ensure_exists flag creates target directory on filesystem"],"goal":"verify pkg:pypi/platformdirs@4.11.0","kind":"HOW","packages":["pkg:pypi/platformdirs@4.11.0"],"schemaVersion":1,"symbols":["platformdirs.PlatformDirs","platformdirs.user_cache_dir","platformdirs.user_config_dir","platformdirs.user_data_dir","platformdirs.user_data_path","platformdirs.user_log_dir"]},"contractCommand":["python3","test/contract.py"],"environment":{"arch":"x64","distro":"alpine","ecosystem":"pypi","executionContext":"python","language":"python","libc":"musl","moduleSystem":"standard","os":"linux","osVersionBucket":"24","packageManager":"pip","packageManagerVersion":"24.0","runtime":"python","runtimeVersion":"3.12","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/platformdirs@4.11.0"],"schemaVersion":1,"subject":"pkg:pypi/platformdirs@4.11.0","symbols":["platformdirs.PlatformDirs","platformdirs.user_cache_dir","platformdirs.user_config_dir","platformdirs.user_data_dir","platformdirs.user_data_path","platformdirs.user_log_dir"],"verifierAdapter":"python@1"}

[project]
name = "verify-platformdirs"
version = "0.1.0"
dependencies = [
    "platformdirs==4.11.0",
]

platformdirs==4.11.0

{
  "schemaVersion": 1,
  "goal": "verify pkg:pypi/platformdirs@4.11.0",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/platformdirs@4.11.0"
  ],
  "symbols": [
    "platformdirs.PlatformDirs",
    "platformdirs.user_cache_dir",
    "platformdirs.user_config_dir",
    "platformdirs.user_data_dir",
    "platformdirs.user_data_path",
    "platformdirs.user_log_dir"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import os
import shutil
import tempfile
from pathlib import Path
from platformdirs import (
    PlatformDirs,
    user_cache_dir,
    user_config_dir,
    user_data_dir,
    user_data_path,
    user_log_dir,
)


def test_platform_dirs_properties():
    dirs = PlatformDirs(appname="testapp", appauthor=False, version="1.0")
    assert isinstance(dirs.user_data_dir, str)
    assert isinstance(dirs.user_cache_dir, str)
    assert isinstance(dirs.user_config_dir, str)
    assert isinstance(dirs.user_log_dir, str)
    assert isinstance(dirs.user_data_path, Path)

    assert "testapp" in dirs.user_data_dir
    assert dirs.user_data_dir.endswith("1.0")
    assert dirs.user_data_path == Path(dirs.user_data_dir)


def test_module_level_functions():
    app = "sample_app"
    ver = "2.0"
    dirs = PlatformDirs(appname=app, appauthor=False, version=ver)

    assert user_data_dir(app, False, version=ver) == dirs.user_data_dir
    assert user_cache_dir(app, False, version=ver) == dirs.user_cache_dir
    assert user_config_dir(app, False, version=ver) == dirs.user_config_dir
    assert user_log_dir(app, False, version=ver) == dirs.user_log_dir

    data_p = user_data_path(app, False, version=ver)
    assert isinstance(data_p, Path)
    assert data_p == Path(user_data_dir(app, False, version=ver))


def test_xdg_environment_overrides():
    orig_env = {k: os.environ.get(k) for k in ["XDG_DATA_HOME", "XDG_CONFIG_HOME", "XDG_CACHE_HOME", "XDG_STATE_HOME"]}
    base_dir = tempfile.mkdtemp(prefix="xdg_test_")
    try:
        mock_data = os.path.join(base_dir, "data")
        mock_config = os.path.join(base_dir, "config")
        mock_cache = os.path.join(base_dir, "cache")
        mock_state = os.path.join(base_dir, "state")

        os.environ["XDG_DATA_HOME"] = mock_data
        os.environ["XDG_CONFIG_HOME"] = mock_config
        os.environ["XDG_CACHE_HOME"] = mock_cache
        os.environ["XDG_STATE_HOME"] = mock_state

        app = "custom_app"
        ver = "3.0"
        dirs = PlatformDirs(appname=app, appauthor=False, version=ver)

        expected_data = os.path.join(mock_data, app, ver)
        expected_config = os.path.join(mock_config, app, ver)
        expected_cache = os.path.join(mock_cache, app, ver)
        expected_log = os.path.join(mock_state, app, ver, "log")

        assert dirs.user_data_dir == expected_data
        assert dirs.user_config_dir == expected_config
        assert dirs.user_cache_dir == expected_cache
        assert dirs.user_log_dir == expected_log

        assert user_data_dir(app, False, version=ver) == expected_data
        assert user_config_dir(app, False, version=ver) == expected_config
        assert user_cache_dir(app, False, version=ver) == expected_cache
        assert user_log_dir(app, False, version=ver) == expected_log
    finally:
        for k, v in orig_env.items():
            if v is None:
                os.environ.pop(k, None)
            else:
                os.environ[k] = v
        shutil.rmtree(base_dir, ignore_errors=True)


def test_opinion_log_dir():
    dirs_opinion = PlatformDirs(appname="opinion_app", appauthor=False, opinion=True)
    dirs_no_opinion = PlatformDirs(appname="opinion_app", appauthor=False, opinion=False)

    assert dirs_opinion.user_log_dir.endswith(os.path.join("opinion_app", "log"))
    assert dirs_no_opinion.user_log_dir.endswith("opinion_app")


def test_ensure_exists():
    tmp_base = tempfile.mkdtemp(prefix="pdirs_test_")
    orig_cache = os.environ.get("XDG_CACHE_HOME")
    try:
        os.environ["XDG_CACHE_HOME"] = tmp_base
        dirs = PlatformDirs(appname="ensure_app", appauthor=False, ensure_exists=True)
        created_path = dirs.user_cache_dir
        assert os.path.isdir(created_path)
    finally:
        if orig_cache is not None:
            os.environ["XDG_CACHE_HOME"] = orig_cache
        else:
            os.environ.pop("XDG_CACHE_HOME", None)
        shutil.rmtree(tmp_base, ignore_errors=True)


def main():
    test_platform_dirs_properties()
    test_module_level_functions()
    test_xdg_environment_overrides()
    test_opinion_log_dir()
    test_ensure_exists()
    print("All contract assertions passed.")


if __name__ == "__main__":
    main()