📝 docs: document user media dirs, fonts, and preference dir

gaborbernat · gaborbernat · commit 8a9378c08c66 · 2026-05-27T15:48:17.000-07:00
Add explanation, per-platform tables, and API references for
user_publicshare_dir, user_templates_dir, user_fonts_dir, and
user_preference_dir. Also add the missing "User media directories"
section to explanation.rst covering the full set of non-app-scoped
dirs, with upstream spec links (XDG user-dirs, Apple File System
Guide, Windows KNOWNFOLDERID).

Notable callouts: macOS has no native templates dir (~/Templates
fallback), Windows publicshare is machine-wide C:\Users\Public,
fonts on Windows uses the Win10+ per-user location, and
preference_dir is only distinct from config_dir on macOS.
diff --git a/docs/api.rst b/docs/api.rst
@@ -150,6 +150,42 @@ See also: :ref:`platforms:``user_projects_dir```
 
 .. autofunction:: platformdirs.user_projects_path
 
+User public share directory
+===========================
+
+See also: :ref:`platforms:``user_publicshare_dir```
+
+.. autofunction:: platformdirs.user_publicshare_dir
+
+.. autofunction:: platformdirs.user_publicshare_path
+
+User templates directory
+========================
+
+See also: :ref:`platforms:``user_templates_dir```
+
+.. autofunction:: platformdirs.user_templates_dir
+
+.. autofunction:: platformdirs.user_templates_path
+
+User fonts directory
+====================
+
+See also: :ref:`platforms:``user_fonts_dir```
+
+.. autofunction:: platformdirs.user_fonts_dir
+
+.. autofunction:: platformdirs.user_fonts_path
+
+User preference directory
+=========================
+
+See also: :ref:`platforms:``user_preference_dir```
+
+.. autofunction:: platformdirs.user_preference_dir
+
+.. autofunction:: platformdirs.user_preference_path
+
 ********************
  Shared directories
 ********************
diff --git a/docs/explanation.rst b/docs/explanation.rst
@@ -141,6 +141,133 @@ Use ``user_log_dir`` and ``site_log_dir`` for application logs:
         format="%(asctime)s - %(levelname)s - %(message)s",
     )
 
