Added desktop folder (#200)

README.rst

@@ -45,6 +45,7 @@ This kind of thing is what the ``platformdirs`` package is for.
 - user pictures dir (``user_pictures_dir``)
 - user videos dir (``user_videos_dir``)
 - user music dir (``user_music_dir``)
+- user desktop dir (``user_desktop_dir``)
 - user runtime dir (``user_runtime_dir``)
 
 And also:
@@ -80,6 +81,8 @@ On macOS:
     '/Users/trentm/Movies'
     >>> user_music_dir()
     '/Users/trentm/Music'
+    >>> user_desktop_dir()
+    '/Users/trentm/Desktop'
     >>> user_runtime_dir(appname, appauthor)
     '/Users/trentm/Library/Caches/TemporaryItems/SuperApp'
 
@@ -108,6 +111,8 @@ On Windows:
     'C:\\Users\\trentm\\Videos'
     >>> user_music_dir()
     'C:\\Users\\trentm\\Music'
+    >>> user_desktop_dir()
+    'C:\\Users\\trentm\\Desktop'
     >>> user_runtime_dir(appname, appauthor)
     'C:\\Users\\trentm\\AppData\\Local\\Temp\\Acme\\SuperApp'
 
@@ -140,6 +145,8 @@ On Linux:
     '/home/trentm/Videos'
     >>> user_music_dir()
     '/home/trentm/Music'
+    >>> user_desktop_dir()
+    '/home/trentm/Desktop'
     >>> user_runtime_dir(appname, appauthor)
     '/run/user/{os.getuid()}/SuperApp'
     >>> site_config_dir(appname)
@@ -171,6 +178,8 @@ On Android::
     '/storage/emulated/0/DCIM/Camera'
     >>> user_music_dir()
     '/storage/emulated/0/Music'
+    >>> user_desktop_dir()
+    '/storage/emulated/0/Desktop'
     >>> user_runtime_dir(appname, appauthor)
     '/data/data/com.myApp/cache/SuperApp/tmp'
 
@@ -206,6 +215,8 @@ apps also support ``XDG_*`` environment variables.
     '/Users/trentm/Movies'
     >>> dirs.user_music_dir
     '/Users/trentm/Music'
+    >>> dirs.user_desktop_dir
+    '/Users/trentm/Desktop'
     >>> dirs.user_runtime_dir
     '/Users/trentm/Library/Caches/TemporaryItems/SuperApp'
 
@@ -236,6 +247,8 @@ dirs::
     '/Users/trentm/Movies'
     >>> dirs.user_music_dir
     '/Users/trentm/Music'
+    >>> dirs.user_desktop_dir
+    '/Users/trentm/Desktop'
     >>> dirs.user_runtime_dir
     '/Users/trentm/Library/Caches/TemporaryItems/SuperApp/1.0'
 

src/platformdirs/__init__.py

@@ -264,6 +264,11 @@ def user_music_dir() -> str:
     return PlatformDirs().user_music_dir
 
 
+def user_desktop_dir() -> str:
+    """:returns: desktop directory tied to the user"""
+    return PlatformDirs().user_desktop_dir
+
+
 def user_runtime_dir(
     appname: str | None = None,
     appauthor: str | None | Literal[False] = None,
@@ -505,6 +510,11 @@ def user_music_path() -> Path:
     return PlatformDirs().user_music_path
 
 
+def user_desktop_path() -> Path:
+    """:returns: desktop path tied to the user"""
+    return PlatformDirs().user_desktop_path
+
+
 def user_runtime_path(
     appname: str | None = None,
     appauthor: str | None | Literal[False] = None,
@@ -545,6 +555,7 @@ def user_runtime_path(
     "user_pictures_dir",
     "user_videos_dir",
     "user_music_dir",
+    "user_desktop_dir",
     "user_runtime_dir",
     "site_data_dir",
     "site_config_dir",
@@ -559,6 +570,7 @@ def user_runtime_path(
     "user_pictures_path",
     "user_videos_path",
     "user_music_path",
+    "user_desktop_path",
     "user_runtime_path",
     "site_data_path",
     "site_config_path",

src/platformdirs/android.py

@@ -92,6 +92,11 @@ def user_music_dir(self) -> str:
         """:return: music directory tied to the user e.g. ``/storage/emulated/0/Music``"""
         return _android_music_folder()
 
+    @property
+    def user_desktop_dir(self) -> str:
+        """:return: desktop directory tied to the user e.g. ``/storage/emulated/0/Desktop``"""
+        return "/storage/emulated/0/Desktop"
+
     @property
     def user_runtime_dir(self) -> str:
         """

src/platformdirs/api.py

@@ -147,6 +147,11 @@ def user_videos_dir(self) -> str:
     def user_music_dir(self) -> str:
         """:return: music directory tied to the user"""
 
+    @property
+    @abstractmethod
+    def user_desktop_dir(self) -> str:
+        """:return: desktop directory tied to the user"""
+
     @property
     @abstractmethod
     def user_runtime_dir(self) -> str:
@@ -217,6 +222,11 @@ def user_music_path(self) -> Path:
         """:return: music path tied to the user"""
         return Path(self.user_music_dir)
 
+    @property
+    def user_desktop_path(self) -> Path:
+        """:return: desktop path tied to the user"""
+        return Path(self.user_desktop_dir)
+
     @property
     def user_runtime_path(self) -> Path:
         """:return: runtime path tied to the user"""

src/platformdirs/macos.py

@@ -80,6 +80,11 @@ def user_music_dir(self) -> str:
         """:return: music directory tied to the user, e.g. ``~/Music``"""
         return os.path.expanduser("~/Music")  # noqa: PTH111
 
+    @property
+    def user_desktop_dir(self) -> str:
+        """:return: desktop directory tied to the user, e.g. ``~/Desktop``"""
+        return os.path.expanduser("~/Desktop")  # noqa: PTH111
+
     @property
     def user_runtime_dir(self) -> str:
         """:return: runtime directory tied to the user, e.g. ``~/Library/Caches/TemporaryItems/$appname/$version``"""

src/platformdirs/unix.py

@@ -146,6 +146,11 @@ def user_music_dir(self) -> str:
         """:return: music directory tied to the user, e.g. ``~/Music``"""
         return _get_user_media_dir("XDG_MUSIC_DIR", "~/Music")
 
+    @property
+    def user_desktop_dir(self) -> str:
+        """:return: desktop directory tied to the user, e.g. ``~/Desktop``"""
+        return _get_user_media_dir("XDG_DESKTOP_DIR", "~/Desktop")
+
     @property
     def user_runtime_dir(self) -> str:
         """

src/platformdirs/windows.py

@@ -122,6 +122,11 @@ def user_music_dir(self) -> str:
         """:return: music directory tied to the user e.g. ``%USERPROFILE%\\Music``"""
         return os.path.normpath(get_win_folder("CSIDL_MYMUSIC"))
 
+    @property
+    def user_desktop_dir(self) -> str:
+        """:return: desktop directory tied to the user, e.g. ``%USERPROFILE%\\Desktop``"""
+        return os.path.normpath(get_win_folder("CSIDL_DESKTOPDIRECTORY"))
+
     @property
     def user_runtime_dir(self) -> str:
         """
@@ -216,6 +221,7 @@ def get_win_folder_via_ctypes(csidl_name: str) -> str:
         "CSIDL_MYVIDEO": 14,
         "CSIDL_MYMUSIC": 13,
         "CSIDL_DOWNLOADS": 40,
+        "CSIDL_DESKTOPDIRECTORY": 16,
     }.get(csidl_name)
     if csidl_const is None:
         msg = f"Unknown CSIDL name: {csidl_name}"

tests/test_android.py

@@ -58,6 +58,7 @@ def test_android(mocker: MockerFixture, params: dict[str, Any], func: str) -> No
         "user_pictures_dir": "/storage/emulated/0/Pictures",
         "user_videos_dir": "/storage/emulated/0/DCIM/Camera",
         "user_music_dir": "/storage/emulated/0/Music",
+        "user_desktop_dir": "/storage/emulated/0/Desktop",
         "user_runtime_dir": f"/data/data/com.example/cache{suffix}{'' if not params.get('opinion', True) else val}",
     }
     expected = expected_map[func]

tests/test_macos.py

@@ -37,6 +37,7 @@ def test_macos(params: dict[str, Any], func: str) -> None:
         "user_pictures_dir": f"{home}/Pictures",
         "user_videos_dir": f"{home}/Movies",
         "user_music_dir": f"{home}/Music",
+        "user_desktop_dir": f"{home}/Desktop",
         "user_runtime_dir": f"{home}/Library/Caches/TemporaryItems{suffix}",
     }
     expected = expected_map[func]

tests/test_unix.py

@@ -24,6 +24,7 @@
         "user_pictures_dir",
         "user_videos_dir",
         "user_music_dir",
+        "user_desktop_dir",
     ],
 )
 def test_user_media_dir(mocker: MockerFixture, prop: str) -> None:
@@ -41,6 +42,7 @@ def test_user_media_dir(mocker: MockerFixture, prop: str) -> None:
         pytest.param("XDG_PICTURES_DIR", "user_pictures_dir", id="user_pictures_dir"),
         pytest.param("XDG_VIDEOS_DIR", "user_videos_dir", id="user_videos_dir"),
         pytest.param("XDG_MUSIC_DIR", "user_music_dir", id="user_music_dir"),
+        pytest.param("XDG_DESKTOP_DIR", "user_desktop_dir", id="user_desktop_dir"),
     ],
 )
 def test_user_media_dir_env_var(mocker: MockerFixture, env_var: str, prop: str) -> None:
@@ -62,6 +64,7 @@ def test_user_media_dir_env_var(mocker: MockerFixture, env_var: str, prop: str)
         pytest.param("XDG_PICTURES_DIR", "user_pictures_dir", "/home/example/Pictures", id="user_pictures_dir"),
         pytest.param("XDG_VIDEOS_DIR", "user_videos_dir", "/home/example/Videos", id="user_videos_dir"),
         pytest.param("XDG_MUSIC_DIR", "user_music_dir", "/home/example/Music", id="user_music_dir"),
+        pytest.param("XDG_DESKTOP_DIR", "user_desktop_dir", "/home/example/Desktop", id="user_desktop_dir"),
     ],
 )
 def test_user_media_dir_default(mocker: MockerFixture, env_var: str, prop: str, default_abs_path: str) -> None: