Added desktop folder (#200)
diff --git a/README.rst b/README.rst
index 4db09e7..cb8f1a0 100644
--- a/README.rst
+++ b/README.rst
@@ -45,6 +45,7 @@
- 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 @@
'/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 @@
'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 @@
'/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 @@
'/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 @@
'/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 @@
'/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'
diff --git a/src/platformdirs/__init__.py b/src/platformdirs/__init__.py
index b263cd4..2d61c87 100644
--- a/src/platformdirs/__init__.py
+++ b/src/platformdirs/__init__.py
@@ -264,6 +264,11 @@
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 @@
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 @@
"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 @@
"user_pictures_path",
"user_videos_path",
"user_music_path",
+ "user_desktop_path",
"user_runtime_path",
"site_data_path",
"site_config_path",
diff --git a/src/platformdirs/android.py b/src/platformdirs/android.py
index 76527dd..29aa995 100644
--- a/src/platformdirs/android.py
+++ b/src/platformdirs/android.py
@@ -93,6 +93,11 @@
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:
"""
:return: runtime directory tied to the user, same as `user_cache_dir` if not opinionated else ``tmp`` in it,
diff --git a/src/platformdirs/api.py b/src/platformdirs/api.py
index fafd81c..ea327b2 100644
--- a/src/platformdirs/api.py
+++ b/src/platformdirs/api.py
@@ -149,6 +149,11 @@
@property
@abstractmethod
+ def user_desktop_dir(self) -> str:
+ """:return: desktop directory tied to the user"""
+
+ @property
+ @abstractmethod
def user_runtime_dir(self) -> str:
""":return: runtime directory tied to the user"""
@@ -218,6 +223,11 @@
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"""
return Path(self.user_runtime_dir)
diff --git a/src/platformdirs/macos.py b/src/platformdirs/macos.py
index a753e2a..3a10dcb 100644
--- a/src/platformdirs/macos.py
+++ b/src/platformdirs/macos.py
@@ -81,6 +81,11 @@
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``"""
return self._append_app_name_and_version(os.path.expanduser("~/Library/Caches/TemporaryItems")) # noqa: PTH111
diff --git a/src/platformdirs/unix.py b/src/platformdirs/unix.py
index 468b0ab..cddce49 100644
--- a/src/platformdirs/unix.py
+++ b/src/platformdirs/unix.py
@@ -147,6 +147,11 @@
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:
"""
:return: runtime directory tied to the user, e.g. ``/run/user/$(id -u)/$appname/$version`` or
diff --git a/src/platformdirs/windows.py b/src/platformdirs/windows.py
index b52c9c6..54c2f24 100644
--- a/src/platformdirs/windows.py
+++ b/src/platformdirs/windows.py
@@ -123,6 +123,11 @@
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:
"""
:return: runtime directory tied to the user, e.g.
@@ -216,6 +221,7 @@
"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}"
diff --git a/tests/test_android.py b/tests/test_android.py
index 40b7c33..281d7aa 100644
--- a/tests/test_android.py
+++ b/tests/test_android.py
@@ -58,6 +58,7 @@
"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]
diff --git a/tests/test_macos.py b/tests/test_macos.py
index 2059fc7..9214ec5 100644
--- a/tests/test_macos.py
+++ b/tests/test_macos.py
@@ -37,6 +37,7 @@
"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]
diff --git a/tests/test_unix.py b/tests/test_unix.py
index 1a28f59..3a52fd8 100644
--- a/tests/test_unix.py
+++ b/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 @@
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 @@
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:
