Upgrade platformdirs to 4.2.1

Author: pradyunsg

news/platformdirs.vendor.rst

@@ -1 +1 @@
-Upgrade platformdirs to 4.2.0
+Upgrade platformdirs to 4.2.1

src/pip/_vendor/platformdirs/__init__.py

@@ -1,6 +1,8 @@
 """
-Utilities for determining application-specific dirs. See <https://github.com/platformdirs/platformdirs> for details and
-usage.
+Utilities for determining application-specific dirs.
+
+See <https://github.com/platformdirs/platformdirs> for details and usage.
+
 """
 
 from __future__ import annotations
@@ -20,22 +22,22 @@
 
 def _set_platform_dir_class() -> type[PlatformDirsABC]:
     if sys.platform == "win32":
-        from pip._vendor.platformdirs.windows import Windows as Result
+        from pip._vendor.platformdirs.windows import Windows as Result  # noqa: PLC0415
     elif sys.platform == "darwin":
-        from pip._vendor.platformdirs.macos import MacOS as Result
+        from pip._vendor.platformdirs.macos import MacOS as Result  # noqa: PLC0415
     else:
-        from pip._vendor.platformdirs.unix import Unix as Result
+        from pip._vendor.platformdirs.unix import Unix as Result  # noqa: PLC0415
 
     if os.getenv("ANDROID_DATA") == "/data" and os.getenv("ANDROID_ROOT") == "/system":
         if os.getenv("SHELL") or os.getenv("PREFIX"):
             return Result
 
-        from pip._vendor.platformdirs.android import _android_folder
+        from pip._vendor.platformdirs.android import _android_folder  # noqa: PLC0415
 
         if _android_folder() is not None:
-            from pip._vendor.platformdirs.android import Android
+            from pip._vendor.platformdirs.android import Android  # noqa: PLC0415
 
-            return Android  # return to avoid redefinition of result
+            return Android  # return to avoid redefinition of a result
 
     return Result
 
