### Complete application directory setup

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/tutorial.rst

An example application class that utilizes PlatformDirs to manage persistent data, configuration, cache, logs, and state, ensuring directories are created and following platform conventions.

```python
import json
import logging
from pathlib import Path

from platformdirs import PlatformDirs


class MyApp:
    def __init__(self) -> None:
        dirs = PlatformDirs("MyApp", "AcmeCompany", ensure_exists=True)

        # Persistent data (database, downloads)
        self.db_path = dirs.user_data_path / "app.db"

        # User configuration
        self.config_path = dirs.user_config_path / "settings.json"

        # Cache for performance
        self.cache_dir = dirs.user_cache_path

        # Application logs
        log_file = dirs.user_log_path / "app.log"
        logging.basicConfig(filename=log_file, level=logging.INFO)

        # Window state and UI preferences
        self.state_path = dirs.user_state_path / "window.json"

    def load_config(self) -> dict:
        if self.config_path.exists():
            return json.loads(self.config_path.read_text())
        return {"theme": "light", "autosave": True}

```

```python
app = MyApp()
app.config_path
app.db_path
```

--------------------------------

### Install platformdirs

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/tutorial.rst

Install the platformdirs library using pip.

```console
pip install platformdirs
```

--------------------------------

### Set up development environment with tox

Source: https://github.com/tox-dev/platformdirs/blob/main/CONTRIBUTING.md

Create a development environment with all necessary dependencies installed in an editable mode.

```bash
tox r -e dev
```

--------------------------------

### Install tox

Source: https://github.com/tox-dev/platformdirs/blob/main/CONTRIBUTING.md

Install the tox tool, which is used for all development tasks in the project.

```bash
pip install tox
```

--------------------------------

### Get User Cache Directory with Customization

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/explanation.rst

This example shows how Black uses platformdirs.user_cache_path and allows customization via an environment variable.

```python
import os
from pathlib import Path
from platformdirs import user_cache_path


def get_cache_dir() -> Path:
    # Allow customization via environment variable
    default_cache_dir = user_cache_path("black")
    cache_dir = Path(os.environ.get("BLACK_CACHE_DIR", default_cache_dir))
    return cache_dir / __version__


CACHE_DIR = get_cache_dir()
```

--------------------------------

### PlatformDirs Class Usage

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Demonstrates basic usage of the `PlatformDirs` class to access various user and site-wide directory paths. It shows how to get string paths and `pathlib.Path` objects, and provides examples for user data, config, cache, state, log, and runtime directories on different platforms.

```APIDOC
## PlatformDirs Class Usage

### Description
Instantiate the `PlatformDirs` class with an application name and optional author/version to access platform-specific directory paths. The library automatically selects the correct backend for Linux, macOS, Windows, or Android.

### Method
```python
from platformdirs import PlatformDirs
from pathlib import Path

# Basic usage — all common directory types in one object
dirs = PlatformDirs(appname="SuperApp", appauthor="Acme", version="1.0")

# String properties
print(dirs.user_data_dir)
# Linux:   ~/.local/share/SuperApp/1.0
# macOS:   ~/Library/Application Support/SuperApp/1.0
# Windows: C:\Users\<User>\AppData\Local\Acme\SuperApp\1.0

print(dirs.user_config_dir)
# Linux:   ~/.config/SuperApp/1.0
# macOS:   ~/Library/Application Support/SuperApp/1.0
# Windows: C:\Users\<User>\AppData\Local\Acme\SuperApp\1.0

print(dirs.user_cache_dir)
# Linux:   ~/.cache/SuperApp/1.0
# macOS:   ~/Library/Caches/SuperApp/1.0
# Windows: C:\Users\<User>\AppData\Local\Acme\SuperApp\Cache\1.0

print(dirs.user_state_dir)
# Linux:   ~/.local/state/SuperApp/1.0
# macOS:   ~/Library/Application Support/SuperApp/1.0

print(dirs.user_log_dir)
# Linux:   ~/.local/state/SuperApp/1.0/log
# macOS:   ~/Library/Logs/SuperApp/1.0
# Windows: C:\Users\<User>\AppData\Local\Acme\SuperApp\1.0\Logs

print(dirs.user_runtime_dir)
# Linux:   /run/user/1000/SuperApp/1.0
# macOS:   ~/Library/Caches/TemporaryItems/SuperApp/1.0
# Windows: C:\Users\<User>\AppData\Local\Temp\Acme\SuperApp\1.0

# pathlib.Path variants (same names with _path suffix)
config_path: Path = dirs.user_config_path  # pathlib.Path object
config_path.mkdir(parents=True, exist_ok=True)
(config_path / "settings.toml").write_text("[app]\ndebug = false\n")

# Site-wide (system) directories
print(dirs.site_data_dir)
# Linux:   /usr/local/share/SuperApp/1.0
# macOS:   /Library/Application Support/SuperApp/1.0
# Windows: C:\ProgramData\Acme\SuperApp\1.0

print(dirs.site_config_dir)
# Linux:   /etc/xdg/SuperApp/1.0
# Windows: C:\ProgramData\Acme\SuperApp\1.0

print(dirs.site_cache_dir)
# Linux:   /var/cache/SuperApp/1.0
print(dirs.site_log_dir)
# Linux:   /var/log/SuperApp/1.0
print(dirs.site_state_dir)
# Linux:   /var/lib/SuperApp/1.0
print(dirs.site_runtime_dir)
# Linux:   /run/SuperApp/1.0
```
```

