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 -----------------------