+******************************
+ User media directories
+******************************
+
+Unlike app dirs (data, config, cache, etc.), media dirs are **not** scoped to the app name. They point to
+standard user-facing folders that exist independently of any particular application. Use them when your app
+needs to read from or save into a folder the user already expects — not when storing application state.
+
+The distinction matters:
+
+- ``user_data_dir("MyApp")`` → ``~/.local/share/MyApp`` — your app's private storage
+- ``user_documents_dir()`` → ``~/Documents`` — the user's document library
+
+On Linux, media dirs are defined by the `XDG user-dirs specification
+<https://www.freedesktop.org/wiki/Software/xdg-user-dirs/>`_ and stored in ``~/.config/user-dirs.dirs``.
+The ``xdg-user-dirs`` tool lets users relocate them. Set the corresponding environment variable
+(``XDG_DOCUMENTS_DIR``, ``XDG_DOWNLOAD_DIR``, etc.) to override on a per-session basis. On macOS and
+Windows, ``platformdirs`` returns the platform-conventional location.
+
+Documents, downloads, and media
+================================
+
+Use these dirs when saving or opening files that belong in the user's library:
+
+.. list-table::
+   :widths: 30 20 50
+   :header-rows: 1
+
+   * - Property
+     - XDG variable
+     - Typical use
+   * - ``user_documents_dir``
+     - ``XDG_DOCUMENTS_DIR``
+     - Exported reports, user-authored files
+   * - ``user_downloads_dir``
+     - ``XDG_DOWNLOAD_DIR``
+     - Files fetched from the internet at user request
+   * - ``user_pictures_dir``
+     - ``XDG_PICTURES_DIR``
+     - Images the user owns
+   * - ``user_videos_dir``
+     - ``XDG_VIDEOS_DIR``
+     - Video files the user owns
+   * - ``user_music_dir``
+     - ``XDG_MUSIC_DIR``
+     - Audio files the user owns
+
+.. code-block:: python
+
+    from platformdirs import user_documents_path
+
+    # Save an exported report where the user expects documents
+    report = user_documents_path() / "report.pdf"
+
+Do not use ``user_documents_dir`` to store application data or config. If the file would confuse the user if
+they opened the folder, it belongs in ``user_data_dir`` instead.
+
+Desktop, projects, and public share
+=====================================
+
+.. list-table::
+   :widths: 30 20 50
+   :header-rows: 1
+
+   * - Property
+     - XDG variable
+     - Typical use
+   * - ``user_desktop_dir``
+     - ``XDG_DESKTOP_DIR``
+     - Shortcut files, launchers (rarely needed in code)
+   * - ``user_projects_dir``
+     - ``XDG_PROJECTS_DIR``
+     - Root directory for user's coding projects (`recently added to xdg-user-dirs
+       <https://gitlab.freedesktop.org/xdg/xdg-user-dirs/-/commit/217cae71c620ed2b3ed2936256ece68defccc6ab>`_)
+   * - ``user_publicshare_dir``
+     - ``XDG_PUBLICSHARE_DIR``
+     - Files shared with other users on the same machine
+
+On Windows, ``user_publicshare_dir`` returns ``C:\Users\Public`` (``%PUBLIC%``) — a machine-wide shared
+folder, not per-user. This matches what Rust ``dirs`` and Java ``directories-jvm`` return, following the
+platform convention.
+
+Templates
+=========
+
+``user_templates_dir`` (``XDG_TEMPLATES_DIR``) points to the folder used by file managers for new-file
+templates. macOS has no platform-defined templates directory; ``~/Templates`` is returned as a pragmatic
+fallback.
+
+Fonts
+=====
+
+``user_fonts_dir`` points to the per-user font installation directory:
+
+- **Linux**: ``$XDG_DATA_HOME/fonts`` (default ``~/.local/share/fonts``) — derived from ``$XDG_DATA_HOME``,
+  not a dedicated env var. See the `XDG Base Directory Specification
+  <https://specifications.freedesktop.org/basedir/latest/>`_.
+- **macOS**: ``~/Library/Fonts``
+- **Windows**: ``%LOCALAPPDATA%\Microsoft\Windows\Fonts`` — the per-user font location added in Windows 10
+
+.. code-block:: python
+
+    import shutil
+    from platformdirs import user_fonts_path
+
+    font_dir = user_fonts_path()
+    font_dir.mkdir(parents=True, exist_ok=True)
+    shutil.copy("MyFont.ttf", font_dir / "MyFont.ttf")
+
+**********************
+ Preference directory
+**********************
+
+``user_preference_dir`` is meaningful mainly on macOS, where Apple's conventions distinguish two separate
+locations:
+
+- ``~/Library/Application Support/AppName`` — long-term application data, databases, plug-ins
+- ``~/Library/Preferences/AppName`` — user-adjustable preference files (historically ``.plist``)
+
+On Linux and Windows, ``user_preference_dir`` is an alias for ``user_config_dir`` — the XDG and Windows
+conventions make no such distinction. On Android, it also aliases ``user_config_dir``.
+
+Use ``user_preference_dir`` when you specifically need to follow Apple's `File System Programming Guide
+<https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html>`_
+and store preference files in ``~/Library/Preferences``. For most cross-platform applications
+``user_config_dir`` is sufficient.
+
 **************************
  User vs site directories
 **************************
diff --git a/docs/platforms.rst b/docs/platforms.rst
@@ -406,6 +406,9 @@ See also: :ref:`api:User desktop directory`
 
 See also: :ref:`api:User projects directory`
 
+Defined by `$XDG_PROJECTS_DIR <https://gitlab.freedesktop.org/xdg/xdg-user-dirs/-/commit/217cae71c620ed2b3ed2936256ece68defccc6ab>`_
+(recently added to xdg-user-dirs).
+
 .. tab-set::
 
     .. tab-item:: Linux
@@ -429,6 +432,135 @@ See also: :ref:`api:User projects directory`
 
        ``/storage/emulated/0/Projects``
 