--------------------------------

### Initialize PlatformDirs and Access Directory Strings

Source: https://github.com/tox-dev/platformdirs/blob/main/README.md

Instantiate PlatformDirs with application and company names to get platform-specific directory paths as strings. Useful for general file path retrieval.

```python
from platformdirs import PlatformDirs

dirs = PlatformDirs("MyApp", "MyCompany")
dirs.user_data_dir  # ~/.local/share/MyApp (Linux)
dirs.user_config_dir  # ~/.config/MyApp (Linux)
dirs.user_cache_dir  # ~/.cache/MyApp (Linux)
dirs.user_state_dir  # ~/.local/state/MyApp (Linux)
dirs.user_log_dir  # ~/.local/state/MyApp/log (Linux)
dirs.user_documents_dir  # ~/Documents
dirs.user_downloads_dir  # ~/Downloads
dirs.user_runtime_dir  # /run/user/<uid>/MyApp (Linux)
```

--------------------------------

### Verify platformdirs installation

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/tutorial.rst

Check the installed version of platformdirs.

```python
import platformdirs
platformdirs.__version__
```

--------------------------------

### Use Site For Root Example

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/parameters.rst

When running as root, this setting redirects user directory calls to their site equivalents. Defaults to False for backward compatibility.

```python
from platformdirs import PlatformDirs

dirs = PlatformDirs("SuperApp", use_site_for_root=True)
# When running as root, user_data_dir returns the site_data_dir path
dirs.user_data_dir  # Returns site directory instead of /root/.local/share/SuperApp
```

--------------------------------

### Merge configuration from multiple sources

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/howto.rst

Use `iter_config_paths` to load configuration files, starting from site-wide defaults and overlaying user-specific overrides.

```python
import json
from platformdirs import PlatformDirs

dirs = PlatformDirs("MyApp")
config = {}

# Iterate from least specific (site) to most specific (user)
for config_dir in dirs.iter_config_paths():
    config_file = config_dir / "config.json"
    if config_file.exists():
        config.update(json.loads(config_file.read_text()))
```

--------------------------------

### Iterating User and Site Directories with platformdirs

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Use iterator methods like `iter_config_dirs()` or `iter_data_paths()` to get a sequence of user-specific and site-wide directories. This is the recommended approach for searching configuration or data across all relevant locations. The order is user-first, then site.

```python
from platformdirs import PlatformDirs

dirs = PlatformDirs("SuperApp", "Acme")

# iter_config_dirs / iter_config_paths
print("Config search order:")
for d in dirs.iter_config_dirs():
    print(f"  {d}")
# Linux output:
#   /home/alice/.config/SuperApp
#   /etc/xdg/SuperApp

print("Data search order:")
for p in dirs.iter_data_paths():
    print(f"  {p}")
# Linux output:
#   /home/alice/.local/share/SuperApp
#   /usr/local/share/SuperApp

# Available iterator methods:
# dirs.iter_config_dirs()    / dirs.iter_config_paths()
# dirs.iter_data_dirs()      / dirs.iter_data_paths()
# dirs.iter_cache_dirs()     / dirs.iter_cache_paths()
# dirs.iter_state_dirs()     / dirs.iter_state_paths()
# dirs.iter_log_dirs()       / dirs.iter_log_paths()
# dirs.iter_runtime_dirs()   / dirs.iter_runtime_paths()

# Practical: load first found plugin definitions
import json
from pathlib import Path

def find_plugins() -> list[dict]:
    for data_path in dirs.iter_data_paths():
        plugins_file = data_path / "plugins.json"
        if plugins_file.exists():
            return json.loads(plugins_file.read_text())
    return []

plugins = find_plugins()
print(f"Found {len(plugins)} plugins")
```

--------------------------------

### Manage User Configuration Files

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/explanation.rst

Use user_config_path to get the directory for configuration files and user preferences. Ensure the directory exists before writing files.

```python
from platformdirs import user_config_path
import json

config_file = user_config_path("MyApp") / "settings.json"
config_file.parent.mkdir(parents=True, exist_ok=True)

settings = {"theme": "dark", "auto_save": True}
config_file.write_text(json.dumps(settings))
```

--------------------------------

### User Configuration Directory Access

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Demonstrates how to obtain the per-user directory for configuration files using `user_config_dir` and `user_config_path`. Includes examples of writing and reading TOML configuration files and iterating through config paths.

```python
from platformdirs import user_config_dir, user_config_path
import tomllib, tomli_w  # pip install tomli-w

config_dir = user_config_dir("SuperApp", "Acme")
print(config_dir)
# Linux:   /home/alice/.config/SuperApp
# macOS:   /Users/alice/Library/Application Support/SuperApp
# Windows: C:\Users\Alice\AppData\Local\Acme\SuperApp

config_path = user_config_path("SuperApp", "Acme", ensure_exists=True)
config_file = config_path / "config.toml"

# Write default config if absent
if not config_file.exists():
    config_file.write_bytes(
        tomli_w.dumps({"theme": "dark", "language": "en", "autosave": True}).encode()
    )

# Read config
with config_file.open("rb") as f:
    settings = tomllib.load(f)
print(settings["theme"])  # dark

# Search all config locations (user first, then system)
from platformdirs import PlatformDirs
dirs = PlatformDirs("SuperApp", "Acme")
for config_location in dirs.iter_config_paths():
    candidate = config_location / "config.toml"
    if candidate.exists():
        print(f"Found config at: {candidate}")
        break
```

