From bc4863e0dfe0d2b21ff9fb8e0f7bb0b980a8fb0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Sat, 14 Feb 2026 08:18:00 -0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(usage):=20document=20use=5F?= =?UTF-8?q?site=5Ffor=5Froot=20parameter?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 documenting use_site_for_root alongside other parameters. 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 --- docs/usage.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/usage.rst b/docs/usage.rst index 8b27b8b..33c4cd0 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -151,6 +151,24 @@ Defaults to ``False``. dirs = PlatformDirs("SuperApp", "Acme", ensure_exists=True) dirs.user_cache_dir # directory is created if it does not exist +``use_site_for_root`` +~~~~~~~~~~~~~~~~~~~~~ + +Unix-only. When ``True``, redirects ``user_*_dir`` calls to their ``site_*_dir`` equivalents when +running as root (uid 0). Defaults to ``False`` for backwards compatibility. + +When enabled, XDG user environment variables (e.g., ``XDG_DATA_HOME``) are bypassed for the +redirected directories. This is useful for system services running as root that should use +system-wide directories rather than root's home directory. + +.. code-block:: python + + from platformdirs import PlatformDirs + + dirs = PlatformDirs("SuperApp", use_site_for_root=True) + # When running as root, user_data_dir returns the site_data_dir path + dirs.user_data_dir # Returns site directory instead of /root/.local/share/SuperApp + Directories not covered -----------------------