+``user_publicshare_dir``
+========================
+
+See also: :ref:`api:User public share directory`
+
+Defined by `$XDG_PUBLICSHARE_DIR <https://www.freedesktop.org/wiki/Software/xdg-user-dirs/>`_.
+
+On Windows, this is the machine-wide ``C:\Users\Public`` (``%PUBLIC%``), shared across all local accounts —
+not a per-user directory. See `FOLDERID_Public
+<https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid>`_.
+
+.. tab-set::
+
+    .. tab-item:: Linux
+       :sync: linux
+
+       ``~/Public`` (from ``$XDG_PUBLICSHARE_DIR`` if set, else ``$XDG_PUBLICSHARE_DIR`` entry in
+       ``user-dirs.dirs``, else ``~/Public``)
+
+    .. tab-item:: macOS
+       :sync: macos
+
+       ``~/Public``
+
+    .. tab-item:: Windows
+       :sync: windows
+
+       ``C:\Users\Public`` (``%PUBLIC%``)
+
+    .. tab-item:: Android
+       :sync: android
+
+       ``/storage/emulated/0/Public``
+
+``user_templates_dir``
+======================
+
+See also: :ref:`api:User templates directory`
+
+Defined by `$XDG_TEMPLATES_DIR <https://www.freedesktop.org/wiki/Software/xdg-user-dirs/>`_. macOS has no
+platform-defined templates directory; ``~/Templates`` is returned as a pragmatic fallback. On Windows, see
+`FOLDERID_Templates <https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid>`_.
+
+.. tab-set::
+
+    .. tab-item:: Linux
+       :sync: linux
+
+       ``~/Templates`` (from ``$XDG_TEMPLATES_DIR`` if set, else ``$XDG_TEMPLATES_DIR`` entry in
+       ``user-dirs.dirs``, else ``~/Templates``)
+
+    .. tab-item:: macOS
+       :sync: macos
+
+       ``~/Templates`` (pragmatic fallback; macOS has no native templates directory)
+
+    .. tab-item:: Windows
+       :sync: windows
+
+       ``%APPDATA%\Microsoft\Windows\Templates``
+
+    .. tab-item:: Android
+       :sync: android
+
+       ``/storage/emulated/0/Templates``
+
+``user_fonts_dir``
+==================
+
+See also: :ref:`api:User fonts directory`
+
+Derived from ``$XDG_DATA_HOME/fonts`` on Linux (no dedicated env var). See the `XDG Base Directory
+Specification <https://specifications.freedesktop.org/basedir/latest/>`_. On Windows, uses the per-user font
+location added in Windows 10.
+
+.. tab-set::
+
+    .. tab-item:: Linux
+       :sync: linux
+
+       ``$XDG_DATA_HOME/fonts`` (default ``~/.local/share/fonts``)
+
+    .. tab-item:: macOS
+       :sync: macos
+
+       ``~/Library/Fonts``
+
+    .. tab-item:: Windows
+       :sync: windows
+
+       ``%LOCALAPPDATA%\Microsoft\Windows\Fonts``
+
+    .. tab-item:: Android
+       :sync: android
+
+       ``/storage/emulated/0/fonts``
+
+``user_preference_dir``
+=======================
+
+See also: :ref:`api:User preference directory`
+
+On macOS, ``~/Library/Preferences`` is distinct from ``~/Library/Application Support`` (``user_config_dir``).
+See `Apple's File System Programming Guide
+<https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html>`_.
+On all other platforms, this aliases ``user_config_dir``.
+
+.. tab-set::
+
+    .. tab-item:: Linux
+       :sync: linux
+
+       Same as ``user_config_dir`` (``$XDG_CONFIG_HOME`` or ``~/.config/AppName``)
+
+    .. tab-item:: macOS
+       :sync: macos
+
+       ``~/Library/Preferences/AppName`` (distinct from ``~/Library/Application Support``)
+
+    .. tab-item:: Windows
+       :sync: windows
+
+       Same as ``user_config_dir`` (``%APPDATA%\AppName``)
+
+    .. tab-item:: Android
+       :sync: android
+
+       Same as ``user_config_dir``
+
 ********************
  Shared directories
 ********************
