✨ feat: add user_projects_dir for $XDG_PROJECTS_DIR (#490)

The XDG user-dirs spec added `XDG_PROJECTS_DIR` in xdg-user-dirs 0.0.4
and recently wired it up fully (see [commit
217cae71](https://gitlab.freedesktop.org/xdg/xdg-user-dirs/-/commit/217cae71c620ed2b3ed2936256ece68defccc6ab)
and [issue
xdg-user-dirs#3](https://gitlab.freedesktop.org/xdg/xdg-user-dirs/-/work_items/3)).
Other ecosystems (Rust `dirs`, Java `directories-jvm`) already expose
this. Closes #485.

The implementation follows the same pattern as `user_documents_dir` and
other XDG user-dirs: on Linux, `unix.py` reads from `user-dirs.dirs` via
`_get_user_media_dir("XDG_PROJECTS_DIR", "~/Projects")`, `XDGMixin` in
`_xdg.py` handles the env var override, and all other platforms (macOS,
Windows, Android) fall back to `~/Projects` since no native shell folder
exists for projects on those platforms.

Both `user_projects_dir` (str) and `user_projects_path` (Path) are
exposed as properties, module-level convenience functions, and
documented in `api.rst` and `platforms.rst`.

Author: gaborbernat

docs/api.rst

@@ -141,6 +141,15 @@ See also: :ref:`platforms:``user_desktop_dir```
 
 .. autofunction:: platformdirs.user_desktop_path
 
+User projects directory
+=======================
+
+See also: :ref:`platforms:``user_projects_dir```
+
+.. autofunction:: platformdirs.user_projects_dir
+
+.. autofunction:: platformdirs.user_projects_path
+
 ********************
  Shared directories
 ********************

docs/platforms.rst

@@ -401,6 +401,34 @@ See also: :ref:`api:User desktop directory`
 
        ``/storage/emulated/0/Desktop``
 
+``user_projects_dir``
+=====================
+
+See also: :ref:`api:User projects directory`
+
+.. tab-set::
+
+    .. tab-item:: Linux
+       :sync: linux
+
+       ``~/Projects`` (from ``$XDG_PROJECTS_DIR`` if set, else ``$XDG_PROJECTS_DIR`` entry in
+       ``user-dirs.dirs``, else ``~/Projects``)
+
+    .. tab-item:: macOS
+       :sync: macos
+
+       ``~/Projects``
+
+    .. tab-item:: Windows
+       :sync: windows
+
+       ``C:\Users\<User>\Projects``
+
+    .. tab-item:: Android
+       :sync: android
+
+       ``/storage/emulated/0/Projects``
+
 ********************
  Shared directories
 ********************

src/platformdirs/__init__.py

@@ -344,6 +344,11 @@ def user_desktop_dir() -> str:
     return PlatformDirs().user_desktop_dir
 
 
+def user_projects_dir() -> str:
+    """:returns: projects directory tied to the user"""
+    return PlatformDirs().user_projects_dir
+
+
 def user_bin_dir() -> str:
     """:returns: bin directory tied to the user"""
     return PlatformDirs().user_bin_dir
@@ -720,6 +725,11 @@ def user_desktop_path() -> Path:
     return PlatformDirs().user_desktop_path
 
 
+def user_projects_path() -> Path:
+    """:returns: projects path tied to the user"""
+    return PlatformDirs().user_projects_path
+
+
 def user_bin_path() -> Path:
     """:returns: bin path tied to the user"""
     return PlatformDirs().user_bin_path
@@ -848,6 +858,8 @@ def site_runtime_path(
     "user_music_path",
     "user_pictures_dir",
     "user_pictures_path",
+    "user_projects_dir",
+    "user_projects_path",
     "user_runtime_dir",
     "user_runtime_path",
     "user_state_dir",

src/platformdirs/__main__.py

@@ -15,6 +15,7 @@
     "user_pictures_dir",
     "user_videos_dir",
     "user_music_dir",
+    "user_projects_dir",
     "user_bin_dir",
     "site_bin_dir",
     "user_applications_dir",

src/platformdirs/_xdg.py

@@ -118,6 +118,13 @@ def user_desktop_dir(self) -> str:
             return os.path.expanduser(path)  # noqa: PTH111
         return super().user_desktop_dir
 
+    @property
+    def user_projects_dir(self) -> str:
+        """:returns: projects directory tied to the user, from ``$XDG_PROJECTS_DIR`` if set, else platform default"""
+        if path := os.environ.get("XDG_PROJECTS_DIR", "").strip():
+            return os.path.expanduser(path)  # noqa: PTH111
+        return super().user_projects_dir
+
     @property
     def user_applications_dir(self) -> str:
         """:returns: applications directory tied to the user, from ``$XDG_DATA_HOME`` if set, else platform default"""

src/platformdirs/android.py

@@ -107,6 +107,11 @@ def user_desktop_dir(self) -> str:
         """:returns: desktop directory tied to the user e.g. ``/storage/emulated/0/Desktop``"""
         return "/storage/emulated/0/Desktop"
 
+    @property
+    def user_projects_dir(self) -> str:
+        """:returns: projects directory tied to the user e.g. ``/storage/emulated/0/Projects``"""
+        return "/storage/emulated/0/Projects"
+
     @property
     def user_bin_dir(self) -> str:
         """:returns: bin directory tied to the user, e.g. ``/data/user/<userid>/<packagename>/files/bin``"""

src/platformdirs/api.py

@@ -208,6 +208,11 @@ def user_music_dir(self) -> str:
     def user_desktop_dir(self) -> str:
         """:returns: desktop directory tied to the user"""
 
+    @property
+    @abstractmethod
+    def user_projects_dir(self) -> str:
+        """:returns: projects directory tied to the user"""
+
     @property
     @abstractmethod
     def user_bin_dir(self) -> str:
@@ -322,6 +327,11 @@ def user_desktop_path(self) -> Path:
         """:returns: desktop path tied to the user"""
         return Path(self.user_desktop_dir)
 
+    @property
+    def user_projects_path(self) -> Path:
+        """:returns: projects path tied to the user"""
+        return Path(self.user_projects_dir)
+
     @property
     def user_bin_path(self) -> Path:
         """:returns: bin path tied to the user"""

src/platformdirs/macos.py

@@ -134,6 +134,11 @@ def user_desktop_dir(self) -> str:
         """:returns: desktop directory tied to the user, e.g. ``~/Desktop``"""
         return os.path.expanduser("~/Desktop")  # noqa: PTH111
 
+    @property
+    def user_projects_dir(self) -> str:
+        """:returns: projects directory tied to the user, e.g. ``~/Projects``"""
+        return os.path.expanduser("~/Projects")  # noqa: PTH111
+
     @property
     def user_bin_dir(self) -> str:
         """:returns: bin directory tied to the user, e.g. ``~/.local/bin``"""

src/platformdirs/unix.py

@@ -123,6 +123,11 @@ def user_desktop_dir(self) -> str:
         """:returns: desktop directory tied to the user, e.g. ``~/Desktop``"""
         return _get_user_media_dir("XDG_DESKTOP_DIR", "~/Desktop")
 
+    @property
+    def user_projects_dir(self) -> str:
+        """:returns: projects directory tied to the user, e.g. ``~/Projects``"""
+        return _get_user_media_dir("XDG_PROJECTS_DIR", "~/Projects")
+
     @property
     def user_bin_dir(self) -> str:
         """:returns: bin directory tied to the user, e.g. ``~/.local/bin``"""

src/platformdirs/windows.py

@@ -133,6 +133,11 @@ def user_desktop_dir(self) -> str:
         r""":returns: desktop directory tied to the user, e.g. ``%USERPROFILE%\Desktop``"""
         return os.path.normpath(get_win_folder("CSIDL_DESKTOPDIRECTORY"))
 
+    @property
+    def user_projects_dir(self) -> str:
+        r""":returns: projects directory tied to the user, e.g. ``%USERPROFILE%\Projects``"""
+        return os.path.normpath(os.path.expanduser("~/Projects"))  # noqa: PTH111
+
     @property
     def user_bin_dir(self) -> str:
         r""":returns: bin directory tied to the user, e.g. ``%LOCALAPPDATA%\Programs``"""