@@ -507,7 +509,7 @@ def user_log_path(
 
 
 def user_documents_path() -> Path:
-    """:returns: documents path tied to the user"""
+    """:returns: documents a path tied to the user"""
     return PlatformDirs().user_documents_path
 
 
@@ -585,41 +587,41 @@ def site_runtime_path(
 
 
 __all__ = [
-    "__version__",
-    "__version_info__",
-    "PlatformDirs",
     "AppDirs",
+    "PlatformDirs",
     "PlatformDirsABC",
-    "user_data_dir",
-    "user_config_dir",
-    "user_cache_dir",
-    "user_state_dir",
-    "user_log_dir",
-    "user_documents_dir",
-    "user_downloads_dir",
-    "user_pictures_dir",
-    "user_videos_dir",
-    "user_music_dir",
-    "user_desktop_dir",
-    "user_runtime_dir",
-    "site_data_dir",
-    "site_config_dir",
+    "__version__",
+    "__version_info__",
     "site_cache_dir",
+    "site_cache_path",
+    "site_config_dir",
+    "site_config_path",
+    "site_data_dir",
+    "site_data_path",
     "site_runtime_dir",
-    "user_data_path",
-    "user_config_path",
+    "site_runtime_path",
+    "user_cache_dir",
     "user_cache_path",
-    "user_state_path",
-    "user_log_path",
+    "user_config_dir",
+    "user_config_path",
+    "user_data_dir",
+    "user_data_path",
+    "user_desktop_dir",
+    "user_desktop_path",
+    "user_documents_dir",
     "user_documents_path",
+    "user_downloads_dir",
     "user_downloads_path",
-    "user_pictures_path",
-    "user_videos_path",
+    "user_log_dir",
+    "user_log_path",
+    "user_music_dir",
     "user_music_path",
-    "user_desktop_path",
+    "user_pictures_dir",
+    "user_pictures_path",
+    "user_runtime_dir",
     "user_runtime_path",
-    "site_data_path",
-    "site_config_path",
-    "site_cache_path",
-    "site_runtime_path",
+    "user_state_dir",
+    "user_state_path",
+    "user_videos_dir",
+    "user_videos_path",
 ]

src/pip/_vendor/platformdirs/__main__.py

@@ -24,7 +24,7 @@
 
 
 def main() -> None:
-    """Run main entry point."""
+    """Run the main entry point."""
     app_name = "MyApp"
     app_author = "MyCompany"
 

src/pip/_vendor/platformdirs/android.py

@@ -13,10 +13,11 @@
 
 class Android(PlatformDirsABC):
     """
-    Follows the guidance `from here <https://android.stackexchange.com/a/216132>`_. Makes use of the
-    `appname <platformdirs.api.PlatformDirsABC.appname>`,
-    `version <platformdirs.api.PlatformDirsABC.version>`,
-    `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+    Follows the guidance `from here <https://android.stackexchange.com/a/216132>`_.
+
+    Makes use of the `appname <platformdirs.api.PlatformDirsABC.appname>`, `version
+    <platformdirs.api.PlatformDirsABC.version>`, `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+
     """
 
     @property
@@ -44,7 +45,7 @@ def site_config_dir(self) -> str:
 
     @property
     def user_cache_dir(self) -> str:
-        """:return: cache directory tied to the user, e.g. e.g. ``/data/user/<userid>/<packagename>/cache/<AppName>``"""
+        """:return: cache directory tied to the user, e.g.,``/data/user/<userid>/<packagename>/cache/<AppName>``"""
         return self._append_app_name_and_version(cast(str, _android_folder()), "cache")
 
     @property
@@ -119,13 +120,13 @@ def site_runtime_dir(self) -> str:
 def _android_folder() -> str | None:
     """:return: base folder for the Android OS or None if it cannot be found"""
     try:
-        # First try to get path to android app via pyjnius
-        from jnius import autoclass
+        # First try to get a path to android app via pyjnius
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         result: str | None = context.getFilesDir().getParentFile().getAbsolutePath()
     except Exception:  # noqa: BLE001
-        # if fails find an android folder looking path on the sys.path
+        # if fails find an android folder looking a path on the sys.path
         pattern = re.compile(r"/data/(data|user/\d+)/(.+)/files")
         for path in sys.path:
             if pattern.match(path):
@@ -141,7 +142,7 @@ def _android_documents_folder() -> str:
     """:return: documents folder for the Android OS"""
     # Get directories with pyjnius
     try:
-        from jnius import autoclass
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         environment = autoclass("android.os.Environment")
@@ -157,7 +158,7 @@ def _android_downloads_folder() -> str:
     """:return: downloads folder for the Android OS"""
     # Get directories with pyjnius
     try:
-        from jnius import autoclass
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         environment = autoclass("android.os.Environment")
@@ -173,7 +174,7 @@ def _android_pictures_folder() -> str:
     """:return: pictures folder for the Android OS"""
     # Get directories with pyjnius
     try:
-        from jnius import autoclass
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         environment = autoclass("android.os.Environment")
@@ -189,7 +190,7 @@ def _android_videos_folder() -> str:
     """:return: videos folder for the Android OS"""
     # Get directories with pyjnius
     try:
-        from jnius import autoclass
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         environment = autoclass("android.os.Environment")
@@ -205,7 +206,7 @@ def _android_music_folder() -> str:
     """:return: music folder for the Android OS"""
     # Get directories with pyjnius
     try:
-        from jnius import autoclass
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         environment = autoclass("android.os.Environment")

src/pip/_vendor/platformdirs/api.py

@@ -11,10 +11,10 @@
     from typing import Iterator, Literal
 
 
-class PlatformDirsABC(ABC):
+class PlatformDirsABC(ABC):  # noqa: PLR0904
     """Abstract base class for platform directories."""
 
-    def __init__(  # noqa: PLR0913
+    def __init__(  # noqa: PLR0913, PLR0917
         self,
         appname: str | None = None,
         appauthor: str | None | Literal[False] = None,
@@ -34,34 +34,47 @@ def __init__(  # noqa: PLR0913
         :param multipath: See `multipath`.
         :param opinion: See `opinion`.
         :param ensure_exists: See `ensure_exists`.
+
         """
         self.appname = appname  #: The name of application.
         self.appauthor = appauthor
         """
-        The name of the app author or distributing body for this application. Typically, it is the owning company name.
-        Defaults to `appname`. You may pass ``False`` to disable it.
+        The name of the app author or distributing body for this application.
+
+        Typically, it is the owning company name. Defaults to `appname`. You may pass ``False`` to disable it.
+
         """
         self.version = version
         """
-        An optional version path element to append to the path. You might want to use this if you want multiple versions
-        of your app to be able to run independently. If used, this would typically be ``<major>.<minor>``.
+        An optional version path element to append to the path.
+
+        You might want to use this if you want multiple versions of your app to be able to run independently. If used,
+        this would typically be ``<major>.<minor>``.
+
         """
         self.roaming = roaming
         """
-        Whether to use the roaming appdata directory on Windows. That means that for users on a Windows network setup
-        for roaming profiles, this user data will be synced on login (see
-        `here <http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>`_).
+        Whether to use the roaming appdata directory on Windows.
+
+        That means that for users on a Windows network setup for roaming profiles, this user data will be synced on
+        login (see
+        `here <https://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>`_).
+
         """
         self.multipath = multipath
         """
         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
         """
         Optionally create the directory (and any missing parents) upon access if it does not exist.
+
         By default, no directories are created.
+
         """
 
     def _append_app_name_and_version(self, *base: str) -> str:
@@ -200,7 +213,7 @@ def user_log_path(self) -> Path:
 
     @property
     def user_documents_path(self) -> Path:
-        """:return: documents path tied to the user"""
+        """:return: documents a path tied to the user"""
         return Path(self.user_documents_dir)
 
     @property

src/pip/_vendor/platformdirs/macos.py

@@ -10,11 +10,14 @@
 
 class MacOS(PlatformDirsABC):
     """
-    Platform directories for the macOS operating system. Follows the guidance from `Apple documentation
-    <https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html>`_.
+    Platform directories for the macOS operating system.
+
+    Follows the guidance from
+    `Apple documentation <https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html>`_.
     Makes use of the `appname <platformdirs.api.PlatformDirsABC.appname>`,
     `version <platformdirs.api.PlatformDirsABC.version>`,
     `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+
     """
 
     @property
@@ -28,7 +31,7 @@ def site_data_dir(self) -> str:
         :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,
+          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``
         """
@@ -60,7 +63,7 @@ def site_cache_dir(self) -> str:
         :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,
+          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``
         """