--------------------------------

### Get Multiple Site Data Directories on Unix/macOS

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/parameters.rst

On Unix/macOS, `multipath=True` makes `site_data_dir` and `site_config_dir` return all directories from `XDG_DATA_DIRS`/`XDG_CONFIG_DIRS` joined by `os.pathsep`.

```pycon
>>> from platformdirs import site_data_dir
>>> site_data_dir("SuperApp", multipath=True)  # on Linux
'/usr/local/share/SuperApp:/usr/share/SuperApp'
```

--------------------------------

### Get User Configuration Path

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/explanation.rst

Retrieves the user-specific configuration path for an application. Each user has their own configuration directory.

```python
from platformdirs import user_config_path

# Each user gets their own config
config = user_config_path("MyApp") / "config.json"
```

--------------------------------

### Application Launcher Directories

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Provides directories for application launchers, such as `.desktop` files on Linux, app bundles on macOS, and Start Menu shortcuts on Windows. These functions return the container directory itself and do not append application name or version.

```APIDOC
## user_applications_dir() / site_applications_dir() — Application launcher directories

### Description
Returns directories for application launchers: `.desktop` files on Linux, app bundles on macOS, and Start Menu shortcuts on Windows. These properties do not append `appname` or `version`, as they point to the container directory itself.

### Usage
```python
from platformdirs import user_applications_dir, user_applications_path
from platformdirs import site_applications_dir, site_applications_path

print(user_applications_dir())
# Linux:   /home/alice/.local/share/applications
# macOS:   /Users/alice/Applications
# Windows: C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Start Menu\Programs

print(site_applications_dir())
# Linux:   /usr/share/applications  (or all dirs if multipath=True)
# macOS:   /Applications
# Windows: C:\ProgramData\Microsoft\Windows\Start Menu\Programs

# Create a .desktop launcher file on Linux
import sys
if sys.platform.startswith("linux"):
    from pathlib import Path
    app_dir = user_applications_path()
    app_dir.mkdir(parents=True, exist_ok=True)
    desktop_file = app_dir / "superapp.desktop"
    desktop_file.write_text(
        "[Desktop Entry]\n"
        "Name=SuperApp\n"
        "Exec=/usr/bin/superapp\n"
        "Type=Application\n"
        "Categories=Utility;\n"
    )
    print(f"Launcher created: {desktop_file}")
```
```

--------------------------------

### Configure User Log Files

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/explanation.rst

Use user_log_path to get the directory for application logs. Ensure the directory exists and configure logging to write to the specified file.

```python
import logging
from platformdirs import user_log_path

log_file = user_log_path("MyApp") / "app.log"
log_file.parent.mkdir(parents=True, exist_ok=True)

logging.basicConfig(
    filename=log_file,
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s",
)
```

--------------------------------

### Access User and Site Application Launcher Directories

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Returns directories for application launchers like .desktop files, app bundles, or Start Menu shortcuts. These properties do not append appname or version.

```python
from platformdirs import user_applications_dir, user_applications_path
from platformdirs import site_applications_dir, site_applications_path

print(user_applications_dir())
# Linux:   /home/alice/.local/share/applications
# macOS:   /Users/alice/Applications
# Windows: C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Start Menu\Programs

print(site_applications_dir())
# Linux:   /usr/share/applications  (or all dirs if multipath=True)
# macOS:   /Applications
# Windows: C:\ProgramData\Microsoft\Windows\Start Menu\Programs

# Create a .desktop launcher file on Linux
import sys
if sys.platform.startswith("linux"):
    from pathlib import Path
    app_dir = user_applications_path()
    app_dir.mkdir(parents=True, exist_ok=True)
    desktop_file = app_dir / "superapp.desktop"
    desktop_file.write_text(
        "[Desktop Entry]\n"
        "Name=SuperApp\n"
        "Exec=/usr/bin/superapp\n"
        "Type=Application\n"
        "Categories=Utility;\n"
    )
    print(f"Launcher created: {desktop_file}")
```

--------------------------------

### Get User Runtime Directory and Path

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Returns the per-user directory for runtime files like sockets and PID files. `ensure_exists=True` creates the directory if it doesn't exist. This is useful for creating PID files or Unix domain sockets.

```python
from platformdirs import user_runtime_dir, user_runtime_path
import os, socket

runtime_dir = user_runtime_dir("SuperApp", "Acme")
print(runtime_dir)
# Linux:   /run/user/1000/SuperApp
# macOS:   /Users/alice/Library/Caches/TemporaryItems/SuperApp
# Windows: C:\Users\Alice\AppData\Local\Temp\Acme\SuperApp

runtime_path = user_runtime_path("SuperApp", "Acme", ensure_exists=True)

# Write a PID file to signal the app is running
pid_file = runtime_path / "app.pid"
pid_file.write_text(str(os.getpid()))
print(f"PID file: {pid_file}")

# Create a Unix domain socket (Linux/macOS)
sock_path = str(runtime_path / "control.sock")
if os.path.exists(sock_path):
    os.unlink(sock_path)
server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
server.bind(sock_path)
server.listen(1)
print(f"Listening on: {sock_path}")
server.close()
os.unlink(sock_path)
pid_file.unlink()
```

--------------------------------

