shortcutxl 0.3.76 → 0.3.78

package/xll/python/Lib/site-packages/pip/_vendor/platformdirs/macos.py

@@ -6,77 +6,71 @@ import os.path
 import sys
 from typing import TYPE_CHECKING
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+from ._xdg import XDGMixin
 from .api import PlatformDirsABC
 
 if TYPE_CHECKING:
     from pathlib import Path
 
 
-class MacOS(PlatformDirsABC):
-    """
-    Platform directories for the macOS operating system.
+class _MacOSDefaults(PlatformDirsABC):  # noqa: PLR0904
+    """Default platform directories for macOS without XDG environment variable overrides.
 
-    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>`.
+    Follows the guidance from `Apple's File System Programming Guide
+    <https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html>`_.
+    The XDG env var handling is in :class:`~platformdirs._xdg.XDGMixin`.
 
     """
 
-    @property
-    def user_data_dir(self) -> str:
-        """:return: data directory tied to the user, e.g. ``~/Library/Application Support/$appname/$version``"""
+    def _base_user_app_support_dir(self) -> str:
         return self._append_app_name_and_version(os.path.expanduser("~/Library/Application Support"))  # noqa: PTH111
 
-    @property
-    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. ``$homebrew_prefix/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.
-          ``$homebrew_prefix/share/$appname/$version:/Library/Application Support/$appname/$version``
-        """
+    def _base_site_dirs(self) -> list[str]:
         is_homebrew = "/opt/python" in sys.prefix
         homebrew_prefix = sys.prefix.split("/opt/python")[0] if is_homebrew else ""
         path_list = [self._append_app_name_and_version(f"{homebrew_prefix}/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]
+        return path_list
+
+    @property
+    def user_data_dir(self) -> str:
+        """:returns: data directory tied to the user, e.g. ``~/Library/Application Support/$appname/$version``"""
+        return self._base_user_app_support_dir()
+
+    @property
+    def _site_data_dirs(self) -> list[str]:
+        return self._base_site_dirs()
 
     @property
     def site_data_path(self) -> Path:
-        """:return: data path shared by users. Only return the first item, even if ``multipath`` is set to ``True``"""
+        """:returns: data path shared by users. Only return the first item, even if ``multipath`` is set to ``True``"""
         return self._first_item_as_path_if_multipath(self.site_data_dir)
 
+    @property
+    def site_config_path(self) -> Path:
+        """:returns: config path shared by users. Only return the first item, even if ``multipath`` is set to ``True``"""
+        return self._first_item_as_path_if_multipath(self.site_config_dir)
+
     @property
     def user_config_dir(self) -> str:
-        """:return: config directory tied to the user, same as `user_data_dir`"""
-        return self.user_data_dir
+        """:returns: config directory tied to the user, same as `user_data_dir`"""
+        return self._base_user_app_support_dir()
 
     @property
-    def site_config_dir(self) -> str:
-        """:return: config directory shared by the users, same as `site_data_dir`"""
-        return self.site_data_dir
+    def _site_config_dirs(self) -> list[str]:
+        return self._base_site_dirs()
 
     @property
     def user_cache_dir(self) -> str:
-        """:return: cache directory tied to the user, e.g. ``~/Library/Caches/$appname/$version``"""
+        """:returns: cache directory tied to the user, e.g. ``~/Library/Caches/$appname/$version``"""
         return self._append_app_name_and_version(os.path.expanduser("~/Library/Caches"))  # noqa: PTH111
 
     @property
     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. ``$homebrew_prefix/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.
-          ``$homebrew_prefix/var/cache/$appname/$version:/Library/Caches/$appname/$version``
-        """
+        """:returns: 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. ``$homebrew_prefix/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. ``$homebrew_prefix/var/cache/$appname/$version:/Library/Caches/$appname/$version``"""
         is_homebrew = "/opt/python" in sys.prefix
         homebrew_prefix = sys.prefix.split("/opt/python")[0] if is_homebrew else ""
         path_list = [self._append_app_name_and_version(f"{homebrew_prefix}/var/cache")] if is_homebrew else []
@@ -87,59 +81,142 @@ class MacOS(PlatformDirsABC):
 
     @property
     def site_cache_path(self) -> Path:
-        """:return: cache path shared by users. Only return the first item, even if ``multipath`` is set to ``True``"""
+        """:returns: cache path shared by users. Only return the first item, even if ``multipath`` is set to ``True``"""
         return self._first_item_as_path_if_multipath(self.site_cache_dir)
 
     @property
     def user_state_dir(self) -> str:
-        """:return: state directory tied to the user, same as `user_data_dir`"""
-        return self.user_data_dir
+        """:returns: state directory tied to the user, same as `user_data_dir`"""
+        return self._base_user_app_support_dir()
+
+    @property
+    def site_state_dir(self) -> str:
+        """:returns: state directory shared by users, same as `site_data_dir`"""
+        return self._base_site_dirs()[0]
 
     @property
     def user_log_dir(self) -> str:
-        """:return: log directory tied to the user, e.g. ``~/Library/Logs/$appname/$version``"""
+        """:returns: log directory tied to the user, e.g. ``~/Library/Logs/$appname/$version``"""
         return self._append_app_name_and_version(os.path.expanduser("~/Library/Logs"))  # noqa: PTH111
 
+    @property
+    def site_log_dir(self) -> str:
+        """:returns: log directory shared by users, e.g. ``/Library/Logs/$appname/$version``"""
+        return self._append_app_name_and_version("/Library/Logs")
+
     @property
     def user_documents_dir(self) -> str:
-        """:return: documents directory tied to the user, e.g. ``~/Documents``"""
+        """:returns: 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``"""
+        """:returns: 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``"""
+        """:returns: pictures directory tied to the user, e.g. ``~/Pictures``"""
         return os.path.expanduser("~/Pictures")  # noqa: PTH111
 
     @property
     def user_videos_dir(self) -> str:
-        """:return: videos directory tied to the user, e.g. ``~/Movies``"""
+        """:returns: videos directory tied to the user, e.g. ``~/Movies``"""
         return os.path.expanduser("~/Movies")  # noqa: PTH111
 
     @property
     def user_music_dir(self) -> str:
-        """:return: music directory tied to the user, e.g. ``~/Music``"""
+        """:returns: 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``"""
+        """:returns: desktop directory tied to the user, e.g. ``~/Desktop``"""
         return os.path.expanduser("~/Desktop")  # noqa: PTH111
 
+    @property
+    def user_projects_dir(self) -> str:
+        """:returns: projects directory tied to the user, e.g. ``~/Projects``"""
+        return os.path.expanduser("~/Projects")  # noqa: PTH111
+
+    @property
+    def user_publicshare_dir(self) -> str:
+        """:returns: public share directory tied to the user, e.g. ``~/Public``"""
+        return os.path.expanduser("~/Public")  # noqa: PTH111  # API returns str, not Path
+
+    @property
+    def user_templates_dir(self) -> str:
+        """:returns: templates directory tied to the user, e.g. ``~/Templates``"""
+        return os.path.expanduser("~/Templates")  # noqa: PTH111  # API returns str, not Path
+
+    @property
+    def user_fonts_dir(self) -> str:
+        """:returns: fonts directory tied to the user, e.g. ``~/Library/Fonts``"""
+        return os.path.expanduser("~/Library/Fonts")  # noqa: PTH111  # API returns str, not Path
+
+    @property
+    def user_preference_dir(self) -> str:
+        """:returns: preference directory tied to the user, e.g. ``~/Library/Preferences/AppName``"""
+        return self._append_app_name_and_version(os.path.expanduser("~/Library/Preferences"))  # noqa: PTH111  # API returns str, not Path
+
+    @property
+    def user_bin_dir(self) -> str:
+        """:returns: bin directory tied to the user, e.g. ``~/.local/bin``"""
+        return os.path.expanduser("~/.local/bin")  # noqa: PTH111
+
+    @property
+    def site_bin_dir(self) -> str:
+        """:returns: bin directory shared by users, e.g. ``/usr/local/bin``"""
+        return "/usr/local/bin"
+
+    @property
+    def user_applications_dir(self) -> str:
+        """:returns: applications directory tied to the user, e.g. ``~/Applications``"""
+        return os.path.expanduser("~/Applications")  # noqa: PTH111
+
+    @property
+    def _site_applications_dirs(self) -> list[str]:
+        return ["/Applications"]
+
+    @property
+    def site_applications_dir(self) -> str:
+        """:returns: applications directory shared by users, e.g. ``/Applications``"""
+        dirs = self._site_applications_dirs
+        return os.pathsep.join(dirs) if self.multipath else dirs[0]
+
     @property
     def user_runtime_dir(self) -> str:
-        """:return: runtime directory tied to the user, e.g. ``~/Library/Caches/TemporaryItems/$appname/$version``"""
+        """:returns: 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`"""
+        """:returns: runtime directory shared by users, same as `user_runtime_dir`"""
         return self.user_runtime_dir
 
+    def iter_config_dirs(self) -> Iterator[str]:
+        """:yield: all user and site configuration directories."""
+        yield self.user_config_dir
+        yield from self._site_config_dirs
+
+    def iter_data_dirs(self) -> Iterator[str]:
+        """:yield: all user and site data directories."""
+        yield self.user_data_dir
+        yield from self._site_data_dirs
+
+
+class MacOS(XDGMixin, _MacOSDefaults):
+    """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>`.
+
+    XDG environment variables (e.g. ``$XDG_DATA_HOME``) are supported and take precedence over macOS defaults.
+
+    """
+
 
 __all__ = [
     "MacOS",