shortcutxl 0.3.76 → 0.3.78

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

@@ -13,7 +13,13 @@ if TYPE_CHECKING:
 
 
 class PlatformDirsABC(ABC):  # noqa: PLR0904
-    """Abstract base class for platform directories."""
+    """Abstract base class defining all platform directory properties, their :class:`~pathlib.Path` variants, and iterators.
+
+    Platform-specific subclasses (e.g. :class:`~platformdirs.windows.Windows`, :class:`~platformdirs.macos.MacOS`,
+    :class:`~platformdirs.unix.Unix`) implement the abstract properties to return the appropriate paths for each
+    operating system.
+
+    """
 
     def __init__(  # noqa: PLR0913, PLR0917
         self,
@@ -24,9 +30,9 @@ class PlatformDirsABC(ABC):  # noqa: PLR0904
         multipath: bool = False,  # noqa: FBT001, FBT002
         opinion: bool = True,  # noqa: FBT001, FBT002
         ensure_exists: bool = False,  # noqa: FBT001, FBT002
+        use_site_for_root: bool = False,  # noqa: FBT001, FBT002
     ) -> None:
-        """
-        Create a new platform directory.
+        """Create a new platform directory.
 
         :param appname: See `appname`.
         :param appauthor: See `appauthor`.
@@ -35,48 +41,64 @@ class PlatformDirsABC(ABC):  # noqa: PLR0904
         :param multipath: See `multipath`.
         :param opinion: See `opinion`.
         :param ensure_exists: See `ensure_exists`.
+        :param use_site_for_root: See `use_site_for_root`.
 
         """
-        self.appname = appname  #: The name of application.
+        self.appname = appname  #: The name of the application.
         self.appauthor = appauthor
-        """
-        The name of the app author or distributing body for this application.
+        """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.
 
+        .. note::
+
+            On Windows, the directory structure is ``<base>/<appauthor>/<appname>``. When ``appauthor`` is ``None`` (the
+            default), it falls back to ``appname``, resulting in ``<base>/<appname>/<appname>`` (e.g.
+            ``AppData/Local/myapp/myapp``). Pass ``appauthor=False`` to omit the author directory entirely and get
+            ``<base>/<appname>``.
+
         """
         self.version = version
-        """
-        An optional version path element to append to the path.
+        """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.
+        """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>`_).
+        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. Only affects ``site_data_dir`` and ``site_config_dir`` on
+        Unix and macOS.
+
         """
-        An optional parameter which indicates that the entire list of data dirs should be returned.
+        self.opinion = opinion
+        """Whether to use opinionated values.
 
-        By default, the first item would only be returned.
+        When enabled, appends an additional subdirectory for certain directories: e.g. ``Cache`` for cache and ``Logs``
+        for logs on Windows, ``log`` for logs on Unix.
 
         """
-        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.
+        """Optionally create the directory (and any missing parents) upon access if it does not exist.
 
         By default, no directories are created.
 
         """
+        self.use_site_for_root = use_site_for_root
+        """Whether to redirect ``user_*_dir`` calls to their ``site_*_dir`` equivalents when running as root (uid 0).
+
+        Only has an effect on Unix. Disabled by default for backwards compatibility. When enabled, XDG user environment
+        variables (e.g. ``XDG_DATA_HOME``) are bypassed for the redirected directories.
+
+        """
 
     def _append_app_name_and_version(self, *base: str) -> str:
         params = list(base[1:])
@@ -101,161 +123,283 @@ class PlatformDirsABC(ABC):  # noqa: PLR0904
     @property
     @abstractmethod
     def user_data_dir(self) -> str:
-        """:return: data directory tied to the user"""
+        """:returns: data directory tied to the user"""
 
     @property
     @abstractmethod
     def site_data_dir(self) -> str:
-        """:return: data directory shared by users"""
+        """:returns: data directory shared by users"""
+
+    @property
+    def _site_data_dirs(self) -> list[str]:
+        raise NotImplementedError
 
     @property
     @abstractmethod
     def user_config_dir(self) -> str:
-        """:return: config directory tied to the user"""
+        """:returns: config directory tied to the user"""
 
     @property
     @abstractmethod
     def site_config_dir(self) -> str:
-        """:return: config directory shared by the users"""
+        """:returns: config directory shared by users"""
+
+    @property
+    def _site_config_dirs(self) -> list[str]:
+        raise NotImplementedError
 
     @property
     @abstractmethod
     def user_cache_dir(self) -> str:
-        """:return: cache directory tied to the user"""
+        """:returns: cache directory tied to the user"""
 
     @property
     @abstractmethod
     def site_cache_dir(self) -> str:
-        """:return: cache directory shared by users"""
+        """:returns: cache directory shared by users"""
 
     @property
     @abstractmethod
     def user_state_dir(self) -> str:
-        """:return: state directory tied to the user"""
+        """:returns: state directory tied to the user"""
+
+    @property
+    @abstractmethod
+    def site_state_dir(self) -> str:
+        """:returns: state directory shared by users"""
 
     @property
     @abstractmethod
     def user_log_dir(self) -> str:
-        """:return: log directory tied to the user"""
+        """:returns: log directory tied to the user"""
+
+    @property
+    @abstractmethod
+    def site_log_dir(self) -> str:
+        """:returns: log directory shared by users"""
 
     @property
     @abstractmethod
     def user_documents_dir(self) -> str:
-        """:return: documents directory tied to the user"""
+        """:returns: documents directory tied to the user"""
 
     @property
     @abstractmethod
     def user_downloads_dir(self) -> str:
-        """:return: downloads directory tied to the user"""
+        """:returns: downloads directory tied to the user"""
 
     @property
     @abstractmethod
     def user_pictures_dir(self) -> str:
-        """:return: pictures directory tied to the user"""
+        """:returns: pictures directory tied to the user"""
 
     @property
     @abstractmethod
     def user_videos_dir(self) -> str:
-        """:return: videos directory tied to the user"""
+        """:returns: videos directory tied to the user"""
 
     @property
     @abstractmethod
     def user_music_dir(self) -> str:
-        """:return: music directory tied to the user"""
+        """:returns: music directory tied to the user"""
 
     @property
     @abstractmethod
     def user_desktop_dir(self) -> str:
-        """:return: desktop directory tied to the user"""
+        """:returns: desktop directory tied to the user"""
+
+    @property
+    @abstractmethod
+    def user_projects_dir(self) -> str:
+        """:returns: projects directory tied to the user"""
+
+    @property
+    @abstractmethod
+    def user_publicshare_dir(self) -> str:
+        """:returns: public share directory tied to the user"""
+
+    @property
+    @abstractmethod
+    def user_templates_dir(self) -> str:
+        """:returns: templates directory tied to the user"""
+
+    @property
+    @abstractmethod
+    def user_fonts_dir(self) -> str:
+        """:returns: fonts directory tied to the user"""
+
+    @property
+    @abstractmethod
+    def user_preference_dir(self) -> str:
+        """:returns: preference directory tied to the user"""
+
+    @property
+    @abstractmethod
+    def user_bin_dir(self) -> str:
+        """:returns: bin directory tied to the user"""
+
+    @property
+    @abstractmethod
+    def site_bin_dir(self) -> str:
+        """:returns: bin directory shared by users"""
+
+    @property
+    @abstractmethod
+    def user_applications_dir(self) -> str:
+        """:returns: applications directory tied to the user"""
+
+    @property
+    @abstractmethod
+    def site_applications_dir(self) -> str:
+        """:returns: applications directory shared by users"""
+
+    @property
+    def _site_applications_dirs(self) -> list[str]:
+        raise NotImplementedError
 
     @property
     @abstractmethod
     def user_runtime_dir(self) -> str:
-        """:return: runtime directory tied to the user"""
+        """:returns: runtime directory tied to the user"""
 
     @property
     @abstractmethod
     def site_runtime_dir(self) -> str:
-        """:return: runtime directory shared by users"""
+        """:returns: runtime directory shared by users"""
 
     @property
     def user_data_path(self) -> Path:
-        """:return: data path tied to the user"""
+        """:returns: data path tied to the user"""
         return Path(self.user_data_dir)
 
     @property
     def site_data_path(self) -> Path:
-        """:return: data path shared by users"""
+        """:returns: data path shared by users"""
         return Path(self.site_data_dir)
 
     @property
     def user_config_path(self) -> Path:
-        """:return: config path tied to the user"""
+        """:returns: config path tied to the user"""
         return Path(self.user_config_dir)
 
     @property
     def site_config_path(self) -> Path:
-        """:return: config path shared by the users"""
+        """:returns: config path shared by users"""
         return Path(self.site_config_dir)
 
     @property
     def user_cache_path(self) -> Path:
-        """:return: cache path tied to the user"""
+        """:returns: 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"""
+        """:returns: 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"""
+        """:returns: state path tied to the user"""
         return Path(self.user_state_dir)
 
+    @property
+    def site_state_path(self) -> Path:
+        """:returns: state path shared by users"""
+        return Path(self.site_state_dir)
+
     @property
     def user_log_path(self) -> Path:
-        """:return: log path tied to the user"""
+        """:returns: log path tied to the user"""
         return Path(self.user_log_dir)
 
+    @property
+    def site_log_path(self) -> Path:
+        """:returns: log path shared by users"""
+        return Path(self.site_log_dir)
+
     @property
     def user_documents_path(self) -> Path:
-        """:return: documents a path tied to the user"""
+        """:returns: 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"""
+        """:returns: 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"""
+        """:returns: pictures path tied to the user"""
         return Path(self.user_pictures_dir)
 
     @property
     def user_videos_path(self) -> Path:
-        """:return: videos path tied to the user"""
+        """:returns: videos path tied to the user"""
         return Path(self.user_videos_dir)
 
     @property
     def user_music_path(self) -> Path:
-        """:return: music path tied to the user"""
+        """:returns: 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"""
+        """:returns: desktop path tied to the user"""
         return Path(self.user_desktop_dir)
 
+    @property
+    def user_projects_path(self) -> Path:
+        """:returns: projects path tied to the user"""
+        return Path(self.user_projects_dir)
+
+    @property
+    def user_publicshare_path(self) -> Path:
+        """:returns: public share path tied to the user"""
+        return Path(self.user_publicshare_dir)
+
+    @property
+    def user_templates_path(self) -> Path:
+        """:returns: templates path tied to the user"""
+        return Path(self.user_templates_dir)
+
+    @property
+    def user_fonts_path(self) -> Path:
+        """:returns: fonts path tied to the user"""
+        return Path(self.user_fonts_dir)
+
+    @property
+    def user_preference_path(self) -> Path:
+        """:returns: preference path tied to the user"""
+        return Path(self.user_preference_dir)
+
+    @property
+    def user_bin_path(self) -> Path:
+        """:returns: bin path tied to the user"""
+        return Path(self.user_bin_dir)
+
+    @property
+    def site_bin_path(self) -> Path:
+        """:returns: bin path shared by users"""
+        return Path(self.site_bin_dir)
+
+    @property
+    def user_applications_path(self) -> Path:
+        """:returns: applications path tied to the user"""
+        return Path(self.user_applications_dir)
+
+    @property
+    def site_applications_path(self) -> Path:
+        """:returns: applications path shared by users"""
+        return Path(self.site_applications_dir)
+
     @property
     def user_runtime_path(self) -> Path:
-        """:return: runtime path tied to the user"""
+        """:returns: 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"""
+        """:returns: runtime path shared by users"""
         return Path(self.site_runtime_dir)
 
     def iter_config_dirs(self) -> Iterator[str]:
@@ -273,6 +417,16 @@ class PlatformDirsABC(ABC):  # noqa: PLR0904
         yield self.user_cache_dir
         yield self.site_cache_dir
 
+    def iter_state_dirs(self) -> Iterator[str]:
+        """:yield: all user and site state directories."""
+        yield self.user_state_dir
+        yield self.site_state_dir
+
+    def iter_log_dirs(self) -> Iterator[str]:
+        """:yield: all user and site log directories."""
+        yield self.user_log_dir
+        yield self.site_log_dir
+
     def iter_runtime_dirs(self) -> Iterator[str]:
         """:yield: all user and site runtime directories."""
         yield self.user_runtime_dir
@@ -293,6 +447,16 @@ class PlatformDirsABC(ABC):  # noqa: PLR0904
         for path in self.iter_cache_dirs():
             yield Path(path)
 
+    def iter_state_paths(self) -> Iterator[Path]:
+        """:yield: all user and site state paths."""
+        for path in self.iter_state_dirs():
+            yield Path(path)
+
+    def iter_log_paths(self) -> Iterator[Path]:
+        """:yield: all user and site log paths."""
+        for path in self.iter_log_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():