Upgrade platformdirs to 3.2.0

Author: pfmoore

news/platformdirs.vendor.rst

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

src/pip/_vendor/platformdirs/__init__.py

@@ -12,6 +12,7 @@
     "user_runtime_dir",
     "site_data_dir",
     "site_config_dir",
+    "site_cache_dir",
 )
 
 

src/pip/_vendor/platformdirs/__main__.py

@@ -12,8 +12,9 @@
 class Android(PlatformDirsABC):
     """
     Follows the guidance `from here <https://android.stackexchange.com/a/216132>`_. Makes use of the
-    `appname <platformdirs.api.PlatformDirsABC.appname>` and
-    `version <platformdirs.api.PlatformDirsABC.version>`.
+    `appname <platformdirs.api.PlatformDirsABC.appname>`,
+    `version <platformdirs.api.PlatformDirsABC.version>`,
+    `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
     """
 
     @property
@@ -43,6 +44,11 @@ def user_cache_dir(self) -> str:
         """:return: cache directory tied to the user, e.g. e.g. ``/data/user/<userid>/<packagename>/cache/<AppName>``"""
         return self._append_app_name_and_version(cast(str, _android_folder()), "cache")
 
+    @property
+    def site_cache_dir(self) -> str:
+        """:return: cache directory shared by users, same as `user_cache_dir`"""
+        return self.user_cache_dir
+
     @property
     def user_state_dir(self) -> str:
         """:return: state directory tied to the user, same as `user_data_dir`"""

src/pip/_vendor/platformdirs/android.py

@@ -22,6 +22,7 @@ def __init__(
         roaming: bool = False,
         multipath: bool = False,
         opinion: bool = True,
+        ensure_exists: bool = False,
     ):
         """
         Create a new platform directory.
@@ -32,6 +33,7 @@ def __init__(
         :param roaming: See `roaming`.
         :param multipath: See `multipath`.
         :param opinion: See `opinion`.
+        :param ensure_exists: See `ensure_exists`.
         """
         self.appname = appname  #: The name of application.
         self.appauthor = appauthor
@@ -56,14 +58,25 @@ def __init__(
         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:
         params = list(base[1:])
         if self.appname:
             params.append(self.appname)
             if self.version:
                 params.append(self.version)
-        return os.path.join(base[0], *params)
+        path = os.path.join(base[0], *params)
+        self._optionally_create_directory(path)
+        return path
+
+    def _optionally_create_directory(self, path: str) -> None:
+        if self.ensure_exists:
+            Path(path).mkdir(parents=True, exist_ok=True)
 
     @property
     @abstractmethod
@@ -90,6 +103,11 @@ def site_config_dir(self) -> str:
     def user_cache_dir(self) -> str:
         """:return: cache directory tied to the user"""
 
+    @property
+    @abstractmethod
+    def site_cache_dir(self) -> str:
+        """:return: cache directory shared by users"""
+
     @property
     @abstractmethod
     def user_state_dir(self) -> str:
@@ -135,6 +153,11 @@ def user_cache_path(self) -> Path:
         """:return: cache path tied to the user"""
         return Path(self.user_cache_dir)
 
+    @property
+    def site_cache_path(self) -> Path:
+        """:return: cache path shared by users"""
+        return Path(self.site_cache_dir)
+
     @property
     def user_state_path(self) -> Path:
         """:return: state path tied to the user"""

src/pip/_vendor/platformdirs/api.py

@@ -9,14 +9,15 @@ 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>`_.
-    Makes use of the `appname <platformdirs.api.PlatformDirsABC.appname>` and
-    `version <platformdirs.api.PlatformDirsABC.version>`.
+    Makes use of the `appname <platformdirs.api.PlatformDirsABC.appname>`,
+    `version <platformdirs.api.PlatformDirsABC.version>`,
+    `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
     """
 
     @property
     def user_data_dir(self) -> str:
         """:return: data directory tied to the user, e.g. ``~/Library/Application Support/$appname/$version``"""
-        return self._append_app_name_and_version(os.path.expanduser("~/Library/Application Support/"))
+        return self._append_app_name_and_version(os.path.expanduser("~/Library/Application Support"))
 
     @property
     def site_data_dir(self) -> str:
@@ -25,19 +26,24 @@ def site_data_dir(self) -> str:
 
     @property
     def user_config_dir(self) -> str:
-        """:return: config directory tied to the user, e.g. ``~/Library/Preferences/$appname/$version``"""
-        return self._append_app_name_and_version(os.path.expanduser("~/Library/Preferences/"))
+        """:return: config directory tied to the user, same as `user_data_dir`"""
+        return self.user_data_dir
 
     @property
     def site_config_dir(self) -> str:
-        """:return: config directory shared by the users, e.g. ``/Library/Preferences/$appname``"""
-        return self._append_app_name_and_version("/Library/Preferences")
+        """:return: config directory shared by the users, same as `site_data_dir`"""
+        return self.site_data_dir
 
     @property
     def user_cache_dir(self) -> str:
         """:return: cache directory tied to the user, e.g. ``~/Library/Caches/$appname/$version``"""
         return self._append_app_name_and_version(os.path.expanduser("~/Library/Caches"))
 
+    @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")
+
     @property
     def user_state_dir(self) -> str:
         """:return: state directory tied to the user, same as `user_data_dir`"""

src/pip/_vendor/platformdirs/macos.py

@@ -24,7 +24,8 @@ class Unix(PlatformDirsABC):
     `appname <platformdirs.api.PlatformDirsABC.appname>`,
     `version <platformdirs.api.PlatformDirsABC.version>`,
     `multipath <platformdirs.api.PlatformDirsABC.multipath>`,
-    `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
+    `opinion <platformdirs.api.PlatformDirsABC.opinion>`,
+    `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
     """
 
     @property
@@ -93,6 +94,13 @@ def user_cache_dir(self) -> str:
             path = os.path.expanduser("~/.cache")
         return self._append_app_name_and_version(path)
 
+    @property
+    def site_cache_dir(self) -> str:
+        """
+        :return: cache directory shared by users, e.g. ``/var/tmp/$appname/$version``
+        """
+        return self._append_app_name_and_version("/var/tmp")
+
     @property
     def user_state_dir(self) -> str:
         """
@@ -148,6 +156,11 @@ def site_config_path(self) -> Path:
         """:return: config path shared by the users. Only return first item, even if ``multipath`` is set to ``True``"""
         return self._first_item_as_path_if_multipath(self.site_config_dir)
 
+    @property
+    def site_cache_path(self) -> Path:
+        """:return: cache path shared by users. Only return first item, even if ``multipath`` is set to ``True``"""
+        return self._first_item_as_path_if_multipath(self.site_cache_dir)
+
     def _first_item_as_path_if_multipath(self, directory: str) -> Path:
         if self.multipath:
             # If multipath is True, the first path is returned.

src/pip/_vendor/platformdirs/unix.py

@@ -1,4 +1,4 @@
 # file generated by setuptools_scm
 # don't change, don't track in version control
-__version__ = version = '2.6.2'
-__version_tuple__ = version_tuple = (2, 6, 2)
+__version__ = version = '3.2.0'
+__version_tuple__ = version_tuple = (3, 2, 0)

src/pip/_vendor/platformdirs/version.py

@@ -17,7 +17,9 @@ class Windows(PlatformDirsABC):
     `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`,
     `version <platformdirs.api.PlatformDirsABC.version>`,
     `roaming <platformdirs.api.PlatformDirsABC.roaming>`,
-    `opinion <platformdirs.api.PlatformDirsABC.opinion>`."""
+    `opinion <platformdirs.api.PlatformDirsABC.opinion>`,
+    `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+    """
 
     @property
     def user_data_dir(self) -> str:
@@ -41,7 +43,9 @@ def _append_parts(self, path: str, *, opinion_value: str | None = None) -> str:
                 params.append(opinion_value)
             if self.version:
                 params.append(self.version)
-        return os.path.join(path, *params)
+        path = os.path.join(path, *params)
+        self._optionally_create_directory(path)
+        return path
 
     @property
     def site_data_dir(self) -> str:
@@ -68,6 +72,12 @@ def user_cache_dir(self) -> str:
         path = os.path.normpath(get_win_folder("CSIDL_LOCAL_APPDATA"))
         return self._append_parts(path, opinion_value="Cache")
 
+    @property
+    def site_cache_dir(self) -> str:
+        """:return: cache directory shared by users, e.g. ``C:\\ProgramData\\$appauthor\\$appname\\Cache\\$version``"""
+        path = os.path.normpath(get_win_folder("CSIDL_COMMON_APPDATA"))
+        return self._append_parts(path, opinion_value="Cache")
+
     @property
     def user_state_dir(self) -> str:
         """:return: state directory tied to the user, same as `user_data_dir`"""
@@ -81,6 +91,7 @@ def user_log_dir(self) -> str:
         path = self.user_data_dir
         if self.opinion:
             path = os.path.join(path, "Logs")
+            self._optionally_create_directory(path)
         return path
 
     @property

src/pip/_vendor/platformdirs/windows.py

@@ -4,7 +4,7 @@ distlib==0.3.6
 distro==1.8.0
 msgpack==1.0.5
 packaging==21.3
-platformdirs==2.6.2
+platformdirs==3.2.0
 pyparsing==3.0.9
 pyproject-hooks==1.0.0
 requests==2.28.2