diff --git a/.github/workflows/check.yaml b/.github/workflows/check.yaml index 2777659..b66e63b 100644 --- a/.github/workflows/check.yaml +++ b/.github/workflows/check.yaml @@ -7,11 +7,9 @@ on: pull_request: schedule: - cron: "0 8 * * *" - concurrency: group: check-${{ github.ref }} cancel-in-progress: true - jobs: test: name: test ${{ matrix.py }} - ${{ matrix.os }} @@ -31,8 +29,7 @@ jobs: - windows-2025 - macos-15 exclude: - - { os: windows-2025, py: pypy3.11 } - + - {os: windows-2025, py: pypy3.11} steps: - uses: actions/checkout@v6 with: @@ -73,7 +70,6 @@ jobs: name: .coverage.${{ matrix.os }}.${{ matrix.py }} path: ".tox/.coverage.*" retention-days: 3 - coverage: name: Combine coverage runs-on: ubuntu-24.04 @@ -107,7 +103,6 @@ jobs: with: name: html-report path: .tox/htmlcov - check: name: ${{ matrix.tox_env }} - ${{ matrix.os }} runs-on: ${{ matrix.os }} @@ -123,7 +118,7 @@ jobs: - docs - pkg_meta exclude: - - { os: windows-2025, tox_env: pkg_meta } + - {os: windows-2025, tox_env: pkg_meta} steps: - uses: actions/checkout@v6 with: diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index f768b8c..a96d894 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -11,20 +11,13 @@ on: push: branches: ["main"] pull_request: - concurrency: - group: >- - ${{ github.workflow }}-${{ github.ref }}${{ - github.event.inputs.release && github.event.inputs.release != 'no' && '-release' || '' - }} + group: ${{ github.workflow }}-${{ github.ref }}${{ github.event.inputs.release && github.event.inputs.release != 'no' && '-release' || '' }} cancel-in-progress: ${{ github.event.inputs.release == 'no' || github.event.inputs.release == null }} - permissions: contents: read - env: dists-artifact-name: python-package-distributions - jobs: build: name: build @@ -47,10 +40,7 @@ jobs: cache-dependency-glob: "tasks/changelog.py" - name: Generate changelog id: v - run: >- - uv run tasks/changelog.py '${{ github.event.inputs.release == 'no' || github.event.inputs.release == null && - 'patch' || github.event.inputs.release }}' '${{ github.event.number }}' '${{ - github.event.pull_request.base.sha }}' + run: uv run tasks/changelog.py '${{ github.event.inputs.release == 'no' || github.event.inputs.release == null && 'patch' || github.event.inputs.release }}' '${{ github.event.number }}' '${{ github.event.pull_request.base.sha }}' env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Create temporary tag for hatch-vcs @@ -63,7 +53,6 @@ jobs: with: name: ${{ env.dists-artifact-name }} path: dist/* - release: name: release needs: [build] diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 75f597f..7caabd4 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -15,24 +15,33 @@ repos: - id: codespell additional_dependencies: ["tomli>=2.4"] - repo: https://github.com/tox-dev/tox-toml-fmt - rev: "v1.5.4" + rev: "v1.6.0" hooks: - id: tox-toml-fmt - repo: https://github.com/tox-dev/pyproject-fmt - rev: "v2.15.3" + rev: "v2.16.0" hooks: - id: pyproject-fmt - repo: https://github.com/astral-sh/ruff-pre-commit - rev: "v0.15.0" + rev: "v0.15.1" hooks: - id: ruff-format - id: ruff-check args: ["--fix", "--unsafe-fixes", "--exit-non-zero-on-fix"] - - repo: https://github.com/rbubley/mirrors-prettier - rev: "v3.8.1" - hooks: - - id: prettier - args: ["--print-width=120", "--prose-wrap=always"] + - repo: https://github.com/google/yamlfmt + rev: "v0.21.0" + hooks: + - id: yamlfmt + - repo: local + hooks: + - id: mdformat + name: mdformat + entry: mdformat --wrap 120 + language: python + types: [markdown] + additional_dependencies: + - mdformat-gfm + - mdformat-ruff - repo: meta hooks: - id: check-hooks-apply diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2f71a03..ea70b5a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,123 @@ -This project uses [tox](https://tox.wiki) for development. To see all available environments run `tox list`. To run the -test suite under a specific Python version, e.g. Python 3.14: +# Contributing to platformdirs + +Thank you for your interest in contributing to platformdirs! This document provides guidelines and instructions for +contributing to the project. + +## Code of Conduct + +Be respectful and constructive in all interactions. We aim to maintain a welcoming environment for all contributors. + +## Getting Started + +This project uses [tox](https://tox.wiki) for all development tasks. Tox provides isolated environments for testing, +linting, type checking, and documentation building. + +To install tox, run: ```bash -tox r -e py314 +pip install tox ``` + +To see all available tox environments, run: + +```bash +tox list +``` + +## Development Workflow + +### Running Tests + +Run tests for a specific Python version with `tox r -e 3.14`. To run tests across multiple Python versions, use +`tox r -e 3.13,3.14`. Running `tox r` will execute all test environments. + +### Code Quality Checks + +Use `tox r -e fix` to auto-fix formatting and linting issues using ruff. Run `tox r -e type` to check types with +pyright. + +### Coverage + +The `coverage` environment combines results from previous test runs and generates reports. Run tests first with specific +Python versions, then add `coverage` to the command, for example `tox r -e 3.14,3.13,3.12,coverage`. This generates HTML +coverage reports in `.tox/htmlcov/` and checks coverage diff against `origin/main`. + +### Documentation + +Build and check documentation with `tox r -e docs`. The built documentation will be available in +`.tox/docs_out/html/index.html`. + +### Package Metadata + +Validate package metadata and build artifacts with `tox r -e pkg_meta`. This checks that the package description renders +correctly on PyPI and validates wheel contents. + +### Development Environment + +Set up a development environment with all dependencies with `tox r -e dev`. This creates an editable install with all +development dependencies in `.tox/dev/`. + +### Running Everything + +Before submitting a pull request, run `tox r` to execute all checks. This runs tests across all supported Python +versions and performs all quality checks. + +## Making Changes + +### Fork and Branch + +Start by forking the repository on GitHub, then clone your fork locally. Create a branch from `main` with a descriptive +name such as `fix/issue-123` for bug fixes, `feat/new-directory-type` for features, or `docs/improve-readme` for +documentation changes. + +### Code Style + +Follow existing code patterns in the codebase. All code must pass `tox r -e fix` for ruff formatting and linting. Add +type annotations to all new code, which are checked by `tox r -e type`. Keep functions focused and well-named, and +prefer explicit over implicit code. + +### Testing + +Add tests for all new features and bug fixes. Tests must pass on all supported Python versions. To check coverage across +multiple Python versions, run `tox r -e 3.14,3.13,3.12,coverage` to execute tests and then combine coverage results. We +target 100% code coverage. + +### Documentation + +When making user-facing changes, update relevant `.rst` files in `docs/`. Add docstrings to new public functions. Update +examples if behavior changes. Run `tox r -e docs` to verify documentation builds. + +## Submitting Changes + +### Commit Messages + +Follow Commitizen conventions with the format `: ` and an optional body explaining the motivation and +approach. Common types are `feat`, `fix`, `docs`, `refactor`, and `test`. For example: + +``` +fix: handle missing XDG_RUNTIME_DIR on FreeBSD + +Falls back to /var/run/user/ when /run/user/ does not exist, +addressing issues on FreeBSD systems that don't create the runtime directory. +``` + +### Pull Requests + +Ensure `tox r` passes on your branch before pushing. Push to your fork and open a pull request against `main`. Fill in +the PR template with a clear description of changes, related issue numbers, and testing performed. Wait for CI checks to +complete and address any review feedback. + +## Platform-Specific Development + +When adding platform-specific functionality, test on the target platform. Document behavior in `docs/platforms.rst` and +follow existing patterns for the platform by checking `src/platformdirs/.py`. Consider environment variable +overrides if applicable. + +## Getting Help + +Check existing [issues](https://github.com/tox-dev/platformdirs/issues) and review the +[documentation](https://platformdirs.readthedocs.io) before asking. Open a new issue for bugs or feature requests. + +## License + +By contributing, you agree that your contributions will be licensed under the project's MIT License. diff --git a/README.md b/README.md index 04779d6..4642eac 100644 --- a/README.md +++ b/README.md @@ -14,13 +14,27 @@ differences between macOS, Windows, Linux/Unix, and Android so you don't have to from platformdirs import PlatformDirs dirs = PlatformDirs("MyApp", "MyCompany") -dirs.user_data_dir # e.g. ~/.local/share/MyApp on Linux -dirs.user_config_dir # e.g. ~/.config/MyApp on Linux -dirs.user_cache_dir # e.g. ~/.cache/MyApp on Linux -dirs.user_log_dir # e.g. ~/.local/state/MyApp/log on Linux +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//MyApp (Linux) ``` -Convenience functions are also available: +For Path objects instead of strings: + +```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') +``` + +Convenience functions for quick access: ```python from platformdirs import user_data_dir, user_config_path @@ -29,25 +43,28 @@ user_data_dir("MyApp", "MyCompany") # returns str user_config_path("MyApp", "MyCompany") # returns pathlib.Path ``` -## Documentation +## Directory types -Full documentation is available at [platformdirs.readthedocs.io](https://platformdirs.readthedocs.io), including: +- **Data**: Persistent application data (`user_data_dir`, `site_data_dir`) +- **Config**: Configuration files and settings (`user_config_dir`, `site_config_dir`) +- **Cache**: Cached data that can be regenerated (`user_cache_dir`, `site_cache_dir`) +- **State**: Non-essential runtime state like window positions (`user_state_dir`, `site_state_dir`) +- **Logs**: Log files (`user_log_dir`, `site_log_dir`) +- **Runtime**: Runtime files like sockets and PIDs (`user_runtime_dir`, `site_runtime_dir`) -- [Usage guide](https://platformdirs.readthedocs.io/en/latest/usage.html) -- parameters, examples, and patterns -- [API reference](https://platformdirs.readthedocs.io/en/latest/api.html) -- all functions and classes -- [Platform details](https://platformdirs.readthedocs.io/en/latest/platforms.html) -- per-platform paths and behavior +Each type has both `user_*` (per-user, writable) and `site_*` (system-wide, read-only for users) variants. -## Why this fork? - -This repository is a friendly fork of the wonderful work started by -[ActiveState](https://github.com/ActiveState/appdirs) who created `appdirs`, this package's ancestor. +## Documentation -Maintaining an open source project is no easy task, particularly from within an organization, and the Python community -is indebted to `appdirs` (and to Trent Mick and Jeff Rouse in particular) for creating an incredibly useful simple -module, as evidenced by the wide number of users it has attracted over the years. +Full documentation is available at [platformdirs.readthedocs.io](https://platformdirs.readthedocs.io): -Nonetheless, given the number of long-standing open issues and pull requests, and no clear path towards -[ensuring that maintenance of the package would continue or grow](https://github.com/ActiveState/appdirs/issues/79), -this fork was created. +- **[Getting started tutorial](https://platformdirs.readthedocs.io/en/latest/usage.html)** -- learn core concepts + through real-world examples +- **[How-to guides](https://platformdirs.readthedocs.io/en/latest/howto.html)** -- recipes for common tasks and + platform-specific tips +- **[API reference](https://platformdirs.readthedocs.io/en/latest/api.html)** -- complete list of functions and classes +- **[Platform details](https://platformdirs.readthedocs.io/en/latest/platforms.html)** -- default paths for each + operating system -Contributions are most welcome. +Contributions are welcome! See [CONTRIBUTING.md](https://github.com/tox-dev/platformdirs/blob/main/CONTRIBUTING.md) for +details. diff --git a/docs/api.rst b/docs/api.rst index 2d84dd0..8fc8b38 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -9,93 +9,134 @@ These are user-specific (and, generally, user-writeable) directories. User data directory ------------------- +See also: :ref:`platforms:``user_data_dir``` + .. autofunction:: platformdirs.user_data_dir .. autofunction:: platformdirs.user_data_path User config directory --------------------- +See also: :ref:`platforms:``user_config_dir``` + + .. autofunction:: platformdirs.user_config_dir .. autofunction:: platformdirs.user_config_path -Cache directory -------------------- +User cache directory +-------------------- + +See also: :ref:`platforms:``user_cache_dir``` + .. autofunction:: platformdirs.user_cache_dir .. autofunction:: platformdirs.user_cache_path -State directory -------------------- +User state directory +-------------------- + +See also: :ref:`platforms:``user_state_dir``` + .. autofunction:: platformdirs.user_state_dir .. autofunction:: platformdirs.user_state_path -Logs directory -------------------- +User log directory +------------------ + +See also: :ref:`platforms:``user_log_dir``` + .. autofunction:: platformdirs.user_log_dir .. autofunction:: platformdirs.user_log_path +User runtime directory +---------------------- + +See also: :ref:`platforms:``user_runtime_dir``` + + +.. autofunction:: platformdirs.user_runtime_dir +.. autofunction:: platformdirs.user_runtime_path + +User applications directory +---------------------------- + +See also: :ref:`platforms:``user_applications_dir``` + + +Where application launchers and shortcuts are registered — ``.desktop`` files on Linux, +the per-user ``Applications`` folder on macOS, or Start Menu shortcuts on Windows. +These entries make applications discoverable in menus and app launchers. + +.. autofunction:: platformdirs.user_applications_dir +.. autofunction:: platformdirs.user_applications_path + +User binary directory +---------------------- + +See also: :ref:`platforms:``user_bin_dir``` + + +Where user-installed executables and scripts are placed so they appear on ``$PATH`` — +``~/.local/bin`` on Linux/macOS or ``%LOCALAPPDATA%\Programs`` on Windows. + +.. autofunction:: platformdirs.user_bin_dir +.. autofunction:: platformdirs.user_bin_path + User documents directory ------------------------ +See also: :ref:`platforms:``user_documents_dir``` + + .. autofunction:: platformdirs.user_documents_dir .. autofunction:: platformdirs.user_documents_path User downloads directory ------------------------ +See also: :ref:`platforms:``user_downloads_dir``` + + .. autofunction:: platformdirs.user_downloads_dir .. autofunction:: platformdirs.user_downloads_path User pictures directory ------------------------ +See also: :ref:`platforms:``user_pictures_dir``` + + .. autofunction:: platformdirs.user_pictures_dir .. autofunction:: platformdirs.user_pictures_path User videos directory ------------------------ +See also: :ref:`platforms:``user_videos_dir``` + + .. autofunction:: platformdirs.user_videos_dir .. autofunction:: platformdirs.user_videos_path User music directory ------------------------ +See also: :ref:`platforms:``user_music_dir``` + + .. autofunction:: platformdirs.user_music_dir .. autofunction:: platformdirs.user_music_path User desktop directory ------------------------ -.. autofunction:: platformdirs.user_desktop_dir -.. autofunction:: platformdirs.user_desktop_path - -User applications directory ----------------------------- - -Where application launchers and shortcuts are registered — ``.desktop`` files on Linux, -the per-user ``Applications`` folder on macOS, or Start Menu shortcuts on Windows. -These entries make applications discoverable in menus and app launchers. - -.. autofunction:: platformdirs.user_applications_dir -.. autofunction:: platformdirs.user_applications_path - -User binary directory ----------------------- +See also: :ref:`platforms:``user_desktop_dir``` -Where user-installed executables and scripts are placed so they appear on ``$PATH`` — -``~/.local/bin`` on Linux/macOS or ``%LOCALAPPDATA%\Programs`` on Windows. -.. autofunction:: platformdirs.user_bin_dir -.. autofunction:: platformdirs.user_bin_path - -Runtime directory -------------------- - -.. autofunction:: platformdirs.user_runtime_dir -.. autofunction:: platformdirs.user_runtime_path +.. autofunction:: platformdirs.user_desktop_dir +.. autofunction:: platformdirs.user_desktop_path Shared directories ~~~~~~~~~~~~~~~~~~ @@ -105,39 +146,82 @@ These are system-wide (and, generally, read-only) directories. Shared data directory --------------------- +See also: :ref:`platforms:``site_data_dir``` + + .. autofunction:: platformdirs.site_data_dir .. autofunction:: platformdirs.site_data_path Shared config directory ----------------------- +See also: :ref:`platforms:``site_config_dir``` + + .. autofunction:: platformdirs.site_config_dir .. autofunction:: platformdirs.site_config_path Shared cache directory ---------------------- +See also: :ref:`platforms:``site_cache_dir``` + + .. autofunction:: platformdirs.site_cache_dir .. autofunction:: platformdirs.site_cache_path Shared state directory ---------------------- +See also: :ref:`platforms:``site_state_dir``` + + .. autofunction:: platformdirs.site_state_dir .. autofunction:: platformdirs.site_state_path Shared log directory -------------------- +See also: :ref:`platforms:``site_log_dir``` + + .. autofunction:: platformdirs.site_log_dir .. autofunction:: platformdirs.site_log_path Shared runtime directory ------------------------ +See also: :ref:`platforms:``site_runtime_dir``` + + .. autofunction:: platformdirs.site_runtime_dir .. autofunction:: platformdirs.site_runtime_path +Shared applications directory +------------------------------ + +See also: :ref:`platforms:``site_applications_dir``` + + +Where application launchers and shortcuts are registered system-wide — ``.desktop`` files in +``/usr/share/applications`` on Linux, ``/Applications`` on macOS, or the All Users Start Menu +on Windows. Applications installed here are available to all users. + +.. autofunction:: platformdirs.site_applications_dir +.. autofunction:: platformdirs.site_applications_path + +Shared binary directory +------------------------ + +See also: :ref:`platforms:``site_bin_dir``` + + +Where system-wide executables and scripts are placed — ``/usr/local/bin`` on Linux/macOS +or ``%ProgramData%\bin`` on Windows. Executables here are available to all users. + +.. autofunction:: platformdirs.site_bin_dir +.. autofunction:: platformdirs.site_bin_path + Platforms ~~~~~~~~~ diff --git a/docs/howto.rst b/docs/howto.rst index c377c7b..2011e83 100644 --- a/docs/howto.rst +++ b/docs/howto.rst @@ -162,12 +162,8 @@ Use ``roaming=True`` for settings that should sync across domain-joined machines Environment variable overrides ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Windows supports environment variable overrides for certain directories: - -- ``WIN_PD_OVERRIDE_*`` - Override specific directory types -- ``PLATFORMDIRS_*`` - Alternative override mechanism - -See the source code for complete list of supported variables. +Windows supports environment variable overrides for certain directories using +``WIN_PD_OVERRIDE_*`` variables. See the :ref:`platforms:Windows` section for the complete list. macOS ~~~~~ @@ -234,15 +230,9 @@ XDG Base Directory Specification ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``platformdirs`` fully supports the XDG Base Directory Specification. Users can override -default paths by setting environment variables: - -- ``XDG_DATA_HOME`` - defaults to ``~/.local/share`` -- ``XDG_CONFIG_HOME`` - defaults to ``~/.config`` -- ``XDG_CACHE_HOME`` - defaults to ``~/.cache`` -- ``XDG_STATE_HOME`` - defaults to ``~/.local/state`` -- ``XDG_RUNTIME_DIR`` - defaults to ``/run/user/$UID`` -- ``XDG_DATA_DIRS`` - defaults to ``/usr/local/share:/usr/share`` -- ``XDG_CONFIG_DIRS`` - defaults to ``/etc/xdg`` +default paths by setting environment variables like ``XDG_DATA_HOME``, ``XDG_CONFIG_HOME``, +``XDG_CACHE_HOME``, and ``XDG_STATE_HOME``. See :ref:`xdg-env-vars` for the complete list +of supported variables and their defaults. Running as root ^^^^^^^^^^^^^^^ diff --git a/docs/parameters.rst b/docs/parameters.rst index c7452cd..ffb9b09 100644 --- a/docs/parameters.rst +++ b/docs/parameters.rst @@ -165,6 +165,8 @@ system-wide directories rather than root's home directory. **Platform**: Unix only +.. _xdg-env-vars: + XDG environment variables -------------------------- @@ -193,6 +195,9 @@ Supported XDG variables: - ``XDG_CONFIG_DIRS`` - system config directories (colon-separated). - ``XDG_RUNTIME_DIR`` - user runtime directory. +**Windows environment variable overrides**: On Windows, ``WIN_PD_OVERRIDE_*`` environment +variables can override default paths. See the :ref:`platforms:Windows` section for details. + Directories not covered ------------------------ diff --git a/docs/platforms.rst b/docs/platforms.rst index 2119216..a0e2a56 100644 --- a/docs/platforms.rst +++ b/docs/platforms.rst @@ -5,12 +5,18 @@ Platform details This page describes the default paths for each platform and any platform-specific behavior. All examples below assume ``appname="SuperApp"`` and ``appauthor="Acme"`` unless stated otherwise. - Default paths ------------- +User directories +~~~~~~~~~~~~~~~~ + +These are user-specific (and, generally, user-writeable) directories. + ``user_data_dir`` -~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User data directory` .. list-table:: :widths: 20 80 @@ -25,7 +31,9 @@ Default paths - ``/data/data//files/SuperApp`` ``user_config_dir`` -~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User config directory` .. list-table:: :widths: 20 80 @@ -40,7 +48,9 @@ Default paths - ``/data/data//shared_prefs/SuperApp`` ``user_cache_dir`` -~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User cache directory` .. list-table:: :widths: 20 80 @@ -55,7 +65,9 @@ Default paths - ``/data/data//cache/SuperApp`` ``user_state_dir`` -~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User state directory` .. list-table:: :widths: 20 80 @@ -70,7 +82,9 @@ Default paths - ``/data/data//files/SuperApp`` ``user_log_dir`` -~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User log directory` .. list-table:: :widths: 20 80 @@ -84,38 +98,10 @@ Default paths * - Android - ``/data/data//cache/SuperApp/log`` -``site_state_dir`` -~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :widths: 20 80 - - * - Linux - - ``/var/lib/SuperApp`` - * - macOS - - ``/Library/Application Support/SuperApp`` - * - Windows - - ``C:\ProgramData\Acme\SuperApp`` - * - Android - - ``/data/data//files/SuperApp`` - -``site_log_dir`` -~~~~~~~~~~~~~~~~ - -.. list-table:: - :widths: 20 80 - - * - Linux - - ``/var/log/SuperApp`` - * - macOS - - ``/Library/Logs/SuperApp`` - * - Windows - - ``C:\ProgramData\Acme\SuperApp\Logs`` - * - Android - - ``/data/data//cache/SuperApp/log`` - ``user_runtime_dir`` -~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User runtime directory` .. list-table:: :widths: 20 80 @@ -129,68 +115,55 @@ Default paths * - Android - ``/data/data//cache/SuperApp/tmp`` -``site_data_dir`` -~~~~~~~~~~~~~~~~~ +``user_applications_dir`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User applications directory` .. list-table:: :widths: 20 80 * - Linux - - ``/usr/local/share/SuperApp`` + - ``~/.local/share/applications`` * - macOS - - ``/Library/Application Support/SuperApp`` + - ``~/Applications`` * - Windows - - ``C:\ProgramData\Acme\SuperApp`` + - ``C:\Users\\AppData\Roaming\Microsoft\Windows\Start Menu\Programs`` * - Android - - ``/data/data//files/SuperApp`` + - same as ``user_data_dir`` -``site_config_dir`` -~~~~~~~~~~~~~~~~~~~ +.. note:: -.. list-table:: - :widths: 20 80 + This property does not append ``appname`` or ``version``. It returns the shared + applications directory where ``.desktop`` files (Linux), app bundles (macOS), or + Start Menu shortcuts (Windows) are placed. - * - Linux - - ``/etc/xdg/SuperApp`` - * - macOS - - ``/Library/Application Support/SuperApp`` - * - Windows - - ``C:\ProgramData\Acme\SuperApp`` - * - Android - - ``/data/data//shared_prefs/SuperApp`` +``user_bin_dir`` +^^^^^^^^^^^^^^^^ -``site_cache_dir`` -~~~~~~~~~~~~~~~~~~ +See also: :ref:`api:User binary directory` .. list-table:: :widths: 20 80 * - Linux - - ``/var/cache/SuperApp`` + - ``~/.local/bin`` * - macOS - - ``/Library/Caches/SuperApp`` + - ``~/.local/bin`` * - Windows - - ``C:\ProgramData\Acme\SuperApp\Cache`` + - ``C:\Users\\AppData\Local\Programs`` * - Android - - ``/data/data//cache/SuperApp`` - -``site_runtime_dir`` -~~~~~~~~~~~~~~~~~~~~ + - ``/data/data//files/bin`` -.. list-table:: - :widths: 20 80 +.. note:: - * - Linux - - ``/run/SuperApp`` - * - macOS - - ``~/Library/Caches/TemporaryItems/SuperApp`` - * - Windows - - ``C:\Users\\AppData\Local\Temp\Acme\SuperApp`` - * - Android - - ``/data/data//cache/SuperApp/tmp`` + This property does not append ``appname`` or ``version``. It returns the directory + where user-installed executables and scripts are placed. ``user_documents_dir`` -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User documents directory` .. list-table:: :widths: 20 80 @@ -205,7 +178,9 @@ Default paths - ``/storage/emulated/0/Documents`` ``user_downloads_dir`` -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User downloads directory` .. list-table:: :widths: 20 80 @@ -220,7 +195,9 @@ Default paths - ``/storage/emulated/0/Downloads`` ``user_pictures_dir`` -~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User pictures directory` .. list-table:: :widths: 20 80 @@ -235,7 +212,9 @@ Default paths - ``/storage/emulated/0/Pictures`` ``user_videos_dir`` -~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User videos directory` .. list-table:: :widths: 20 80 @@ -250,7 +229,9 @@ Default paths - ``/storage/emulated/0/DCIM/Camera`` ``user_music_dir`` -~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User music directory` .. list-table:: :widths: 20 80 @@ -265,7 +246,9 @@ Default paths - ``/storage/emulated/0/Music`` ``user_desktop_dir`` -~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:User desktop directory` .. list-table:: :widths: 20 80 @@ -279,70 +262,140 @@ Default paths * - Android - ``/storage/emulated/0/Desktop`` -``user_applications_dir`` -~~~~~~~~~~~~~~~~~~~~~~~~~ +Shared directories +~~~~~~~~~~~~~~~~~~ + +These are system-wide (and, generally, read-only) directories. + +``site_data_dir`` +^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:Shared data directory` .. list-table:: :widths: 20 80 * - Linux - - ``~/.local/share/applications`` + - ``/usr/local/share/SuperApp`` * - macOS - - ``~/Applications`` + - ``/Library/Application Support/SuperApp`` * - Windows - - ``C:\Users\\AppData\Roaming\Microsoft\Windows\Start Menu\Programs`` + - ``C:\ProgramData\Acme\SuperApp`` * - Android - - same as ``user_data_dir`` + - ``/data/data//files/SuperApp`` -.. note:: +``site_config_dir`` +^^^^^^^^^^^^^^^^^^^ - This property does not append ``appname`` or ``version``. It returns the shared - applications directory where ``.desktop`` files (Linux), app bundles (macOS), or - Start Menu shortcuts (Windows) are placed. +See also: :ref:`api:Shared config directory` -``site_applications_dir`` -~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :widths: 20 80 + + * - Linux + - ``/etc/xdg/SuperApp`` + * - macOS + - ``/Library/Application Support/SuperApp`` + * - Windows + - ``C:\ProgramData\Acme\SuperApp`` + * - Android + - ``/data/data//shared_prefs/SuperApp`` + +``site_cache_dir`` +^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:Shared cache directory` .. list-table:: :widths: 20 80 * - Linux - - ``/usr/share/applications`` + - ``/var/cache/SuperApp`` * - macOS - - ``/Applications`` + - ``/Library/Caches/SuperApp`` * - Windows - - ``C:\ProgramData\Microsoft\Windows\Start Menu\Programs`` + - ``C:\ProgramData\Acme\SuperApp\Cache`` * - Android - - same as ``user_applications_dir`` + - ``/data/data//cache/SuperApp`` -.. note:: +``site_state_dir`` +^^^^^^^^^^^^^^^^^^ - This property does not append ``appname`` or ``version``. It returns the system-wide - applications directory where ``.desktop`` files (Linux), app bundles (macOS), or - Start Menu shortcuts (Windows) are installed for all users. +See also: :ref:`api:Shared state directory` -``user_bin_dir`` -~~~~~~~~~~~~~~~~ +.. list-table:: + :widths: 20 80 + + * - Linux + - ``/var/lib/SuperApp`` + * - macOS + - ``/Library/Application Support/SuperApp`` + * - Windows + - ``C:\ProgramData\Acme\SuperApp`` + * - Android + - ``/data/data//files/SuperApp`` + +``site_log_dir`` +^^^^^^^^^^^^^^^^ + +See also: :ref:`api:Shared log directory` .. list-table:: :widths: 20 80 * - Linux - - ``~/.local/bin`` + - ``/var/log/SuperApp`` * - macOS - - ``~/.local/bin`` + - ``/Library/Logs/SuperApp`` * - Windows - - ``C:\Users\\AppData\Local\Programs`` + - ``C:\ProgramData\Acme\SuperApp\Logs`` * - Android - - ``/data/data//files/bin`` + - ``/data/data//cache/SuperApp/log`` + +``site_runtime_dir`` +^^^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:Shared runtime directory` + +.. list-table:: + :widths: 20 80 + + * - Linux + - ``/run/SuperApp`` + * - macOS + - ``~/Library/Caches/TemporaryItems/SuperApp`` + * - Windows + - ``C:\Users\\AppData\Local\Temp\Acme\SuperApp`` + * - Android + - ``/data/data//cache/SuperApp/tmp`` + +``site_applications_dir`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +See also: :ref:`api:Shared applications directory` + +.. list-table:: + :widths: 20 80 + + * - Linux + - ``/usr/share/applications`` + * - macOS + - ``/Applications`` + * - Windows + - ``C:\ProgramData\Microsoft\Windows\Start Menu\Programs`` + * - Android + - same as ``user_applications_dir`` .. note:: - This property does not append ``appname`` or ``version``. It returns the directory - where user-installed executables and scripts are placed. + This property does not append ``appname`` or ``version``. It returns the system-wide + applications directory where ``.desktop`` files (Linux), app bundles (macOS), or + Start Menu shortcuts (Windows) are installed for all users. ``site_bin_dir`` -~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^ + +See also: :ref:`api:Shared binary directory` .. list-table:: :widths: 20 80 @@ -399,9 +452,6 @@ Key behaviors: which syncs across machines in a Windows domain - **OPINION**: ``user_cache_dir`` appends ``\Cache``, ``user_log_dir`` appends ``\Logs`` -Environment variable overrides -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Unlike Linux/macOS where ``XDG_*`` variables are a platform standard, Windows has no built-in convention for overriding folder locations at the application level. To fill this gap, ``platformdirs`` checks ``WIN_PD_OVERRIDE_*`` environment variables before querying the Shell