Upgrade platformdirs to 4.2.0

Author: sbidoul

news/platformdirs.vendor.rst

@@ -0,0 +1 @@
+Upgrade platformdirs to 4.2.0

src/pip/_vendor/platformdirs/__init__.py

@@ -2,6 +2,7 @@
 Utilities for determining application-specific dirs. See <https://github.com/platformdirs/platformdirs> for details and
 usage.
 """
+
 from __future__ import annotations
 
 import os
@@ -14,11 +15,7 @@
 
 if TYPE_CHECKING:
     from pathlib import Path
-
-    if sys.version_info >= (3, 8):  # pragma: no cover (py38+)
-        from typing import Literal
-    else:  # pragma: no cover (py38+)
-        from pip._vendor.typing_extensions import Literal
+    from typing import Literal
 
 
 def _set_platform_dir_class() -> type[PlatformDirsABC]:
@@ -264,6 +261,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,
@@ -288,6 +290,30 @@ def user_runtime_dir(
     ).user_runtime_dir
 
 
+def site_runtime_dir(
+    appname: str | None = None,
+    appauthor: str | None | Literal[False] = None,
+    version: str | None = None,
+    opinion: bool = True,  # noqa: FBT001, FBT002
+    ensure_exists: bool = False,  # noqa: FBT001, FBT002
+) -> str:
+    """
+    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+    :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
+    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+    :returns: runtime directory shared by users
+    """
+    return PlatformDirs(
+        appname=appname,
+        appauthor=appauthor,
+        version=version,
+        opinion=opinion,
+        ensure_exists=ensure_exists,
+    ).site_runtime_dir
+
+
 def user_data_path(
     appname: str | None = None,
     appauthor: str | None | Literal[False] = None,
@@ -505,6 +531,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,
@@ -529,6 +560,30 @@ def user_runtime_path(
     ).user_runtime_path
 
 
+def site_runtime_path(
+    appname: str | None = None,
+    appauthor: str | None | Literal[False] = None,
+    version: str | None = None,
+    opinion: bool = True,  # noqa: FBT001, FBT002
+    ensure_exists: bool = False,  # noqa: FBT001, FBT002
+) -> Path:
+    """
+    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+    :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
+    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+    :returns: runtime path shared by users
+    """
+    return PlatformDirs(
+        appname=appname,
+        appauthor=appauthor,
+        version=version,
+        opinion=opinion,
+        ensure_exists=ensure_exists,
+    ).site_runtime_path
+
+
 __all__ = [
     "__version__",
     "__version_info__",
@@ -545,10 +600,12 @@ 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",
     "site_cache_dir",
+    "site_runtime_dir",
     "user_data_path",
     "user_config_path",
     "user_cache_path",
@@ -559,8 +616,10 @@ 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",
     "site_cache_path",
+    "site_runtime_path",
 ]

src/pip/_vendor/platformdirs/__main__.py

@@ -1,4 +1,5 @@
 """Main entry point."""
+
 from __future__ import annotations
 
 from pip._vendor.platformdirs import PlatformDirs, __version__
@@ -18,6 +19,7 @@
     "site_data_dir",
     "site_config_dir",
     "site_cache_dir",
+    "site_runtime_dir",
 )
 
 

src/pip/_vendor/platformdirs/android.py

@@ -1,4 +1,5 @@
 """Android."""
+
 from __future__ import annotations
 
 import os
@@ -92,6 +93,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:
         """
@@ -103,6 +109,11 @@ def user_runtime_dir(self) -> str:
             path = os.path.join(path, "tmp")  # noqa: PTH118
         return path
 
+    @property
+    def site_runtime_dir(self) -> str:
+        """:return: runtime directory shared by users, same as `user_runtime_dir`"""
+        return self.user_runtime_dir
+
 
 @lru_cache(maxsize=1)
 def _android_folder() -> str | None:

src/pip/_vendor/platformdirs/api.py

@@ -1,4 +1,5 @@
 """Base API."""
+
 from __future__ import annotations
 
 import os
@@ -7,12 +8,7 @@
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    import sys
-
-    if sys.version_info >= (3, 8):  # pragma: no cover (py38+)
-        from typing import Literal
-    else:  # pragma: no cover (py38+)
-        from pip._vendor.typing_extensions import Literal
+    from typing import Iterator, Literal
 
 
 class PlatformDirsABC(ABC):
