Comparing changes

The `use_site_for_root` parameter was added in #426 but wasn't documented in the Usage Guide. 📚 Users had no way to discover this feature when configuring system services running as root that need to use system-wide directories instead of root's home directory. Added a dedicated section in the Usage Guide documenting `use_site_for_root` alongside other parameters like `ensure_exists`, `multipath`, and `roaming`. The documentation explains the Unix-only behavior, the default value for backwards compatibility, and includes a practical example showing how root processes redirect to site directories. Fixes #433

OpenBSD applications using platformdirs were unnecessarily falling back to temporary directories because the default runtime path `/var/run/user/{uid}` is not writable by regular users on OpenBSD. 🔒 This issue was reported by OpenBSD package maintainers who noticed the mismatch with the platform's native XDG implementation. OpenBSD now has native `XDG_RUNTIME_DIR` support in libc via the `setxdgenv()` function in [`lib/libc/gen/login_cap.c`](https://github.com/openbsd/src/blob/master/lib/libc/gen/login_cap.c), which creates directories at `/tmp/run/user/{uid}` with proper ownership and permissions. The fix splits the BSD platform detection to handle OpenBSD separately from FreeBSD and NetBSD, which both continue using `/var/run/user/{uid}`. ✨ This change aligns platformdirs with OpenBSD's official implementation while preserving existing behavior for FreeBSD and NetBSD. Applications on OpenBSD will now correctly use the runtime directory created by the system during login instead of falling back to temporary directories. ## Documentation References During investigation, the following official platform documentation was reviewed: - **OpenBSD**: [`setxdgenv()` in login_cap.c](https://github.com/openbsd/src/blob/master/lib/libc/gen/login_cap.c) - uses `/tmp/run/user/{uid}` - **FreeBSD**: [`pam_xdg` module](https://github.com/freebsd/freebsd-src/blob/main/lib/libpam/modules/pam_xdg/pam_xdg.c) - uses `/var/run/xdg/{username}` (platformdirs fallback of `/var/run/user/{uid}` is reasonable) - **NetBSD**: No native XDG support found; [pkgsrc patches](https://github.com/NetBSD/pkgsrc/blob/trunk/misc/py-platformdirs/patches/patch-tests_test__unix.py) treat it same as FreeBSD Fixes #436

Applications need to discover both user-specific and system-wide application directories for desktop integration. The library already provides `user_applications_dir` but lacked the corresponding site-level counterpart, creating an asymmetry with other directory pairs like `user_data_dir`/`site_data_dir`. This adds `site_applications_dir` following official platform conventions verified from documentation. 📂 On Linux it returns `/usr/share/applications` (via `$XDG_DATA_DIRS`), on macOS `/Applications`, on Windows `C:\ProgramData\Microsoft\Windows\Start Menu\Programs`, and on Android it aliases to `user_applications_dir` since there's no system-wide distinction. The implementation follows the established pattern of other `site_*_dir` properties with multipath support and respects the `use_site_for_root` option on Unix systems. ✨ This allows applications to properly discover where system-wide desktop entries and application shortcuts should be installed. **Platform documentation references:** - Windows: [CSIDL (Microsoft Learn)](https://learn.microsoft.com/en-us/windows/win32/shell/csidl) - `CSIDL_COMMON_PROGRAMS` - Linux: [XDG Base Directory Specification](http://specifications.freedesktop.org/basedir/latest/) - `$XDG_DATA_DIRS/applications` - macOS: [Apple File System Programming Guide](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html) - `/Applications` Closes #435

Applications that install system-wide executables need a standard location that mirrors `user_bin_dir`. Currently, `user_bin_dir` provides `~/.local/bin` on Unix/macOS and `%LOCALAPPDATA%\Programs` on Windows, but there's no corresponding site-wide equivalent. This creates API inconsistency since all other directory types (data, config, cache, state, log, runtime) have both user and site variants. ✨ Package managers like Chocolatey, pip, and uv need a consistent answer for where to install system-wide binaries. The implementation follows platform conventions researched from official documentation. Unix/Linux uses `/usr/local/bin` per [FHS 3.0](https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html), which designates this path for locally-installed software distinct from distribution packages in `/usr/bin`. macOS uses `/usr/local/bin` as the standard Homebrew and user installation location, since `/usr/bin` is read-only on modern macOS per [Apple's documentation](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html). Windows uses `%ProgramData%\bin` to mirror the `site_data_dir` pattern, following [Chocolatey's precedent](https://docs.chocolatey.org/en-us/choco/setup) of using `%ProgramData%\Chocolatey\bin` for system-wide package binaries. Android aliases to `user_bin_dir` since the platform has no system-wide installation concept per [Android's storage documentation](https://developer.android.com/guide/topics/data/data-storage). 🔍 The change also implements `use_site_for_root` support on Unix, allowing `user_bin_dir` to redirect to `site_bin_dir` when running as root. This matches the behavior of other `user_*` properties and provides a consistent experience for tools that need to install binaries differently based on privilege level. Closes #434

The existing `usage.rst` documentation mixed tutorial content with reference material in a single 661-line file. New users looking to get started had to wade through parameter tables and edge cases, while experienced users searching for specific parameters had to scan through introductory examples. 📖 This made the documentation harder to navigate and maintain as the library evolved. The reorganization follows the [Divio documentation system](https://documentation.divio.com/) by splitting the content into three focused pages. `usage.rst` becomes a tutorial teaching core concepts through real-world examples from Black, Poetry, virtualenv, and tox. `howto.rst` provides recipes for common tasks like handling write errors and platform-specific considerations. `parameters.rst` serves as a reference for all configuration options including the previously undocumented `use_site_for_root` parameter. ✨ This structure lets users quickly find what they need based on their goal. All examples now use `_path` variants instead of `_dir` for consistency with modern Python practices. Real-world code examples link directly to source files in production projects so users can see how established tools use `platformdirs`. Closes #433 --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Comparing changes

Open a pull request

Commits on Feb 14, 2026

This comparison is taking too long to generate.

Uh oh!