platformdirs: introduce user_downloads_dir()

README.rst

@@ -41,6 +41,7 @@ This kind of thing is what the ``platformdirs`` package is for.
 - site config dir (``site_config_dir``)
 - user log dir (``user_log_dir``)
 - user documents dir (``user_documents_dir``)
+- user downloads dir (``user_downloads_dir``)
 - user runtime dir (``user_runtime_dir``)
 
 And also:
@@ -68,6 +69,8 @@ On macOS:
     '/Users/trentm/Library/Logs/SuperApp'
     >>> user_documents_dir()
     '/Users/trentm/Documents'
+    >>> user_downloads_dir()
+    '/Users/trentm/Downloads'
     >>> user_runtime_dir(appname, appauthor)
     '/Users/trentm/Library/Caches/TemporaryItems/SuperApp'
 
@@ -88,6 +91,8 @@ On Windows:
     'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Logs'
     >>> user_documents_dir()
     'C:\\Users\\trentm\\Documents'
+    >>> user_downloads_dir()
+    'C:\\Users\\trentm\\Downloads'
     >>> user_runtime_dir(appname, appauthor)
     'C:\\Users\\trentm\\AppData\\Local\\Temp\\Acme\\SuperApp'
 
@@ -112,6 +117,8 @@ On Linux:
     '/home/trentm/.config/SuperApp'
     >>> user_documents_dir()
     '/home/trentm/Documents'
+    >>> user_downloads_dir()
+    '/home/trentm/Downloads'
     >>> user_runtime_dir(appname, appauthor)
     '/run/user/{os.getuid()}/SuperApp'
     >>> site_config_dir(appname)
@@ -135,6 +142,8 @@ On Android::
     '/data/data/com.myApp/shared_prefs/SuperApp'
     >>> user_documents_dir()
     '/storage/emulated/0/Documents'
+    >>> user_downloads_dir()
+    '/storage/emulated/0/Downloads'
     >>> user_runtime_dir(appname, appauthor)
     '/data/data/com.myApp/cache/SuperApp/tmp'
 
@@ -162,6 +171,8 @@ apps also support ``XDG_*`` environment variables.
     '/Users/trentm/Library/Logs/SuperApp'
     >>> dirs.user_documents_dir
     '/Users/trentm/Documents'
+    >>> dirs.user_downloads_dir
+    '/Users/trentm/Downloads'
     >>> dirs.user_runtime_dir
     '/Users/trentm/Library/Caches/TemporaryItems/SuperApp'
 
@@ -184,6 +195,8 @@ dirs::
     '/Users/trentm/Library/Logs/SuperApp/1.0'
     >>> dirs.user_documents_dir
     '/Users/trentm/Documents'
+    >>> dirs.user_downloads_dir
+    '/Users/trentm/Downloads'
     >>> dirs.user_runtime_dir
     '/Users/trentm/Library/Caches/TemporaryItems/SuperApp/1.0'
 

docs/api.rst

@@ -42,6 +42,12 @@ User documents directory
 .. autofunction:: platformdirs.user_documents_dir
 .. autofunction:: platformdirs.user_documents_path
 
+User downloads directory
+------------------------
+
+.. autofunction:: platformdirs.user_downloads_dir
+.. autofunction:: platformdirs.user_downloads_path
+
 Runtime directory
 -------------------
 

src/platformdirs/__init__.py

@@ -244,6 +244,11 @@ def user_documents_dir() -> str:
     return PlatformDirs().user_documents_dir
 
 
+def user_downloads_dir() -> str:
+    """:returns: downloads directory tied to the user"""
+    return PlatformDirs().user_downloads_dir
+
+
 def user_pictures_dir() -> str:
     """:returns: pictures directory tied to the user"""
     return PlatformDirs().user_pictures_dir
@@ -480,6 +485,11 @@ def user_documents_path() -> Path:
     return PlatformDirs().user_documents_path
 
 
+def user_downloads_path() -> Path:
+    """:returns: downloads path tied to the user"""
+    return PlatformDirs().user_downloads_path
+
+
 def user_pictures_path() -> Path:
     """:returns: pictures path tied to the user"""
     return PlatformDirs().user_pictures_path
@@ -531,6 +541,7 @@ def user_runtime_path(
     "user_state_dir",
     "user_log_dir",
     "user_documents_dir",
+    "user_downloads_dir",
     "user_pictures_dir",
     "user_videos_dir",
     "user_music_dir",
@@ -544,6 +555,7 @@ def user_runtime_path(
     "user_state_path",
     "user_log_path",
     "user_documents_path",
+    "user_downloads_path",
     "user_pictures_path",
     "user_videos_path",
     "user_music_path",

src/platformdirs/__main__.py

@@ -10,6 +10,7 @@
     "user_state_dir",
     "user_log_dir",
     "user_documents_dir",
+    "user_downloads_dir",
     "user_pictures_dir",
     "user_videos_dir",
     "user_music_dir",

src/platformdirs/android.py

@@ -72,6 +72,11 @@ def user_documents_dir(self) -> str:
         """:return: documents directory tied to the user e.g. ``/storage/emulated/0/Documents``"""
         return _android_documents_folder()
 
+    @property
+    def user_downloads_dir(self) -> str:
+        """:return: downloads directory tied to the user e.g. ``/storage/emulated/0/Downloads``"""
+        return _android_downloads_folder()
+
     @property
     def user_pictures_dir(self) -> str:
         """:return: pictures directory tied to the user e.g. ``/storage/emulated/0/Pictures``"""
@@ -136,6 +141,22 @@ def _android_documents_folder() -> str:
     return documents_dir
 
 
+@lru_cache(maxsize=1)
+def _android_downloads_folder() -> str:
+    """:return: downloads folder for the Android OS"""
+    # Get directories with pyjnius
+    try:
+        from jnius import autoclass
+
+        context = autoclass("android.content.Context")
+        environment = autoclass("android.os.Environment")
+        downloads_dir: str = context.getExternalFilesDir(environment.DIRECTORY_DOWNLOADS).getAbsolutePath()
+    except Exception:  # noqa: BLE001
+        downloads_dir = "/storage/emulated/0/Downloads"
+
+    return downloads_dir
+
+
 @lru_cache(maxsize=1)
 def _android_pictures_folder() -> str:
     """:return: pictures folder for the Android OS"""

src/platformdirs/api.py

@@ -127,6 +127,11 @@ def user_log_dir(self) -> str:
     def user_documents_dir(self) -> str:
         """:return: documents directory tied to the user"""
 
+    @property
+    @abstractmethod
+    def user_downloads_dir(self) -> str:
+        """:return: downloads directory tied to the user"""
+
     @property
     @abstractmethod
     def user_pictures_dir(self) -> str:
@@ -192,6 +197,11 @@ def user_documents_path(self) -> Path:
         """:return: documents path tied to the user"""
         return Path(self.user_documents_dir)
 
+    @property
+    def user_downloads_path(self) -> Path:
+        """:return: downloads path tied to the user"""
+        return Path(self.user_downloads_dir)
+
     @property
     def user_pictures_path(self) -> Path:
         """:return: pictures path tied to the user"""

src/platformdirs/macos.py

@@ -60,6 +60,11 @@ def user_documents_dir(self) -> str:
         """:return: documents directory tied to the user, e.g. ``~/Documents``"""
         return os.path.expanduser("~/Documents")  # noqa: PTH111
 
+    @property
+    def user_downloads_dir(self) -> str:
+        """:return: downloads directory tied to the user, e.g. ``~/Downloads``"""
+        return os.path.expanduser("~/Downloads")  # noqa: PTH111
+
     @property
     def user_pictures_dir(self) -> str:
         """:return: pictures directory tied to the user, e.g. ``~/Pictures``"""

src/platformdirs/unix.py

@@ -126,6 +126,11 @@ def user_documents_dir(self) -> str:
         """:return: documents directory tied to the user, e.g. ``~/Documents``"""
         return _get_user_media_dir("XDG_DOCUMENTS_DIR", "~/Documents")
 
+    @property
+    def user_downloads_dir(self) -> str:
+        """:return: downloads directory tied to the user, e.g. ``~/Downloads``"""
+        return _get_user_media_dir("XDG_DOWNLOAD_DIR", "~/Downloads")
+
     @property
     def user_pictures_dir(self) -> str:
         """:return: pictures directory tied to the user, e.g. ``~/Pictures``"""

src/platformdirs/windows.py

@@ -102,6 +102,11 @@ def user_documents_dir(self) -> str:
         """:return: documents directory tied to the user e.g. ``%USERPROFILE%\\Documents``"""
         return os.path.normpath(get_win_folder("CSIDL_PERSONAL"))
 
+    @property
+    def user_downloads_dir(self) -> str:
+        """:return: downloads directory tied to the user e.g. ``%USERPROFILE%\\Downloads``"""
+        return os.path.normpath(get_win_folder("CSIDL_DOWNLOADS"))
+
     @property
     def user_pictures_dir(self) -> str:
         """:return: pictures directory tied to the user e.g. ``%USERPROFILE%\\Pictures``"""
@@ -153,6 +158,9 @@ def get_win_folder_if_csidl_name_not_env_var(csidl_name: str) -> str | None:
     if csidl_name == "CSIDL_PERSONAL":
         return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Documents")  # noqa: PTH118
 
+    if csidl_name == "CSIDL_DOWNLOADS":
+        return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Downloads")  # noqa: PTH118
+
     if csidl_name == "CSIDL_MYPICTURES":
         return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Pictures")  # noqa: PTH118
 
@@ -176,6 +184,7 @@ def get_win_folder_from_registry(csidl_name: str) -> str:
         "CSIDL_COMMON_APPDATA": "Common AppData",
         "CSIDL_LOCAL_APPDATA": "Local AppData",
         "CSIDL_PERSONAL": "Personal",
+        "CSIDL_DOWNLOADS": "{374DE290-123F-4565-9164-39C4925E467B}",
         "CSIDL_MYPICTURES": "My Pictures",
         "CSIDL_MYVIDEO": "My Video",
         "CSIDL_MYMUSIC": "My Music",
@@ -194,6 +203,10 @@ def get_win_folder_from_registry(csidl_name: str) -> str:
 
 def get_win_folder_via_ctypes(csidl_name: str) -> str:
     """Get folder with ctypes."""
+    # There is no 'CSIDL_DOWNLOADS'.
+    # Use 'CSIDL_PROFILE' (40) and append the default folder 'Downloads' instead.
+    # https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid
+
     csidl_const = {
         "CSIDL_APPDATA": 26,
         "CSIDL_COMMON_APPDATA": 35,
@@ -202,6 +215,7 @@ def get_win_folder_via_ctypes(csidl_name: str) -> str:
         "CSIDL_MYPICTURES": 39,
         "CSIDL_MYVIDEO": 14,
         "CSIDL_MYMUSIC": 13,
+        "CSIDL_DOWNLOADS": 40,
     }.get(csidl_name)
     if csidl_const is None:
         msg = f"Unknown CSIDL name: {csidl_name}"
@@ -217,6 +231,9 @@ def get_win_folder_via_ctypes(csidl_name: str) -> str:
         if windll.kernel32.GetShortPathNameW(buf.value, buf2, 1024):
             buf = buf2
 
+    if csidl_name == "CSIDL_DOWNLOADS":
+        return os.path.join(buf.value, "Downloads")  # noqa: PTH118
+
     return buf.value
 
 

tests/conftest.py

@@ -14,6 +14,7 @@
     "user_state_dir",
     "user_log_dir",
     "user_documents_dir",
+    "user_downloads_dir",
     "user_pictures_dir",
     "user_videos_dir",
     "user_music_dir",

tests/test_android.py

@@ -54,6 +54,7 @@ def test_android(mocker: MockerFixture, params: dict[str, Any], func: str) -> No
         "user_state_dir": f"/data/data/com.example/files{suffix}",
         "user_log_dir": f"/data/data/com.example/cache{suffix}{'' if params.get('opinion', True) is False else '/log'}",
         "user_documents_dir": "/storage/emulated/0/Documents",
+        "user_downloads_dir": "/storage/emulated/0/Downloads",
         "user_pictures_dir": "/storage/emulated/0/Pictures",
         "user_videos_dir": "/storage/emulated/0/DCIM/Camera",
         "user_music_dir": "/storage/emulated/0/Music",

tests/test_macos.py

@@ -33,6 +33,7 @@ def test_macos(params: dict[str, Any], func: str) -> None:
         "user_state_dir": f"{home}/Library/Application Support{suffix}",
         "user_log_dir": f"{home}/Library/Logs{suffix}",
         "user_documents_dir": f"{home}/Documents",
+        "user_downloads_dir": f"{home}/Downloads",
         "user_pictures_dir": f"{home}/Pictures",
         "user_videos_dir": f"{home}/Movies",
         "user_music_dir": f"{home}/Music",

tests/test_unix.py

@@ -16,7 +16,16 @@
     from pytest_mock import MockerFixture
 
 
-@pytest.mark.parametrize("prop", ["user_documents_dir", "user_pictures_dir", "user_videos_dir", "user_music_dir"])
+@pytest.mark.parametrize(
+    "prop",
+    [
+        "user_documents_dir",
+        "user_downloads_dir",
+        "user_pictures_dir",
+        "user_videos_dir",
+        "user_music_dir",
+    ],
+)
 def test_user_media_dir(mocker: MockerFixture, prop: str) -> None:
     example_path = "/home/example/ExampleMediaFolder"
     mock = mocker.patch("platformdirs.unix._get_user_dirs_folder")
@@ -28,6 +37,7 @@ def test_user_media_dir(mocker: MockerFixture, prop: str) -> None:
     ("env_var", "prop"),
     [
         pytest.param("XDG_DOCUMENTS_DIR", "user_documents_dir", id="user_documents_dir"),
+        pytest.param("XDG_DOWNLOAD_DIR", "user_downloads_dir", id="user_downloads_dir"),
         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"),
@@ -48,6 +58,7 @@ def test_user_media_dir_env_var(mocker: MockerFixture, env_var: str, prop: str)
     ("env_var", "prop", "default_abs_path"),
     [
         pytest.param("XDG_DOCUMENTS_DIR", "user_documents_dir", "/home/example/Documents", id="user_documents_dir"),
+        pytest.param("XDG_DOWNLOAD_DIR", "user_downloads_dir", "/home/example/Downloads", id="user_downloads_dir"),
         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"),