@@ -58,8 +54,8 @@ def __init__(  # noqa: PLR0913
         """
         self.multipath = multipath
         """
-        An optional parameter only applicable to Unix/Linux which indicates that the entire list of data dirs should be
-        returned. By default, the first item would only be returned.
+        An optional parameter which indicates that the entire list of data dirs should be returned.
+        By default, the first item would only be returned.
         """
         self.opinion = opinion  #: A flag to indicating to use opinionated values.
         self.ensure_exists = ensure_exists
@@ -147,11 +143,21 @@ 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:
         """:return: runtime directory tied to the user"""
 
+    @property
+    @abstractmethod
+    def site_runtime_dir(self) -> str:
+        """:return: runtime directory shared by users"""
+
     @property
     def user_data_path(self) -> Path:
         """:return: data path tied to the user"""
@@ -217,7 +223,57 @@ 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"""
         return Path(self.user_runtime_dir)
+
+    @property
+    def site_runtime_path(self) -> Path:
+        """:return: runtime path shared by users"""
+        return Path(self.site_runtime_dir)
+
+    def iter_config_dirs(self) -> Iterator[str]:
+        """:yield: all user and site configuration directories."""
+        yield self.user_config_dir
+        yield self.site_config_dir
+
+    def iter_data_dirs(self) -> Iterator[str]:
+        """:yield: all user and site data directories."""
+        yield self.user_data_dir
+        yield self.site_data_dir
+
+    def iter_cache_dirs(self) -> Iterator[str]:
+        """:yield: all user and site cache directories."""
+        yield self.user_cache_dir
+        yield self.site_cache_dir
+
+    def iter_runtime_dirs(self) -> Iterator[str]:
+        """:yield: all user and site runtime directories."""
+        yield self.user_runtime_dir
+        yield self.site_runtime_dir
+
+    def iter_config_paths(self) -> Iterator[Path]:
+        """:yield: all user and site configuration paths."""
+        for path in self.iter_config_dirs():
+            yield Path(path)
+
+    def iter_data_paths(self) -> Iterator[Path]:
+        """:yield: all user and site data paths."""
+        for path in self.iter_data_dirs():
+            yield Path(path)
+
+    def iter_cache_paths(self) -> Iterator[Path]:
+        """:yield: all user and site cache paths."""
+        for path in self.iter_cache_dirs():
+            yield Path(path)
+
+    def iter_runtime_paths(self) -> Iterator[Path]:
+        """:yield: all user and site runtime paths."""
+        for path in self.iter_runtime_dirs():
+            yield Path(path)

src/pip/_vendor/platformdirs/macos.py

@@ -1,7 +1,9 @@
 """macOS."""
+
 from __future__ import annotations
 
 import os.path
+import sys
 
 from .api import PlatformDirsABC
 
@@ -22,8 +24,20 @@ def user_data_dir(self) -> str:
 
     @property
     def site_data_dir(self) -> str:
-        """:return: data directory shared by users, e.g. ``/Library/Application Support/$appname/$version``"""
-        return self._append_app_name_and_version("/Library/Application Support")
+        """
+        :return: data directory shared by users, e.g. ``/Library/Application Support/$appname/$version``.
+          If we're using a Python binary managed by `Homebrew <https://brew.sh>`_, the directory
+          will be under the Homebrew prefix, e.g. ``/opt/homebrew/share/$appname/$version``.
+          If `multipath <platformdirs.api.PlatformDirsABC.multipath>` is enabled and we're in Homebrew,
+          the response is a multi-path string separated by ":", e.g.
+          ``/opt/homebrew/share/$appname/$version:/Library/Application Support/$appname/$version``
+        """
+        is_homebrew = sys.prefix.startswith("/opt/homebrew")
+        path_list = [self._append_app_name_and_version("/opt/homebrew/share")] if is_homebrew else []
+        path_list.append(self._append_app_name_and_version("/Library/Application Support"))
+        if self.multipath:
+            return os.pathsep.join(path_list)
+        return path_list[0]
 
     @property
     def user_config_dir(self) -> str:
@@ -42,8 +56,20 @@ def user_cache_dir(self) -> str:
 
     @property
     def site_cache_dir(self) -> str:
-        """:return: cache directory shared by users, e.g. ``/Library/Caches/$appname/$version``"""
-        return self._append_app_name_and_version("/Library/Caches")
+        """
+        :return: cache directory shared by users, e.g. ``/Library/Caches/$appname/$version``.
+          If we're using a Python binary managed by `Homebrew <https://brew.sh>`_, the directory
+          will be under the Homebrew prefix, e.g. ``/opt/homebrew/var/cache/$appname/$version``.
+          If `multipath <platformdirs.api.PlatformDirsABC.multipath>` is enabled and we're in Homebrew,
+          the response is a multi-path string separated by ":", e.g.
+          ``/opt/homebrew/var/cache/$appname/$version:/Library/Caches/$appname/$version``
+        """
+        is_homebrew = sys.prefix.startswith("/opt/homebrew")
+        path_list = [self._append_app_name_and_version("/opt/homebrew/var/cache")] if is_homebrew else []
+        path_list.append(self._append_app_name_and_version("/Library/Caches"))
+        if self.multipath:
+            return os.pathsep.join(path_list)
+        return path_list[0]
 
     @property
     def user_state_dir(self) -> str:
@@ -80,11 +106,21 @@ 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``"""
         return self._append_app_name_and_version(os.path.expanduser("~/Library/Caches/TemporaryItems"))  # noqa: PTH111
 
+    @property
+    def site_runtime_dir(self) -> str:
+        """:return: runtime directory shared by users, same as `user_runtime_dir`"""
+        return self.user_runtime_dir
+
 
 __all__ = [
     "MacOS",