### Get Site Data and Config Directories

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Retrieves system-wide directories readable by all users, typically writable by administrators. Use these for read-only resources shipped with the application. `multipath=True` returns all candidate directories as a colon-separated string on Unix/macOS.

```python
from platformdirs import site_data_dir, site_config_dir
from platformdirs import PlatformDirs

# Single site paths
print(site_data_dir("SuperApp", "Acme"))
# Linux:   /usr/local/share/SuperApp
# macOS:   /Library/Application Support/SuperApp
# Windows: C:\ProgramData\Acme\SuperApp

print(site_config_dir("SuperApp", "Acme"))
# Linux:   /etc/xdg/SuperApp
# macOS:   /Library/Application Support/SuperApp

# multipath — get all site data dirs as colon-separated string (Unix/macOS only)
print(site_data_dir("SuperApp", multipath=True))
# Linux: /usr/local/share/SuperApp:/usr/share/SuperApp
```

--------------------------------

### Get User Log Directory and Path

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Provides the per-user directory for log files. `ensure_exists=True` creates the directory if it doesn't exist. This is useful for configuring Python's logging to write to a platform-appropriate location.

```python
from platformdirs import user_log_dir, user_log_path
import logging

log_dir = user_log_dir("SuperApp", "Acme")
print(log_dir)
# Linux:   /home/alice/.local/state/SuperApp/log
# macOS:   /Users/alice/Library/Logs/SuperApp
# Windows: C:\Users\Alice\AppData\Local\Acme\SuperApp\Logs

log_path = user_log_path("SuperApp", "Acme", ensure_exists=True)
log_file = log_path / "app.log"

# Configure Python's logging to write to the platform log dir
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    handlers=[
        logging.FileHandler(log_file),
        logging.StreamHandler(),
    ],
)
logger = logging.getLogger(__name__)
logger.info("Application started")
logger.warning("Cache is stale, refreshing...")
# Log written to platform-appropriate location
```

--------------------------------

### Get User State Directory and Path

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Retrieves the per-user directory for non-essential runtime state. `ensure_exists=True` creates the directory if it doesn't exist. This is useful for saving UI state like window positions.

```python
from platformdirs import user_state_dir, user_state_path
import json

state_dir = user_state_dir("SuperApp", "Acme")
print(state_dir)
# Linux:   /home/alice/.local/state/SuperApp
# macOS:   /Users/alice/Library/Application Support/SuperApp
# Windows: C:\Users\Alice\AppData\Local\Acme\SuperApp

state_path = user_state_path("SuperApp", "Acme", ensure_exists=True)
state_file = state_path / "window_state.json"

# Save UI state
window_state = {"x": 100, "y": 200, "width": 1024, "height": 768, "maximized": False}
state_file.write_text(json.dumps(window_state, indent=2))

# Restore on next launch
if state_file.exists():
    restored = json.loads(state_file.read_text())
    print(f"Restoring window: {restored['width']}x{restored['height']}")
```

--------------------------------

### PlatformDirs Initialization Options

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Demonstrates different initialization options for PlatformDirs, including automatic directory creation, disabling opinionated subdirectories, and handling multipath directories.

```python
from platformdirs import PlatformDirs

# ensure_exists=True — auto-create the directory (and parents) on first access
dirs_auto = PlatformDirs("SuperApp", "Acme", ensure_exists=True)
_ = dirs_auto.user_log_dir   # directory is created immediately on access

# opinion=False — disable opinionated subdirectories (e.g. no Cache/ or Logs/ on Windows)
dirs_raw = PlatformDirs("SuperApp", "Acme", opinion=False)
print(dirs_raw.user_cache_dir)
# Windows: C:\Users\<User>\AppData\Local\Acme\SuperApp  (no \Cache suffix)
print(dirs_raw.user_log_dir)
# Windows: C:\Users\<User>\AppData\Local\Acme\SuperApp  (no \Logs suffix)

# multipath=True — return all site dirs as colon-separated string (Unix/macOS)
dirs_multi = PlatformDirs("SuperApp", multipath=True)
print(dirs_multi.site_data_dir)
# Linux: /usr/local/share/SuperApp:/usr/share/SuperApp

# use_site_for_root=True — redirect user_* dirs to site_* when running as root (Unix)
dirs_root = PlatformDirs("SuperApp", use_site_for_root=True)
# When uid == 0: dirs_root.user_data_dir == dirs_root.site_data_dir
```

--------------------------------

### User Cache Directory Access

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Illustrates how to get the per-user directory for cached data using `user_cache_dir` and `user_cache_path`. Provides a practical example of a `fetch_with_cache` function for downloading and caching URLs.

```python
from platformdirs import user_cache_dir, user_cache_path
import hashlib, urllib.request

cache_dir = user_cache_dir("SuperApp", "Acme", version="1.0")
print(cache_dir)
# Linux:   /home/alice/.cache/SuperApp/1.0
# macOS:   /Users/alice/Library/Caches/SuperApp/1.0
# Windows: C:\Users\Alice\AppData\Local\Acme\SuperApp\Cache\1.0

cache_path = user_cache_path("SuperApp", "Acme", ensure_exists=True)

def fetch_with_cache(url: str) -> bytes:
    """Download a URL, caching the result locally."""
    key = hashlib.sha256(url.encode()).hexdigest()[:16]
    cached_file = cache_path / key
    if cached_file.exists():
        print(f"Cache hit: {cached_file}")
        return cached_file.read_bytes()
    print(f"Cache miss, downloading: {url}")
    data = urllib.request.urlopen(url).read()  # noqa: S310
    cached_file.write_bytes(data)
    return data
```

--------------------------------

### Build documentation with tox

Source: https://github.com/tox-dev/platformdirs/blob/main/CONTRIBUTING.md

Build and check the project documentation using tox. The output will be available in .tox/docs_out/html/index.html.

```bash
tox r -e docs
```

--------------------------------

### User Data Directory Access

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Shows how to get the per-user directory for persistent application data using `user_data_dir` (string) and `user_data_path` (Path object). Includes an example of storing and loading JSON data and auto-creating directories.

```python
from platformdirs import user_data_dir, user_data_path
import json
from pathlib import Path

# Convenience function — returns str
data_dir = user_data_dir("SuperApp", "Acme", version="1.0")
print(data_dir)
# Linux:   /home/alice/.local/share/SuperApp/1.0
# macOS:   /Users/alice/Library/Application Support/SuperApp/1.0
# Windows: C:\Users\Alice\AppData\Local\Acme\SuperApp\1.0

# Path variant — returns pathlib.Path
data_path: Path = user_data_path("SuperApp", "Acme", version="1.0")

# Real usage: storing a JSON database
db_file = data_path / "userdata.json"
data_path.mkdir(parents=True, exist_ok=True)
db_file.write_text(json.dumps({"user": "alice", "score": 42}))
loaded = json.loads(db_file.read_text())
assert loaded["score"] == 42

# Auto-create with ensure_exists
safe_path = user_data_path("SuperApp", "Acme", ensure_exists=True)
(safe_path / "profile.json").write_text("{}")   # directory guaranteed to exist
```

--------------------------------

### opinion

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/parameters.rst

When True (the default), certain directories get an opinionated subdirectory. For example, on Windows the cache directory includes a Cache subdirectory, and the log directory includes Logs. On Linux, the log directory appends /log. Set to False to suppress this.

```APIDOC
## opinion

### Description
When ``True`` (the default), certain directories get an opinionated subdirectory. For example, on Windows the cache
directory includes a ``Cache`` subdirectory, and the log directory includes ``Logs``. On Linux, the log directory
appends ``/log``. Set to ``False`` to suppress this:

### Type
``bool``

### Default
``True``
```

--------------------------------

### Initialize PlatformDirs and Access Directory Paths

Source: https://github.com/tox-dev/platformdirs/blob/main/README.md

Instantiate PlatformDirs to retrieve platform-specific directory paths as pathlib.Path objects. Recommended when path manipulation is needed.

```python
from platformdirs import PlatformDirs

dirs = PlatformDirs("MyApp", "MyCompany")
dirs.user_data_path  # pathlib.Path('~/.local/share/MyApp')
dirs.user_config_path  # pathlib.Path('~/.config/MyApp')
```

--------------------------------

### Test application initialization with mocked directories

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/howto.rst

Use `unittest.mock.MagicMock` and `tmp_path` to simulate directory structures and file contents for testing code that relies on `platformdirs`.

```python
from platformdirs import PlatformDirs
import json
from unittest.mock import MagicMock


def my_app_init(dirs: PlatformDirs) -> dict:
    config_file = dirs.user_config_path / "config.json"
    if config_file.exists():
        return json.loads(config_file.read_text())
    return {}


def test_loads_config(tmp_path):
    config_file = tmp_path / "config.json"
    config_file.write_text('{"theme": "dark"}')

    dirs = MagicMock()
    dirs.user_config_path = tmp_path

    result = my_app_init(dirs)
```

--------------------------------

### Linux: falling back from site to user config

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/howto.rst

Provides a recipe for falling back from site configuration directories (requiring root) to user configuration directories for normal users.

```python
from platformdirs import site_config_path, user_config_path
import os

site_cfg = site_config_path("MyApp") / "defaults.conf"

if os.access(site_cfg.parent, os.W_OK):
    site_cfg.write_text("[defaults]\n")
else:
    user_cfg = user_config_path("MyApp") / "config.conf"
    user_cfg.parent.mkdir(parents=True, exist_ok=True)
    user_cfg.write_text("[user_settings]\n")
```

--------------------------------

### Get User Data Path

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/explanation.rst

Use user_data_path to get the directory for persistent application data. This is suitable for databases, downloaded files, and user-created content.

```python
from platformdirs import user_data_path

db_path = user_data_path("MyApp") / "app.db"
downloads_dir = user_data_path("MyApp") / "downloads"
```

--------------------------------

### Get Real On-Disk Path on Windows

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/explanation.rst

On Windows, use os.path.realpath on the path returned by platformdirs after creation to get the actual on-disk path for external processes.

```python
import os
import platformdirs

data_dir = platformdirs.user_data_dir(
    appname="MyApp", appauthor="Acme", ensure_exists=True
)
real_dir = os.path.realpath(data_dir)
```

--------------------------------

### Create directories safely with platformdirs

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/howto.rst

Always create parent directories before writing files. Use `mkdir(parents=True, exist_ok=True)` to ensure the directory exists.

```python
from pathlib import Path
from platformdirs import user_data_path

data_dir = user_data_path("MyApp")
db_file = data_dir / "data.db"

# Create directory if it doesn't exist
db_file.parent.mkdir(parents=True, exist_ok=True)

# Now safe to write
db_file.write_bytes(b"...")
```

--------------------------------

### Get User Data Directory

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/parameters.rst

Use `user_data_dir` to get the path to the user's data directory. When `appname` is None, the base platform directory is returned without an app-specific subdirectory.

```pycon
>>> from platformdirs import user_data_dir
>>> user_data_dir("SuperApp")
'/Users/trentm/Library/Application Support/SuperApp'
>>> user_data_dir()
'/Users/trentm/Library/Application Support'
```

--------------------------------

### PlatformDirs Constructor Parameters

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Explains the constructor parameters for the `PlatformDirs` class that allow fine-tuning path behavior, including `appname`, `appauthor`, `version`, and `roaming`.

```APIDOC
## PlatformDirs constructor parameters — Controlling path behavior

### Description
The `PlatformDirs.__init__` accepts parameters that fine-tune how paths are composed and managed. All are optional and affect every directory property on the instance.

### Parameters
- **appname** (str) - The name of the application.
- **appauthor** (str | False) - The name of the application author. On Windows, this is used to create a subdirectory. Pass `False` to omit the author directory on Windows.
- **version** (str) - The version of the application. This is appended to the path.
- **roaming** (bool) - On Windows, if `True`, uses roaming `AppData` which is synced across network logins. Defaults to `False`.

### Method
```python
from platformdirs import PlatformDirs

# appname / appauthor / version — path composition
dirs = PlatformDirs(
    appname="SuperApp",
    appauthor="Acme",     # Windows: adds Acme\ prefix. Pass False to omit entirely.
    version="2.1",        # appends version segment to the path
)
print(dirs.user_data_dir)
# Windows: C:\Users\<User>\AppData\Local\Acme\SuperApp\2.1

# appauthor=False — skip the author directory on Windows
dirs_no_author = PlatformDirs("SuperApp", appauthor=False)
print(dirs_no_author.user_data_dir)
# Windows: C:\Users\<User>\AppData\Local\SuperApp

# roaming=True — use roaming AppData on Windows (synced across network login)
dirs_roaming = PlatformDirs("SuperApp", "Acme", roaming=True)
print(dirs_roaming.user_data_dir)
# Windows: C:\Users\<User>\AppData\Roaming\Acme\SuperApp
```
```

--------------------------------

### Get user log directory

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/tutorial.rst

Retrieve the platform-specific user log directory for an application.

```python
from platformdirs import user_log_dir
user_log_dir("MyApp", "AcmeCompany")
```

--------------------------------

### Get user cache directory

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/tutorial.rst

Retrieve the platform-specific user cache directory for an application.

```python
from platformdirs import user_cache_dir
user_cache_dir("MyApp", "AcmeCompany")
```

--------------------------------

### Initialize PlatformDirs with opinion=False

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Disables the Cache/ subdirectory on Windows when initializing PlatformDirs.

```python
from platformdirs import PlatformDirs
dirs = PlatformDirs("SuperApp", "Acme", opinion=False)
print(dirs.user_cache_dir)
# Windows: C:\Users\Alice\AppData\Local\Acme\SuperApp  (no \Cache suffix)
```

--------------------------------

### Get user data path as pathlib.Path

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/tutorial.rst

Retrieve the platform-specific user data directory as a pathlib.Path object.

```python
from platformdirs import user_data_path
user_data_path("MyApp", "AcmeCompany")
```

--------------------------------

### Binary/Executable Directories

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Provides directories for user-installed or system-wide executables and scripts. `user_bin_dir` is typically `~/.local/bin` on Linux/macOS and `%LOCALAPPDATA%\Programs` on Windows. `site_bin_dir` is `/usr/local/bin` on Linux/macOS and `C:\ProgramData\bin` on Windows.

```APIDOC
## user_bin_dir() / site_bin_dir() — Binary/executable directories

### Description
Returns directories for user-installed or system-wide executables and scripts. On Linux and macOS `user_bin_dir` is `~/.local/bin`; on Windows it is `%LOCALAPPDATA%\Programs`. `site_bin_dir` returns `/usr/local/bin` on Linux/macOS and `C:\ProgramData\bin` on Windows. These properties do not append `appname` or `version`.

### Usage
```python
from platformdirs import user_bin_dir, user_bin_path, site_bin_dir, site_bin_path

print(user_bin_dir())   # Linux/macOS: /home/alice/.local/bin  |  Windows: C:\Users\Alice\AppData\Local\Programs
print(site_bin_dir())   # Linux/macOS: /usr/local/bin          |  Windows: C:\ProgramData\bin

# Check if a user-installed script is present
user_bin = user_bin_path()
my_script = user_bin / "my-tool"
if not my_script.exists():
    print(f"Install script to: {my_script}")
    # my_script.write_text("#!/usr/bin/env python3\nprint('hello')\n")
    # my_script.chmod(0o755)
else:
    print(f"Found: {my_script}")

# Install location selection helper
import sys
is_root = (sys.platform != "win32" and __import__("os").getuid() == 0)
install_target = site_bin_path() if is_root else user_bin_path()
print(f"Will install to: {install_target}")
```
```

--------------------------------

### Create directories automatically with PlatformDirs

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/howto.rst

Use `ensure_exists=True` when initializing `PlatformDirs` to automatically create directories as needed.

```python
from platformdirs import PlatformDirs

dirs = PlatformDirs("MyApp", ensure_exists=True)
db_file = dirs.user_data_path / "data.db"
db_file.write_bytes(b"...")  # Directory already exists
```

--------------------------------

### Get User Cache Directory

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/explanation.rst

Use user_cache_path to obtain the directory for cacheable data. This data can be safely deleted without losing functionality.

```python
from platformdirs import user_cache_path

cache_dir = user_cache_path("MyApp")
thumbnail_cache = cache_dir / "thumbnails"
api_cache = cache_dir / "api_responses"
```

--------------------------------

### Windows roaming vs local profiles

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/howto.rst

Shows how to use 'roaming=True' for settings that should sync across domain-joined machines, and the default behavior for local settings.

```python
from platformdirs import user_config_path, user_cache_path

# Synced across domain computers
roaming_cfg = user_config_path("MyApp", roaming=True)

# Local to this machine
local_cache = user_cache_path("MyApp")
```

--------------------------------

### Load Configuration with PlatformDirs

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Loads a JSON configuration file, prioritizing user settings over system defaults. It iterates through configuration paths provided by PlatformDirs.

```python
from platformdirs import PlatformDirs

dirs = PlatformDirs("SuperApp", "Acme")

def load_config(filename: str) -> dict:
    """Load config, preferring user settings over system defaults."""
    import json
    for path in dirs.iter_config_paths():
        candidate = path / filename
        if candidate.exists():
            return json.loads(candidate.read_text())
    return {}  # no config found anywhere

config = load_config("defaults.json")
```

--------------------------------

### Get User Home Directory

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/parameters.rst

Platformdirs does not provide a property for the user's home directory. Use pathlib.Path.home or os.path.expanduser from the standard library instead.

```pycon
>>> from pathlib import Path
>>> Path.home()
PosixPath('/Users/trentm')
```

--------------------------------

### Control Opinionated Subdirectories

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/parameters.rst

When `opinion=True` (default), certain directories get opinionated subdirectories (e.g., 'Cache' for cache dirs). Set to `False` to suppress these.

```pycon
>>> user_cache_dir("SuperApp", "Acme")  # on Windows, opinion=True
'C:\Users\trentm\AppData\Local\Acme\SuperApp\Cache'
>>> user_cache_dir("SuperApp", "Acme", opinion=False)  # on Windows
'C:\Users\trentm\AppData\Local\Acme\SuperApp'
```

--------------------------------

### PlatformDirs Constructor Parameters

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Control path composition and management using constructor parameters like appname, appauthor, version, and roaming. The `appauthor=False` option omits the author directory on Windows. `roaming=True` uses the roaming AppData folder on Windows.

```python
from platformdirs import PlatformDirs

# appname / appauthor / version — path composition
dirs = PlatformDirs(
    appname="SuperApp",
    appauthor="Acme",     # Windows: adds Acme\ prefix. Pass False to omit entirely.
    version="2.1",        # appends version segment to the path
)
print(dirs.user_data_dir)
# Windows: C:\Users\<User>\AppData\Local\Acme\SuperApp\2.1

# appauthor=False — skip the author directory on Windows
dirs_no_author = PlatformDirs("SuperApp", appauthor=False)
print(dirs_no_author.user_data_dir)
# Windows: C:\Users\<User>\AppData\Local\SuperApp

# roaming=True — use roaming AppData on Windows (synced across network login)
dirs_roaming = PlatformDirs("SuperApp", "Acme", roaming=True)
print(dirs_roaming.user_data_dir)
# Windows: C:\Users\<User>\AppData\Roaming\Acme\SuperApp
```

--------------------------------

### Linux: redirecting user directories when running as root

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/howto.rst

Explains how to use 'use_site_for_root=True' to make system services write to '/usr/local/share' instead of '/root' when running as root.

```python
from platformdirs import PlatformDirs
import os

if os.geteuid() == 0:
    dirs = PlatformDirs("myservice", use_site_for_root=True)
    # user_data_dir now returns /usr/local/share/myservice
else:
    dirs = PlatformDirs("myservice")
    # user_data_dir returns ~/.local/share/myservice
```

--------------------------------

### macOS: separating data and config

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/howto.rst

Demonstrates how to use subdirectories to separate data and configuration concerns on macOS, as both user_data_dir and user_config_dir resolve to the same base path.

```python
from platformdirs import user_data_path

app_dir = user_data_path("MyApp")
config_dir = app_dir / "config"
databases_dir = app_dir / "databases"
```

--------------------------------

### List available tox environments

Source: https://github.com/tox-dev/platformdirs/blob/main/CONTRIBUTING.md

View all available tox environments for running development tasks.

```bash
tox list
```

--------------------------------

### XDG Environment Variable Override

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/parameters.rst

On Linux and macOS, XDG environment variables like XDG_CONFIG_HOME override default directories when set. This example shows setting XDG_CONFIG_HOME.

```pycon
>>> import os
>>> os.environ["XDG_CONFIG_HOME"] = "/Users/trentm/.config"
>>> user_config_dir("SuperApp")
'/Users/trentm/.config/SuperApp'
```

--------------------------------

### Get user data directory

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/tutorial.rst

Retrieve the platform-specific user data directory for an application. The appauthor parameter defaults to appname if not provided. On Windows, omitting appauthor results in a flatter directory structure.

```python
from platformdirs import user_data_dir
user_data_dir("MyApp", "AcmeCompany")
```

```python
user_data_dir("MyApp", appauthor=False)  # on Windows
```

--------------------------------

### Check directory writability with platformdirs

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/howto.rst

Use `os.access` with `os.W_OK` to test if a directory is writable before attempting to write files to it.

```python
from platformdirs import user_cache_path
import os

cache_dir = user_cache_path("MyApp")
cache_dir.mkdir(parents=True, exist_ok=True)

if os.access(cache_dir, os.W_OK):
    # Directory is writable
    cache_file = cache_dir / "cache.dat"
    cache_file.write_bytes(b"...")
else:
    # Handle read-only directory
    print(f"Warning: {cache_dir} is not writable")
```

--------------------------------

### Access User and Site Binary Directories

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Provides directories for user-installed or system-wide executables. These functions do not append appname or version.

```python
from platformdirs import user_bin_dir, user_bin_path, site_bin_dir, site_bin_path

print(user_bin_dir())   # Linux/macOS: /home/alice/.local/bin  |  Windows: C:\Users\Alice\AppData\Local\Programs
print(site_bin_dir())   # Linux/macOS: /usr/local/bin          |  Windows: C:\ProgramData\bin

# Check if a user-installed script is present
user_bin = user_bin_path()
my_script = user_bin / "my-tool"
if not my_script.exists():
    print(f"Install script to: {my_script}")
    # my_script.write_text("#!/usr/bin/env python3\nprint('hello')\n")
    # my_script.chmod(0o755)
else:
    print(f"Found: {my_script}")

# Install location selection helper
import sys
is_root = (sys.platform != "win32" and __import__("os").getuid() == 0)
install_target = site_bin_path() if is_root else user_bin_path()
print(f"Will install to: {install_target}")
```

--------------------------------

### Command-line Interface for Path Inspection

Source: https://context7.com/tox-dev/platformdirs/llms.txt

Inspect all directory paths on the current system using the command-line interface by running `python -m platformdirs`. This tool prints properties for a sample app, demonstrating path variations with and without version or app author information.

```bash
# Print all platform directories for the current system
python -m platformdirs

# Example output on Linux:
# -- platformdirs 4.9.6 --
# -- app dirs (with optional 'version')

```

--------------------------------

### Manage multiple directories with PlatformDirs

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/tutorial.rst

Instantiate PlatformDirs to access multiple directory properties (data, config, cache, log, state) for an application. The ensure_exists=True option creates directories if they do not exist.

```python
from platformdirs import PlatformDirs
dirs = PlatformDirs("MyApp", "AcmeCompany")
dirs.user_data_dir
dirs.user_config_dir
dirs.user_cache_dir
dirs.user_log_dir
```

```python
dirs.user_data_path
dirs.user_cache_path
```

```python
dirs = PlatformDirs("MyApp", "AcmeCompany", ensure_exists=True)
dirs.user_data_dir  # directory is created if it doesn't exist
```

--------------------------------

### Get Virtualenv App Data Directory

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/explanation.rst

Retrieves the user data directory for virtualenv, with an option to override via an environment variable. Ensures the directory exists and is writable, falling back to the system's temporary directory if necessary.

```python
import os
from platformdirs import user_data_dir


def get_app_data_dir(env):
    key = "VIRTUALENV_OVERRIDE_APP_DATA"
    if key in env:
        return env[key]
    return user_data_dir(appname="virtualenv", appauthor="pypa")


folder = get_app_data_dir(os.environ)
folder = os.path.abspath(folder)

# Create directory and check writability
os.makedirs(folder, exist_ok=True)
if not os.access(folder, os.W_OK):
    # Fallback to temp directory
    folder = tempfile.gettempdir()
```

--------------------------------

### Ensure Directory Existence on Access

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/parameters.rst

Set `ensure_exists=True` to automatically create the directory, including parent directories, when the directory property is accessed.

```python
from platformdirs import PlatformDirs

dirs = PlatformDirs("SuperApp", "Acme", ensure_exists=True)
dirs.user_cache_dir  # directory is created if it does not exist
```

--------------------------------

### Site Bin Path

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/api.rst

Provides the path to the system-wide executable directory, available to all users.

```APIDOC
## site_bin_path

### Description
Returns the path to the system-wide executables directory.

### Function Signature
`platformdirs.site_bin_path()`

### Returns
string: The path to the site-wide bin directory.
```

--------------------------------

### Site Bin Directory

Source: https://github.com/tox-dev/platformdirs/blob/main/docs/api.rst

Provides the path to the system-wide executable directory, available to all users.

```APIDOC
## site_bin_dir

### Description
Returns the path to the system-wide executables directory.

### Function Signature
`platformdirs.site_bin_dir()`

### Returns
string: The path to the site-wide bin directory.
```

--------------------------------

### Command-line Interface for Path Inspection

Source: https://context7.com/tox-dev/platformdirs/llms.txt

`platformdirs` provides a command-line interface accessible via `python -m platformdirs` for quick interactive inspection of all directory paths on the current platform.

```APIDOC
## Command-line interface — Inspect paths via `python -m platformdirs`

`platformdirs` ships a `__main__` entry point for quick interactive inspection of all directory paths on the current platform. Running it prints all properties for a sample app with and without version, appauthor, or both.

```bash
# Print all platform directories for the current system
python -m platformdirs

# Example output on Linux:
# -- platformdirs 4.9.6 --
# -- app dirs (with optional 'version')
```
```