From 5b48a5a7df10a52c8ad2717ffa2c79e484d1f641 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Sat, 14 Feb 2026 11:22:46 -0800 Subject: [PATCH 01/11] =?UTF-8?q?=F0=9F=93=9D=20docs:=20enhance=20README,?= =?UTF-8?q?=20fix=20issues,=20and=20reorganize=20platforms.rst?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enhanced README.md to provide MVP documentation for PyPI users without requiring a visit to the full docs. Added comprehensive Quick start showing all directory types (data, config, cache, state, log, runtime, documents, downloads) with Path examples. New Directory types section explains purpose and user vs site variants. Updated Documentation links to reflect the reorganized structure from #441 (tutorial, how-to, reference pages). Simplified fork attribution to single line since appdirs has been deprecated since 2023. Fixed api.rst documentation: - Added missing user_applications_dir and user_bin_dir documentation - Unified headlines to use "User X directory" format consistently - Added bi-directional cross-references between api.rst and platforms.rst Reorganized platforms.rst to match api.rst structure: - Grouped all user directories together under "User directories" section - Grouped all site directories together under "Shared directories" section - Reordered to match api.rst sequence (runtime/applications/bin before documents/downloads for better alignment) - Added bi-directional cross-references to api.rst sections Fixed howto.rst: - Removed non-existent PLATFORMDIRS_* env variable reference - Updated cross-reference to Windows environment overrides Fixed parameters.rst: - Resolved XDG documentation redundancy by linking to howto.rst - Added cross-reference to Windows environment overrides - Added explicit label for XDG environment variables section All documentation cross-references now work correctly and docs build passes without warnings. Addresses #444 --- README.md | 56 +++++---- docs/api.rst | 146 ++++++++++++++++++----- docs/howto.rst | 20 +--- docs/parameters.rst | 5 + docs/platforms.rst | 274 ++++++++++++++++++++++++++------------------ 5 files changed, 322 insertions(+), 179 deletions(-) diff --git a/README.md b/README.md index 04779d6..a1c4893 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,25 @@ 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! This project is a maintained fork of the original +[appdirs](https://github.com/ActiveState/appdirs) library. 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 From e505ba1c86cbdf5c7094ee530d8cfcd78fc0acf8 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 14 Feb 2026 20:41:58 +0000 Subject: [PATCH 02/11] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a1c4893..b3b631d 100644 --- a/README.md +++ b/README.md @@ -58,10 +58,13 @@ Each type has both `user_*` (per-user, writable) and `site_*` (system-wide, read Full documentation is available at [platformdirs.readthedocs.io](https://platformdirs.readthedocs.io): -- **[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 +- **[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 +- **[Platform details](https://platformdirs.readthedocs.io/en/latest/platforms.html)** -- default paths for each + operating system Contributions are welcome! This project is a maintained fork of the original [appdirs](https://github.com/ActiveState/appdirs) library. From faaae85fc66dd76c0951756aaa61f61a4dee4906 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Sat, 14 Feb 2026 12:49:22 -0800 Subject: [PATCH 03/11] =?UTF-8?q?=F0=9F=93=9D=20docs:=20simplify=20README?= =?UTF-8?q?=20footer?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The appdirs fork history is no longer relevant since the original project was deprecated in 2023. Removed the fork attribution text and replaced it with a direct link to CONTRIBUTING.md to make it easier for new contributors to find guidelines. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b3b631d..5f00d1c 100644 --- a/README.md +++ b/README.md @@ -66,5 +66,5 @@ Full documentation is available at [platformdirs.readthedocs.io](https://platfor - **[Platform details](https://platformdirs.readthedocs.io/en/latest/platforms.html)** -- default paths for each operating system -Contributions are welcome! This project is a maintained fork of the original -[appdirs](https://github.com/ActiveState/appdirs) library. +Contributions are welcome! See +[CONTRIBUTING.md](https://github.com/tox-dev/platformdirs/blob/main/CONTRIBUTING.md) for details. From 918fed306ac7e448e074354a0fde5a547e26f7c7 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 14 Feb 2026 20:50:10 +0000 Subject: [PATCH 04/11] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5f00d1c..de44093 100644 --- a/README.md +++ b/README.md @@ -66,5 +66,5 @@ Full documentation is available at [platformdirs.readthedocs.io](https://platfor - **[Platform details](https://platformdirs.readthedocs.io/en/latest/platforms.html)** -- default paths for each operating system -Contributions are welcome! See -[CONTRIBUTING.md](https://github.com/tox-dev/platformdirs/blob/main/CONTRIBUTING.md) for details. +Contributions are welcome! See [CONTRIBUTING.md](https://github.com/tox-dev/platformdirs/blob/main/CONTRIBUTING.md) for +details. From 9acbecca5151483c9aebb64d91f75ac3591a5e34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Sat, 14 Feb 2026 12:50:20 -0800 Subject: [PATCH 05/11] =?UTF-8?q?=F0=9F=94=A7=20build:=20replace=20prettie?= =?UTF-8?q?r=20with=20yamlfmt=20and=20mdformat?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prettier is a JavaScript tool that requires Node.js dependencies. Switching to yamlfmt for YAML files and mdformat for Markdown provides better integration with Python tooling and reduces cross-language dependencies. mdformat with gfm and black plugins provides equivalent formatting for Markdown files with 120 character wrapping, while yamlfmt handles YAML formatting natively without additional configuration. --- .pre-commit-config.yaml | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 75f597f..2866d55 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -28,11 +28,20 @@ repos: - 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 From 53fdfc94064cd5180399b5597352b5dceb0965fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Sat, 14 Feb 2026 12:51:36 -0800 Subject: [PATCH 06/11] =?UTF-8?q?=F0=9F=93=9D=20docs:=20expand=20CONTRIBUT?= =?UTF-8?q?ING.md=20with=20comprehensive=20tox-focused=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous CONTRIBUTING.md was minimal. Expanded it to provide clear guidance for new contributors with tox-based workflows for testing, linting, type checking, and documentation building. Structured around tox commands since all development tasks use tox environments, making it easier for contributors to get started and follow the project's development practices. Signed-off-by: Bernát Gábor --- .github/workflows/check.yaml | 9 +- .github/workflows/release.yaml | 12 +- .pre-commit-config.yaml | 6 +- CONTRIBUTING.md | 209 ++++++++++++++++++++++++++++++++- README.md | 20 ++-- 5 files changed, 225 insertions(+), 31 deletions(-) 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..754a212 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -11,20 +11,19 @@ on: push: branches: ["main"] pull_request: - concurrency: 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 @@ -48,9 +47,7 @@ jobs: - 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 }}' + 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 +60,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 2866d55..7caabd4 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -15,15 +15,15 @@ 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2f71a03..171ccbe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,209 @@ -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/en/4.35.0) for all development tasks. Tox provides isolated environments for +testing, linting, type checking, and documentation building. + +### Install tox + +```bash +pip install tox +``` + +### Available Environments + +List all available tox environments: + +```bash +tox list +``` + +## Development Workflow + +### Running Tests + +Run tests for a specific Python version: + +```bash +tox r -e 3.14 +``` + +Run tests for multiple Python versions: + +```bash +tox r -e 3.13,3.14 +``` + +Run all test environments: + +```bash +tox r +``` + +### Code Quality Checks + +Auto-fix formatting and linting issues: + +```bash +tox r -e fix +``` + +Run type checking: + +```bash +tox r -e type +``` + +### Coverage + +Combine coverage from all test runs and generate reports: + +```bash +tox r -e coverage +``` + +This generates HTML coverage reports in `.tox/htmlcov/` and checks coverage diff against `origin/main`. + +### Documentation + +Build and check documentation: + +```bash +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: ```bash -tox r -e py314 +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: + +```bash +tox r -e dev +``` + +This creates an editable install with all development dependencies in `.tox/dev/`. + +### Running Everything + +Before submitting a PR, run all checks: + +```bash +tox r +``` + +This runs tests across all supported Python versions and performs all quality checks. + +## Making Changes + +### Fork and Branch + +1. Fork the repository on GitHub +1. Clone your fork locally +1. Create a branch from `main`: + +```bash +git checkout -b fix/issue-123 +``` + +Use descriptive branch names: + +- `fix/issue-123` for bug fixes +- `feat/new-directory-type` for features +- `docs/improve-readme` for documentation + +### Code Style + +- Follow existing code patterns in the codebase +- All code must pass `tox r -e fix` (ruff formatting and linting) +- Add type annotations to all new code (checked by `tox r -e type`) +- Keep functions focused and well-named +- Prefer explicit over implicit + +### Testing + +- Add tests for all new features and bug fixes +- Tests must pass on all supported Python versions +- Run `tox r -e coverage` to check test coverage +- 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: + +``` +: + + +``` + +Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `build` + +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 + +1. Ensure `tox r` passes on your branch +1. Push to your fork +1. Open a pull request against `main` +1. Fill in the PR template with: + - Clear description of changes + - Related issue numbers + - Testing performed +1. Wait for CI checks to complete +1. Address any review feedback + +## Platform-Specific Development + +When adding platform-specific functionality: + +- Test on the target platform +- Document behavior in `docs/platforms.rst` +- Follow existing patterns for the platform (check `src/platformdirs/.py`) +- Consider environment variable overrides if applicable + +## Getting Help + +- Check existing [issues](https://github.com/tox-dev/platformdirs/issues) +- Review [documentation](https://platformdirs.readthedocs.io) +- 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 de44093..4642eac 100644 --- a/README.md +++ b/README.md @@ -14,14 +14,14 @@ 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 # ~/.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) +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) ``` For Path objects instead of strings: @@ -30,8 +30,8 @@ For Path objects instead of strings: 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') +dirs.user_data_path # pathlib.Path('~/.local/share/MyApp') +dirs.user_config_path # pathlib.Path('~/.config/MyApp') ``` Convenience functions for quick access: From 8b0f02d8d19c95c826e99feedff9289bd1c8c2f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Sat, 14 Feb 2026 12:54:37 -0800 Subject: [PATCH 07/11] =?UTF-8?q?=F0=9F=94=A7=20build:=20format=20YAML=20f?= =?UTF-8?q?iles=20with=20yamlfmt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/release.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 754a212..025f323 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -17,6 +17,7 @@ concurrency: + github.event.inputs.release && github.event.inputs.release != 'no' && '-release' || '' }} cancel-in-progress: ${{ github.event.inputs.release == 'no' || github.event.inputs.release == null }} From 68b5ba2633a41bcd56f991beb80db14cdcd3df2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Sat, 14 Feb 2026 12:55:17 -0800 Subject: [PATCH 08/11] =?UTF-8?q?=F0=9F=94=A7=20build:=20update=20pre-comm?= =?UTF-8?q?it=20hooks=20to=20latest=20versions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated tox-toml-fmt to v1.6.0, pyproject-fmt to v2.16.0, and ruff-pre-commit to v0.15.1. Added yamlfmt for YAML formatting and mdformat with plugins for Markdown formatting to replace prettier. Excluded release.yaml from yamlfmt due to pre-existing formatting issues with multiline template expressions. --- .pre-commit-config.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7caabd4..411624f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -32,6 +32,7 @@ repos: rev: "v0.21.0" hooks: - id: yamlfmt + exclude: ".github/workflows/release.yaml" - repo: local hooks: - id: mdformat From 9b91b2e1f534546b922dd532aa0d5fb9330d641b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Sat, 14 Feb 2026 12:57:37 -0800 Subject: [PATCH 09/11] =?UTF-8?q?=F0=9F=94=A7=20build:=20clean=20up=20work?= =?UTF-8?q?flow=20YAML=20formatting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixed GitHub Actions workflow files to use clean, readable formatting instead of folded scalar syntax with blank lines. Removed unnecessary line breaks from concurrency group and changelog command definitions. The >- (folded scalar) syntax with blank lines was confusing and hard to format. yamlfmt properly collapses these to single lines while preserving the actual string values that GitHub Actions receives. --- .github/workflows/release.yaml | 12 ++---------- .pre-commit-config.yaml | 1 - 2 files changed, 2 insertions(+), 11 deletions(-) diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 025f323..a96d894 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -12,14 +12,7 @@ on: 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 @@ -47,8 +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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 411624f..7caabd4 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -32,7 +32,6 @@ repos: rev: "v0.21.0" hooks: - id: yamlfmt - exclude: ".github/workflows/release.yaml" - repo: local hooks: - id: mdformat From 54fb14523316b15322880bbeeea63bd2334289ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Sat, 14 Feb 2026 12:57:41 -0800 Subject: [PATCH 10/11] =?UTF-8?q?=F0=9F=93=9D=20docs:=20rewrite=20CONTRIBU?= =?UTF-8?q?TING.md=20in=20paragraph=20style?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Converted the contributing guide from structured lists and sections to flowing prose with proper English grammar and punctuation. Information is presented in narrative form while maintaining the same tox-focused content and comprehensive guidance for contributors. --- CONTRIBUTING.md | 164 +++++++++++------------------------------------- 1 file changed, 38 insertions(+), 126 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 171ccbe..1a48471 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,18 +9,16 @@ Be respectful and constructive in all interactions. We aim to maintain a welcomi ## Getting Started -This project uses [tox](https://tox.wiki/en/4.35.0) for all development tasks. Tox provides isolated environments for -testing, linting, type checking, and documentation building. +This project uses [tox](https://tox.wiki) for all development tasks. Tox provides isolated environments for testing, +linting, type checking, and documentation building. -### Install tox +To install tox, run: ```bash pip install tox ``` -### Available Environments - -List all available tox environments: +To see all available tox environments, run: ```bash tox list @@ -30,145 +28,69 @@ tox list ### Running Tests -Run tests for a specific Python version: - -```bash -tox r -e 3.14 -``` - -Run tests for multiple Python versions: - -```bash -tox r -e 3.13,3.14 -``` - -Run all test environments: - -```bash -tox r -``` +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 -Auto-fix formatting and linting issues: - -```bash -tox r -e fix -``` - -Run type checking: - -```bash -tox r -e type -``` +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 -Combine coverage from all test runs and generate reports: - -```bash -tox r -e coverage -``` - -This generates HTML coverage reports in `.tox/htmlcov/` and checks coverage diff against `origin/main`. +Combine coverage from all test runs and generate reports with `tox r -e coverage`. This generates HTML coverage reports +in `.tox/htmlcov/` and checks coverage diff against `origin/main`. ### Documentation -Build and check documentation: - -```bash -tox r -e docs -``` - -The built documentation will be available in `.tox/docs_out/html/index.html`. +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: - -```bash -tox r -e pkg_meta -``` - -This checks that the package description renders correctly on PyPI and validates wheel contents. +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: - -```bash -tox r -e dev -``` - -This creates an editable install with all development dependencies in `.tox/dev/`. +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 PR, run all checks: - -```bash -tox r -``` - -This runs tests across all supported Python versions and performs all quality checks. +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 -1. Fork the repository on GitHub -1. Clone your fork locally -1. Create a branch from `main`: - -```bash -git checkout -b fix/issue-123 -``` - -Use descriptive branch names: - -- `fix/issue-123` for bug fixes -- `feat/new-directory-type` for features -- `docs/improve-readme` for documentation +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` (ruff formatting and linting) -- Add type annotations to all new code (checked by `tox r -e type`) -- Keep functions focused and well-named -- Prefer explicit over implicit +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 -- Run `tox r -e coverage` to check test coverage -- We target 100% code coverage +Add tests for all new features and bug fixes. Tests must pass on all supported Python versions. Run `tox r -e coverage` +to check test coverage. 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 +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: - -``` -: - - -``` - -Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `build` - -Example: +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 @@ -179,30 +101,20 @@ addressing issues on FreeBSD systems that don't create the runtime directory. ### Pull Requests -1. Ensure `tox r` passes on your branch -1. Push to your fork -1. Open a pull request against `main` -1. Fill in the PR template with: - - Clear description of changes - - Related issue numbers - - Testing performed -1. Wait for CI checks to complete -1. Address any review feedback +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` -- Follow existing patterns for the platform (check `src/platformdirs/.py`) -- Consider environment variable overrides if applicable +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) -- Review [documentation](https://platformdirs.readthedocs.io) -- Open a new issue for bugs or feature requests +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 From 4cd1918953eea33d30401979d77b6e192e545289 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Sat, 14 Feb 2026 12:57:41 -0800 Subject: [PATCH 11/11] =?UTF-8?q?=F0=9F=93=9D=20docs:=20rewrite=20CONTRIBU?= =?UTF-8?q?TING.md=20in=20paragraph=20style?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Converted the contributing guide from structured lists and sections to flowing prose with proper English grammar and punctuation. Information is presented in narrative form while maintaining the same tox-focused content and comprehensive guidance for contributors. --- CONTRIBUTING.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a48471..ea70b5a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,8 +38,9 @@ pyright. ### Coverage -Combine coverage from all test runs and generate reports with `tox r -e coverage`. This generates HTML coverage reports -in `.tox/htmlcov/` and checks coverage diff against `origin/main`. +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 @@ -77,8 +78,9 @@ prefer explicit over implicit code. ### Testing -Add tests for all new features and bug fixes. Tests must pass on all supported Python versions. Run `tox r -e coverage` -to check test coverage. We target 100% code coverage. +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