diff --git a/news/platformdirs.vendor.rst b/news/platformdirs.vendor.rst new file mode 100644 index 00000000000..dc3cff6f551 --- /dev/null +++ b/news/platformdirs.vendor.rst @@ -0,0 +1 @@ +Upgrade platformdirs to 4.9.4 diff --git a/src/pip/_vendor/platformdirs/__init__.py b/src/pip/_vendor/platformdirs/__init__.py index 2325ec2eb6f..23a09507b41 100644 --- a/src/pip/_vendor/platformdirs/__init__.py +++ b/src/pip/_vendor/platformdirs/__init__.py @@ -1,5 +1,7 @@ -""" -Utilities for determining application-specific dirs. +"""Utilities for determining application-specific dirs. + +Provides convenience functions (e.g. :func:`user_data_dir`, :func:`user_config_path`), a :data:`PlatformDirs` class that +auto-detects the current platform, and the :class:`~platformdirs.api.PlatformDirsABC` base class. See for details and usage. @@ -50,20 +52,23 @@ def _set_platform_dir_class() -> type[PlatformDirsABC]: AppDirs = PlatformDirs #: Backwards compatibility with appdirs -def user_data_dir( +def user_data_dir( # noqa: PLR0913, PLR0917 appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 + use_site_for_root: bool = False, # noqa: FBT001, FBT002 ) -> str: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param roaming: See `roaming `. :param ensure_exists: See `ensure_exists `. + :param use_site_for_root: See `use_site_for_root `. + :returns: data directory tied to the user + """ return PlatformDirs( appname=appname, @@ -71,6 +76,7 @@ def user_data_dir( version=version, roaming=roaming, ensure_exists=ensure_exists, + use_site_for_root=use_site_for_root, ).user_data_dir @@ -81,13 +87,14 @@ def site_data_dir( multipath: bool = False, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 ) -> str: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. - :param multipath: See `roaming `. + :param multipath: See `multipath `. :param ensure_exists: See `ensure_exists `. + :returns: data directory shared by users + """ return PlatformDirs( appname=appname, @@ -98,20 +105,23 @@ def site_data_dir( ).site_data_dir -def user_config_dir( +def user_config_dir( # noqa: PLR0913, PLR0917 appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 + use_site_for_root: bool = False, # noqa: FBT001, FBT002 ) -> str: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param roaming: See `roaming `. :param ensure_exists: See `ensure_exists `. + :param use_site_for_root: See `use_site_for_root `. + :returns: config directory tied to the user + """ return PlatformDirs( appname=appname, @@ -119,6 +129,7 @@ def user_config_dir( version=version, roaming=roaming, ensure_exists=ensure_exists, + use_site_for_root=use_site_for_root, ).user_config_dir @@ -129,13 +140,14 @@ def site_config_dir( multipath: bool = False, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 ) -> str: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. - :param multipath: See `roaming `. + :param multipath: See `multipath `. :param ensure_exists: See `ensure_exists `. - :returns: config directory shared by the users + + :returns: config directory shared by users + """ return PlatformDirs( appname=appname, @@ -146,20 +158,23 @@ def site_config_dir( ).site_config_dir -def user_cache_dir( +def user_cache_dir( # noqa: PLR0913, PLR0917 appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, opinion: bool = True, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 + use_site_for_root: bool = False, # noqa: FBT001, FBT002 ) -> str: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. - :param opinion: See `roaming `. + :param opinion: See `opinion `. :param ensure_exists: See `ensure_exists `. + :param use_site_for_root: See `use_site_for_root `. + :returns: cache directory tied to the user + """ return PlatformDirs( appname=appname, @@ -167,6 +182,7 @@ def user_cache_dir( version=version, opinion=opinion, ensure_exists=ensure_exists, + use_site_for_root=use_site_for_root, ).user_cache_dir @@ -177,13 +193,14 @@ def site_cache_dir( opinion: bool = True, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 ) -> str: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param opinion: See `opinion `. :param ensure_exists: See `ensure_exists `. - :returns: cache directory tied to the user + + :returns: cache directory shared by users + """ return PlatformDirs( appname=appname, @@ -194,20 +211,23 @@ def site_cache_dir( ).site_cache_dir -def user_state_dir( +def user_state_dir( # noqa: PLR0913, PLR0917 appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 + use_site_for_root: bool = False, # noqa: FBT001, FBT002 ) -> str: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param roaming: See `roaming `. :param ensure_exists: See `ensure_exists `. + :param use_site_for_root: See `use_site_for_root `. + :returns: state directory tied to the user + """ return PlatformDirs( appname=appname, @@ -215,23 +235,49 @@ def user_state_dir( version=version, roaming=roaming, ensure_exists=ensure_exists, + use_site_for_root=use_site_for_root, ).user_state_dir -def user_log_dir( +def site_state_dir( appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, - opinion: bool = True, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 ) -> str: + """:param appname: See `appname `. + :param appauthor: See `appauthor `. + :param version: See `version `. + :param ensure_exists: See `ensure_exists `. + + :returns: state directory shared by users + """ - :param appname: See `appname `. + return PlatformDirs( + appname=appname, + appauthor=appauthor, + version=version, + ensure_exists=ensure_exists, + ).site_state_dir + + +def user_log_dir( # noqa: PLR0913, PLR0917 + appname: str | None = None, + appauthor: str | Literal[False] | None = None, + version: str | None = None, + opinion: bool = True, # noqa: FBT001, FBT002 + ensure_exists: bool = False, # noqa: FBT001, FBT002 + use_site_for_root: bool = False, # noqa: FBT001, FBT002 +) -> str: + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. - :param opinion: See `roaming `. + :param opinion: See `opinion `. :param ensure_exists: See `ensure_exists `. + :param use_site_for_root: See `use_site_for_root `. + :returns: log directory tied to the user + """ return PlatformDirs( appname=appname, @@ -239,9 +285,35 @@ def user_log_dir( version=version, opinion=opinion, ensure_exists=ensure_exists, + use_site_for_root=use_site_for_root, ).user_log_dir +def site_log_dir( + appname: str | None = None, + appauthor: str | Literal[False] | None = None, + version: str | None = None, + opinion: bool = True, # noqa: FBT001, FBT002 + ensure_exists: bool = False, # noqa: FBT001, FBT002 +) -> str: + """:param appname: See `appname `. + :param appauthor: See `appauthor `. + :param version: See `version `. + :param opinion: See `opinion `. + :param ensure_exists: See `ensure_exists `. + + :returns: log directory shared by users + + """ + return PlatformDirs( + appname=appname, + appauthor=appauthor, + version=version, + opinion=opinion, + ensure_exists=ensure_exists, + ).site_log_dir + + def user_documents_dir() -> str: """:returns: documents directory tied to the user""" return PlatformDirs().user_documents_dir @@ -272,20 +344,54 @@ def user_desktop_dir() -> str: return PlatformDirs().user_desktop_dir -def user_runtime_dir( +def user_bin_dir() -> str: + """:returns: bin directory tied to the user""" + return PlatformDirs().user_bin_dir + + +def site_bin_dir() -> str: + """:returns: bin directory shared by users""" + return PlatformDirs().site_bin_dir + + +def user_applications_dir() -> str: + """:returns: applications directory tied to the user""" + return PlatformDirs().user_applications_dir + + +def site_applications_dir( + multipath: bool = False, # noqa: FBT001, FBT002 + ensure_exists: bool = False, # noqa: FBT001, FBT002 +) -> str: + """:param multipath: See `multipath `. + :param ensure_exists: See `ensure_exists `. + + :returns: applications directory shared by users + + """ + return PlatformDirs( + multipath=multipath, + ensure_exists=ensure_exists, + ).site_applications_dir + + +def user_runtime_dir( # noqa: PLR0913, PLR0917 appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, opinion: bool = True, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 + use_site_for_root: bool = False, # noqa: FBT001, FBT002 ) -> str: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param opinion: See `opinion `. :param ensure_exists: See `ensure_exists `. + :param use_site_for_root: See `use_site_for_root `. + :returns: runtime directory tied to the user + """ return PlatformDirs( appname=appname, @@ -293,6 +399,7 @@ def user_runtime_dir( version=version, opinion=opinion, ensure_exists=ensure_exists, + use_site_for_root=use_site_for_root, ).user_runtime_dir @@ -303,13 +410,14 @@ def site_runtime_dir( opinion: bool = True, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 ) -> str: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param opinion: See `opinion `. :param ensure_exists: See `ensure_exists `. + :returns: runtime directory shared by users + """ return PlatformDirs( appname=appname, @@ -320,20 +428,23 @@ def site_runtime_dir( ).site_runtime_dir -def user_data_path( +def user_data_path( # noqa: PLR0913, PLR0917 appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 + use_site_for_root: bool = False, # noqa: FBT001, FBT002 ) -> Path: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param roaming: See `roaming `. :param ensure_exists: See `ensure_exists `. + :param use_site_for_root: See `use_site_for_root `. + :returns: data path tied to the user + """ return PlatformDirs( appname=appname, @@ -341,6 +452,7 @@ def user_data_path( version=version, roaming=roaming, ensure_exists=ensure_exists, + use_site_for_root=use_site_for_root, ).user_data_path @@ -351,13 +463,14 @@ def site_data_path( multipath: bool = False, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 ) -> Path: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param multipath: See `multipath `. :param ensure_exists: See `ensure_exists `. + :returns: data path shared by users + """ return PlatformDirs( appname=appname, @@ -368,20 +481,23 @@ def site_data_path( ).site_data_path -def user_config_path( +def user_config_path( # noqa: PLR0913, PLR0917 appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 + use_site_for_root: bool = False, # noqa: FBT001, FBT002 ) -> Path: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param roaming: See `roaming `. :param ensure_exists: See `ensure_exists `. + :param use_site_for_root: See `use_site_for_root `. + :returns: config path tied to the user + """ return PlatformDirs( appname=appname, @@ -389,6 +505,7 @@ def user_config_path( version=version, roaming=roaming, ensure_exists=ensure_exists, + use_site_for_root=use_site_for_root, ).user_config_path @@ -399,13 +516,14 @@ def site_config_path( multipath: bool = False, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 ) -> Path: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. - :param multipath: See `roaming `. + :param multipath: See `multipath `. :param ensure_exists: See `ensure_exists `. - :returns: config path shared by the users + + :returns: config path shared by users + """ return PlatformDirs( appname=appname, @@ -423,13 +541,14 @@ def site_cache_path( opinion: bool = True, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 ) -> Path: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param opinion: See `opinion `. :param ensure_exists: See `ensure_exists `. - :returns: cache directory tied to the user + + :returns: cache path shared by users + """ return PlatformDirs( appname=appname, @@ -440,20 +559,23 @@ def site_cache_path( ).site_cache_path -def user_cache_path( +def user_cache_path( # noqa: PLR0913, PLR0917 appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, opinion: bool = True, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 + use_site_for_root: bool = False, # noqa: FBT001, FBT002 ) -> Path: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. - :param opinion: See `roaming `. + :param opinion: See `opinion `. :param ensure_exists: See `ensure_exists `. + :param use_site_for_root: See `use_site_for_root `. + :returns: cache path tied to the user + """ return PlatformDirs( appname=appname, @@ -461,23 +583,27 @@ def user_cache_path( version=version, opinion=opinion, ensure_exists=ensure_exists, + use_site_for_root=use_site_for_root, ).user_cache_path -def user_state_path( +def user_state_path( # noqa: PLR0913, PLR0917 appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 + use_site_for_root: bool = False, # noqa: FBT001, FBT002 ) -> Path: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param roaming: See `roaming `. :param ensure_exists: See `ensure_exists `. + :param use_site_for_root: See `use_site_for_root `. + :returns: state path tied to the user + """ return PlatformDirs( appname=appname, @@ -485,23 +611,49 @@ def user_state_path( version=version, roaming=roaming, ensure_exists=ensure_exists, + use_site_for_root=use_site_for_root, ).user_state_path -def user_log_path( +def site_state_path( appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, - opinion: bool = True, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 ) -> Path: + """:param appname: See `appname `. + :param appauthor: See `appauthor `. + :param version: See `version `. + :param ensure_exists: See `ensure_exists `. + + :returns: state path shared by users + """ - :param appname: See `appname `. + return PlatformDirs( + appname=appname, + appauthor=appauthor, + version=version, + ensure_exists=ensure_exists, + ).site_state_path + + +def user_log_path( # noqa: PLR0913, PLR0917 + appname: str | None = None, + appauthor: str | Literal[False] | None = None, + version: str | None = None, + opinion: bool = True, # noqa: FBT001, FBT002 + ensure_exists: bool = False, # noqa: FBT001, FBT002 + use_site_for_root: bool = False, # noqa: FBT001, FBT002 +) -> Path: + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. - :param opinion: See `roaming `. + :param opinion: See `opinion `. :param ensure_exists: See `ensure_exists `. + :param use_site_for_root: See `use_site_for_root `. + :returns: log path tied to the user + """ return PlatformDirs( appname=appname, @@ -509,11 +661,37 @@ def user_log_path( version=version, opinion=opinion, ensure_exists=ensure_exists, + use_site_for_root=use_site_for_root, ).user_log_path +def site_log_path( + appname: str | None = None, + appauthor: str | Literal[False] | None = None, + version: str | None = None, + opinion: bool = True, # noqa: FBT001, FBT002 + ensure_exists: bool = False, # noqa: FBT001, FBT002 +) -> Path: + """:param appname: See `appname `. + :param appauthor: See `appauthor `. + :param version: See `version `. + :param opinion: See `opinion `. + :param ensure_exists: See `ensure_exists `. + + :returns: log path shared by users + + """ + return PlatformDirs( + appname=appname, + appauthor=appauthor, + version=version, + opinion=opinion, + ensure_exists=ensure_exists, + ).site_log_path + + def user_documents_path() -> Path: - """:returns: documents a path tied to the user""" + """:returns: documents path tied to the user""" return PlatformDirs().user_documents_path @@ -542,20 +720,54 @@ def user_desktop_path() -> Path: return PlatformDirs().user_desktop_path -def user_runtime_path( +def user_bin_path() -> Path: + """:returns: bin path tied to the user""" + return PlatformDirs().user_bin_path + + +def site_bin_path() -> Path: + """:returns: bin path shared by users""" + return PlatformDirs().site_bin_path + + +def user_applications_path() -> Path: + """:returns: applications path tied to the user""" + return PlatformDirs().user_applications_path + + +def site_applications_path( + multipath: bool = False, # noqa: FBT001, FBT002 + ensure_exists: bool = False, # noqa: FBT001, FBT002 +) -> Path: + """:param multipath: See `multipath `. + :param ensure_exists: See `ensure_exists `. + + :returns: applications path shared by users + + """ + return PlatformDirs( + multipath=multipath, + ensure_exists=ensure_exists, + ).site_applications_path + + +def user_runtime_path( # noqa: PLR0913, PLR0917 appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, opinion: bool = True, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 + use_site_for_root: bool = False, # noqa: FBT001, FBT002 ) -> Path: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param opinion: See `opinion `. :param ensure_exists: See `ensure_exists `. + :param use_site_for_root: See `use_site_for_root `. + :returns: runtime path tied to the user + """ return PlatformDirs( appname=appname, @@ -563,6 +775,7 @@ def user_runtime_path( version=version, opinion=opinion, ensure_exists=ensure_exists, + use_site_for_root=use_site_for_root, ).user_runtime_path @@ -573,13 +786,14 @@ def site_runtime_path( opinion: bool = True, # noqa: FBT001, FBT002 ensure_exists: bool = False, # noqa: FBT001, FBT002 ) -> Path: - """ - :param appname: See `appname `. + """:param appname: See `appname `. :param appauthor: See `appauthor `. :param version: See `version `. :param opinion: See `opinion `. :param ensure_exists: See `ensure_exists `. + :returns: runtime path shared by users + """ return PlatformDirs( appname=appname, @@ -596,14 +810,26 @@ def site_runtime_path( "PlatformDirsABC", "__version__", "__version_info__", + "site_applications_dir", + "site_applications_path", + "site_bin_dir", + "site_bin_path", "site_cache_dir", "site_cache_path", "site_config_dir", "site_config_path", "site_data_dir", "site_data_path", + "site_log_dir", + "site_log_path", "site_runtime_dir", "site_runtime_path", + "site_state_dir", + "site_state_path", + "user_applications_dir", + "user_applications_path", + "user_bin_dir", + "user_bin_path", "user_cache_dir", "user_cache_path", "user_config_dir", diff --git a/src/pip/_vendor/platformdirs/__main__.py b/src/pip/_vendor/platformdirs/__main__.py index fa8a677a336..58c12e0f644 100644 --- a/src/pip/_vendor/platformdirs/__main__.py +++ b/src/pip/_vendor/platformdirs/__main__.py @@ -15,10 +15,16 @@ "user_pictures_dir", "user_videos_dir", "user_music_dir", + "user_bin_dir", + "site_bin_dir", + "user_applications_dir", "user_runtime_dir", "site_data_dir", "site_config_dir", "site_cache_dir", + "site_state_dir", + "site_log_dir", + "site_applications_dir", "site_runtime_dir", ) diff --git a/src/pip/_vendor/platformdirs/_xdg.py b/src/pip/_vendor/platformdirs/_xdg.py new file mode 100644 index 00000000000..c4aadd6d031 --- /dev/null +++ b/src/pip/_vendor/platformdirs/_xdg.py @@ -0,0 +1,143 @@ +"""XDG environment variable mixin for Unix and macOS.""" + +from __future__ import annotations + +import os + +from .api import PlatformDirsABC + + +class XDGMixin(PlatformDirsABC): + """Mixin that checks XDG environment variables, falling back to platform-specific defaults via ``super()``.""" + + @property + def user_data_dir(self) -> str: + """:returns: data directory tied to the user, from ``$XDG_DATA_HOME`` if set, else platform default""" + if path := os.environ.get("XDG_DATA_HOME", "").strip(): + return self._append_app_name_and_version(path) + return super().user_data_dir + + @property + def _site_data_dirs(self) -> list[str]: + if xdg_dirs := os.environ.get("XDG_DATA_DIRS", "").strip(): + return [self._append_app_name_and_version(p) for p in xdg_dirs.split(os.pathsep) if p.strip()] + return super()._site_data_dirs # type: ignore[misc] + + @property + def site_data_dir(self) -> str: + """:returns: data directories shared by users, from ``$XDG_DATA_DIRS`` if set, else platform default""" + dirs = self._site_data_dirs + return os.pathsep.join(dirs) if self.multipath else dirs[0] + + @property + def user_config_dir(self) -> str: + """:returns: config directory tied to the user, from ``$XDG_CONFIG_HOME`` if set, else platform default""" + if path := os.environ.get("XDG_CONFIG_HOME", "").strip(): + return self._append_app_name_and_version(path) + return super().user_config_dir + + @property + def _site_config_dirs(self) -> list[str]: + if xdg_dirs := os.environ.get("XDG_CONFIG_DIRS", "").strip(): + return [self._append_app_name_and_version(p) for p in xdg_dirs.split(os.pathsep) if p.strip()] + return super()._site_config_dirs # type: ignore[misc] + + @property + def site_config_dir(self) -> str: + """:returns: config directories shared by users, from ``$XDG_CONFIG_DIRS`` if set, else platform default""" + dirs = self._site_config_dirs + return os.pathsep.join(dirs) if self.multipath else dirs[0] + + @property + def user_cache_dir(self) -> str: + """:returns: cache directory tied to the user, from ``$XDG_CACHE_HOME`` if set, else platform default""" + if path := os.environ.get("XDG_CACHE_HOME", "").strip(): + return self._append_app_name_and_version(path) + return super().user_cache_dir + + @property + def user_state_dir(self) -> str: + """:returns: state directory tied to the user, from ``$XDG_STATE_HOME`` if set, else platform default""" + if path := os.environ.get("XDG_STATE_HOME", "").strip(): + return self._append_app_name_and_version(path) + return super().user_state_dir + + @property + def user_runtime_dir(self) -> str: + """:returns: runtime directory tied to the user, from ``$XDG_RUNTIME_DIR`` if set, else platform default""" + if path := os.environ.get("XDG_RUNTIME_DIR", "").strip(): + return self._append_app_name_and_version(path) + return super().user_runtime_dir + + @property + def site_runtime_dir(self) -> str: + """:returns: runtime directory shared by users, from ``$XDG_RUNTIME_DIR`` if set, else platform default""" + if path := os.environ.get("XDG_RUNTIME_DIR", "").strip(): + return self._append_app_name_and_version(path) + return super().site_runtime_dir + + @property + def user_documents_dir(self) -> str: + """:returns: documents directory tied to the user, from ``$XDG_DOCUMENTS_DIR`` if set, else platform default""" + if path := os.environ.get("XDG_DOCUMENTS_DIR", "").strip(): + return os.path.expanduser(path) # noqa: PTH111 + return super().user_documents_dir + + @property + def user_downloads_dir(self) -> str: + """:returns: downloads directory tied to the user, from ``$XDG_DOWNLOAD_DIR`` if set, else platform default""" + if path := os.environ.get("XDG_DOWNLOAD_DIR", "").strip(): + return os.path.expanduser(path) # noqa: PTH111 + return super().user_downloads_dir + + @property + def user_pictures_dir(self) -> str: + """:returns: pictures directory tied to the user, from ``$XDG_PICTURES_DIR`` if set, else platform default""" + if path := os.environ.get("XDG_PICTURES_DIR", "").strip(): + return os.path.expanduser(path) # noqa: PTH111 + return super().user_pictures_dir + + @property + def user_videos_dir(self) -> str: + """:returns: videos directory tied to the user, from ``$XDG_VIDEOS_DIR`` if set, else platform default""" + if path := os.environ.get("XDG_VIDEOS_DIR", "").strip(): + return os.path.expanduser(path) # noqa: PTH111 + return super().user_videos_dir + + @property + def user_music_dir(self) -> str: + """:returns: music directory tied to the user, from ``$XDG_MUSIC_DIR`` if set, else platform default""" + if path := os.environ.get("XDG_MUSIC_DIR", "").strip(): + return os.path.expanduser(path) # noqa: PTH111 + return super().user_music_dir + + @property + def user_desktop_dir(self) -> str: + """:returns: desktop directory tied to the user, from ``$XDG_DESKTOP_DIR`` if set, else platform default""" + if path := os.environ.get("XDG_DESKTOP_DIR", "").strip(): + return os.path.expanduser(path) # noqa: PTH111 + return super().user_desktop_dir + + @property + def user_applications_dir(self) -> str: + """:returns: applications directory tied to the user, from ``$XDG_DATA_HOME`` if set, else platform default""" + if path := os.environ.get("XDG_DATA_HOME", "").strip(): + return os.path.join(os.path.expanduser(path), "applications") # noqa: PTH111, PTH118 + return super().user_applications_dir + + @property + def _site_applications_dirs(self) -> list[str]: + if xdg_dirs := os.environ.get("XDG_DATA_DIRS", "").strip(): + return [os.path.join(p, "applications") for p in xdg_dirs.split(os.pathsep) if p.strip()] # noqa: PTH118 + return super()._site_applications_dirs # type: ignore[misc] + + @property + def site_applications_dir(self) -> str: + """:returns: applications directories shared by users, from ``$XDG_DATA_DIRS`` if set, else platform default""" + dirs = self._site_applications_dirs + return os.pathsep.join(dirs) if self.multipath else dirs[0] + + +__all__ = [ + "XDGMixin", +] diff --git a/src/pip/_vendor/platformdirs/android.py b/src/pip/_vendor/platformdirs/android.py index 92efc852d38..8c798b95e31 100644 --- a/src/pip/_vendor/platformdirs/android.py +++ b/src/pip/_vendor/platformdirs/android.py @@ -11,114 +11,140 @@ from .api import PlatformDirsABC -class Android(PlatformDirsABC): - """ - Follows the guidance `from here `_. +class Android(PlatformDirsABC): # noqa: PLR0904 + """Platform directories for Android. + + Follows the guidance `from here `_. Directories are typically located + under the app's private storage (``/data/user///``). Makes use of the `appname `, `version - `, `ensure_exists `. + `, `opinion `, `ensure_exists + `. """ @property def user_data_dir(self) -> str: - """:return: data directory tied to the user, e.g. ``/data/user///files/``""" + """:returns: data directory tied to the user, e.g. ``/data/user///files/``""" return self._append_app_name_and_version(cast("str", _android_folder()), "files") @property def site_data_dir(self) -> str: - """:return: data directory shared by users, same as `user_data_dir`""" + """:returns: data directory shared by users, same as `user_data_dir`""" return self.user_data_dir @property def user_config_dir(self) -> str: - """ - :return: config directory tied to the user, e.g. \ - ``/data/user///shared_prefs/`` - """ + """:returns: config directory tied to the user, e.g. ``/data/user///shared_prefs/``""" return self._append_app_name_and_version(cast("str", _android_folder()), "shared_prefs") @property def site_config_dir(self) -> str: - """:return: config directory shared by the users, same as `user_config_dir`""" + """:returns: config directory shared by users, same as `user_config_dir`""" return self.user_config_dir @property def user_cache_dir(self) -> str: - """:return: cache directory tied to the user, e.g.,``/data/user///cache/``""" + """:returns: cache directory tied to the user, e.g.,``/data/user///cache/``""" 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`""" + """:returns: 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`""" + """:returns: state directory tied to the user, same as `user_data_dir`""" return self.user_data_dir + @property + def site_state_dir(self) -> str: + """:returns: state directory shared by users, same as `user_state_dir`""" + return self.user_state_dir + @property def user_log_dir(self) -> str: - """ - :return: log directory tied to the user, same as `user_cache_dir` if not opinionated else ``log`` in it, - e.g. ``/data/user///cache//log`` - """ + """:returns: log directory tied to the user, same as `user_cache_dir` if not opinionated else ``log`` in it, e.g. ``/data/user///cache//log``""" path = self.user_cache_dir if self.opinion: path = os.path.join(path, "log") # noqa: PTH118 + self._optionally_create_directory(path) return path + @property + def site_log_dir(self) -> str: + """:returns: log directory shared by users, same as `user_log_dir`""" + return self.user_log_dir + @property def user_documents_dir(self) -> str: - """:return: documents directory tied to the user e.g. ``/storage/emulated/0/Documents``""" + """:returns: documents directory tied to the user e.g. ``/storage/emulated/0/Documents``""" return _android_documents_folder() @property def user_downloads_dir(self) -> str: - """:return: downloads directory tied to the user e.g. ``/storage/emulated/0/Downloads``""" + """:returns: downloads directory tied to the user e.g. ``/storage/emulated/0/Downloads``""" return _android_downloads_folder() @property def user_pictures_dir(self) -> str: - """:return: pictures directory tied to the user e.g. ``/storage/emulated/0/Pictures``""" + """:returns: pictures directory tied to the user e.g. ``/storage/emulated/0/Pictures``""" return _android_pictures_folder() @property def user_videos_dir(self) -> str: - """:return: videos directory tied to the user e.g. ``/storage/emulated/0/DCIM/Camera``""" + """:returns: videos directory tied to the user e.g. ``/storage/emulated/0/DCIM/Camera``""" return _android_videos_folder() @property def user_music_dir(self) -> str: - """:return: music directory tied to the user e.g. ``/storage/emulated/0/Music``""" + """:returns: 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``""" + """:returns: desktop directory tied to the user e.g. ``/storage/emulated/0/Desktop``""" return "/storage/emulated/0/Desktop" + @property + def user_bin_dir(self) -> str: + """:returns: bin directory tied to the user, e.g. ``/data/user///files/bin``""" + return os.path.join(cast("str", _android_folder()), "files", "bin") # noqa: PTH118 + + @property + def site_bin_dir(self) -> str: + """:returns: bin directory shared by users, same as `user_bin_dir`""" + return self.user_bin_dir + + @property + def user_applications_dir(self) -> str: + """:returns: applications directory tied to the user, same as `user_data_dir`""" + return self.user_data_dir + + @property + def site_applications_dir(self) -> str: + """:returns: applications directory shared by users, same as `user_applications_dir`""" + return self.user_applications_dir + @property def user_runtime_dir(self) -> str: - """ - :return: runtime directory tied to the user, same as `user_cache_dir` if not opinionated else ``tmp`` in it, - e.g. ``/data/user///cache//tmp`` - """ + """:returns: runtime directory tied to the user, same as `user_cache_dir` if not opinionated else ``tmp`` in it, e.g. ``/data/user///cache//tmp``""" path = self.user_cache_dir if self.opinion: path = os.path.join(path, "tmp") # noqa: PTH118 + self._optionally_create_directory(path) return path @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 @lru_cache(maxsize=1) def _android_folder() -> str | None: # noqa: C901 - """:return: base folder for the Android OS or None if it cannot be found""" + """:returns: base folder for the Android OS or None if it cannot be found""" result: str | None = None # type checker isn't happy with our "import android", just don't do this when type checking see # https://stackoverflow.com/a/61394121 @@ -135,7 +161,7 @@ def _android_folder() -> str | None: # noqa: C901 try: # ...and fall back to using plain pyjnius, if python4android isn't available or doesn't deliver any useful # result... - from jnius import autoclass # noqa: PLC0415 + from jnius import autoclass # noqa: PLC0415 # ty: ignore[unresolved-import] context = autoclass("android.content.Context") result = context.getFilesDir().getParentFile().getAbsolutePath() @@ -166,10 +192,10 @@ def _android_folder() -> str | None: # noqa: C901 @lru_cache(maxsize=1) def _android_documents_folder() -> str: - """:return: documents folder for the Android OS""" + """:returns: documents folder for the Android OS""" # Get directories with pyjnius try: - from jnius import autoclass # noqa: PLC0415 + from jnius import autoclass # noqa: PLC0415 # ty: ignore[unresolved-import] context = autoclass("android.content.Context") environment = autoclass("android.os.Environment") @@ -182,10 +208,10 @@ def _android_documents_folder() -> str: @lru_cache(maxsize=1) def _android_downloads_folder() -> str: - """:return: downloads folder for the Android OS""" + """:returns: downloads folder for the Android OS""" # Get directories with pyjnius try: - from jnius import autoclass # noqa: PLC0415 + from jnius import autoclass # noqa: PLC0415 # ty: ignore[unresolved-import] context = autoclass("android.content.Context") environment = autoclass("android.os.Environment") @@ -198,10 +224,10 @@ def _android_downloads_folder() -> str: @lru_cache(maxsize=1) def _android_pictures_folder() -> str: - """:return: pictures folder for the Android OS""" + """:returns: pictures folder for the Android OS""" # Get directories with pyjnius try: - from jnius import autoclass # noqa: PLC0415 + from jnius import autoclass # noqa: PLC0415 # ty: ignore[unresolved-import] context = autoclass("android.content.Context") environment = autoclass("android.os.Environment") @@ -214,10 +240,10 @@ def _android_pictures_folder() -> str: @lru_cache(maxsize=1) def _android_videos_folder() -> str: - """:return: videos folder for the Android OS""" + """:returns: videos folder for the Android OS""" # Get directories with pyjnius try: - from jnius import autoclass # noqa: PLC0415 + from jnius import autoclass # noqa: PLC0415 # ty: ignore[unresolved-import] context = autoclass("android.content.Context") environment = autoclass("android.os.Environment") @@ -230,10 +256,10 @@ def _android_videos_folder() -> str: @lru_cache(maxsize=1) def _android_music_folder() -> str: - """:return: music folder for the Android OS""" + """:returns: music folder for the Android OS""" # Get directories with pyjnius try: - from jnius import autoclass # noqa: PLC0415 + from jnius import autoclass # noqa: PLC0415 # ty: ignore[unresolved-import] context = autoclass("android.content.Context") environment = autoclass("android.os.Environment") diff --git a/src/pip/_vendor/platformdirs/api.py b/src/pip/_vendor/platformdirs/api.py index 251600e6d1b..1ee29adb5be 100644 --- a/src/pip/_vendor/platformdirs/api.py +++ b/src/pip/_vendor/platformdirs/api.py @@ -13,7 +13,13 @@ 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 @@ def __init__( # noqa: PLR0913, PLR0917 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,57 @@ def __init__( # noqa: PLR0913, PLR0917 :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. """ 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 ``.``. """ 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 `_). + login (see `here `_). """ 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 +116,221 @@ def _first_item_as_path_if_multipath(self, directory: str) -> Path: @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 @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 @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_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 @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_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 +348,16 @@ def iter_cache_dirs(self) -> Iterator[str]: 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 +378,16 @@ def iter_cache_paths(self) -> Iterator[Path]: 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(): diff --git a/src/pip/_vendor/platformdirs/macos.py b/src/pip/_vendor/platformdirs/macos.py index 30ab3689130..249324672b0 100644 --- a/src/pip/_vendor/platformdirs/macos.py +++ b/src/pip/_vendor/platformdirs/macos.py @@ -6,77 +6,60 @@ 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 `_. - Makes use of the `appname `, - `version `, - `ensure_exists `. + Follows the guidance from `Apple's File System Programming Guide + `_. + 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``""" + """:returns: 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")) # 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 `_, the directory - will be under the Homebrew prefix, e.g. ``$homebrew_prefix/share/$appname/$version``. - If `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 _site_data_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 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 user_config_dir(self) -> str: - """:return: config directory tied to the user, same as `user_data_dir`""" + """:returns: 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, same as `site_data_dir`""" - return self.site_data_dir + def _site_config_dirs(self) -> list[str]: + return self._site_data_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 `_, the directory - will be under the Homebrew prefix, e.g. ``$homebrew_prefix/var/cache/$appname/$version``. - If `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 `_, the directory will be under the Homebrew prefix, e.g. ``$homebrew_prefix/var/cache/$appname/$version``. If `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 +70,117 @@ def site_cache_dir(self) -> str: @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`""" + """:returns: state directory tied to the user, same as `user_data_dir`""" return self.user_data_dir + @property + def site_state_dir(self) -> str: + """:returns: state directory shared by users, same as `site_data_dir`""" + return self.site_data_dir + @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_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 + `_. + Makes use of the `appname `, `version + `, `ensure_exists `. + + XDG environment variables (e.g. ``$XDG_DATA_HOME``) are supported and take precedence over macOS defaults. + + """ + __all__ = [ "MacOS", diff --git a/src/pip/_vendor/platformdirs/unix.py b/src/pip/_vendor/platformdirs/unix.py index fc75d8d0747..0638700c192 100644 --- a/src/pip/_vendor/platformdirs/unix.py +++ b/src/pip/_vendor/platformdirs/unix.py @@ -5,9 +5,12 @@ import os import sys from configparser import ConfigParser +from functools import cached_property from pathlib import Path +from tempfile import gettempdir from typing import TYPE_CHECKING, NoReturn +from ._xdg import XDGMixin from .api import PlatformDirsABC if TYPE_CHECKING: @@ -23,202 +26,175 @@ def getuid() -> NoReturn: from os import getuid -class Unix(PlatformDirsABC): # noqa: PLR0904 - """ - On Unix/Linux, we follow the `XDG Basedir Spec `_. +class _UnixDefaults(PlatformDirsABC): # noqa: PLR0904 + """Default directories for Unix/Linux without XDG environment variable overrides. - The spec allows overriding directories with environment variables. The examples shown are the default values, - alongside the name of the environment variable that overrides them. Makes use of the `appname - `, `version `, `multipath - `, `opinion `, `ensure_exists - `. + The XDG env var handling is in :class:`~platformdirs._xdg.XDGMixin`. """ + @cached_property + def _use_site(self) -> bool: + return self.use_site_for_root and getuid() == 0 + @property def user_data_dir(self) -> str: - """ - :return: data directory tied to the user, e.g. ``~/.local/share/$appname/$version`` or - ``$XDG_DATA_HOME/$appname/$version`` - """ - path = os.environ.get("XDG_DATA_HOME", "") - if not path.strip(): - path = os.path.expanduser("~/.local/share") # noqa: PTH111 - return self._append_app_name_and_version(path) + """:returns: data directory tied to the user, e.g. ``~/.local/share/$appname/$version`` or ``$XDG_DATA_HOME/$appname/$version``""" + return self._append_app_name_and_version(os.path.expanduser("~/.local/share")) # noqa: PTH111 @property def _site_data_dirs(self) -> list[str]: - path = os.environ.get("XDG_DATA_DIRS", "") - if not path.strip(): - path = f"/usr/local/share{os.pathsep}/usr/share" - return [self._append_app_name_and_version(p) for p in path.split(os.pathsep)] - - @property - def site_data_dir(self) -> str: - """ - :return: data directories shared by users (if `multipath ` is - enabled and ``XDG_DATA_DIRS`` is set and a multi path the response is also a multi path separated by the - OS path separator), e.g. ``/usr/local/share/$appname/$version`` or ``/usr/share/$appname/$version`` - """ - # XDG default for $XDG_DATA_DIRS; only first, if multipath is False - dirs = self._site_data_dirs - if not self.multipath: - return dirs[0] - return os.pathsep.join(dirs) + return [self._append_app_name_and_version("/usr/local/share"), self._append_app_name_and_version("/usr/share")] @property def user_config_dir(self) -> str: - """ - :return: config directory tied to the user, e.g. ``~/.config/$appname/$version`` or - ``$XDG_CONFIG_HOME/$appname/$version`` - """ - path = os.environ.get("XDG_CONFIG_HOME", "") - if not path.strip(): - path = os.path.expanduser("~/.config") # noqa: PTH111 - return self._append_app_name_and_version(path) + """:returns: config directory tied to the user, e.g. ``~/.config/$appname/$version`` or ``$XDG_CONFIG_HOME/$appname/$version``""" + return self._append_app_name_and_version(os.path.expanduser("~/.config")) # noqa: PTH111 @property def _site_config_dirs(self) -> list[str]: - path = os.environ.get("XDG_CONFIG_DIRS", "") - if not path.strip(): - path = "/etc/xdg" - return [self._append_app_name_and_version(p) for p in path.split(os.pathsep)] - - @property - def site_config_dir(self) -> str: - """ - :return: config directories shared by users (if `multipath ` - is enabled and ``XDG_CONFIG_DIRS`` is set and a multi path the response is also a multi path separated by - the OS path separator), e.g. ``/etc/xdg/$appname/$version`` - """ - # XDG default for $XDG_CONFIG_DIRS only first, if multipath is False - dirs = self._site_config_dirs - if not self.multipath: - return dirs[0] - return os.pathsep.join(dirs) + return [self._append_app_name_and_version("/etc/xdg")] @property def user_cache_dir(self) -> str: - """ - :return: cache directory tied to the user, e.g. ``~/.cache/$appname/$version`` or - ``~/$XDG_CACHE_HOME/$appname/$version`` - """ - path = os.environ.get("XDG_CACHE_HOME", "") - if not path.strip(): - path = os.path.expanduser("~/.cache") # noqa: PTH111 - return self._append_app_name_and_version(path) + """:returns: cache directory tied to the user, e.g. ``~/.cache/$appname/$version`` or ``$XDG_CACHE_HOME/$appname/$version``""" + return self._append_app_name_and_version(os.path.expanduser("~/.cache")) # noqa: PTH111 @property def site_cache_dir(self) -> str: - """:return: cache directory shared by users, e.g. ``/var/cache/$appname/$version``""" + """:returns: cache directory shared by users, e.g. ``/var/cache/$appname/$version``""" return self._append_app_name_and_version("/var/cache") @property def user_state_dir(self) -> str: - """ - :return: state directory tied to the user, e.g. ``~/.local/state/$appname/$version`` or - ``$XDG_STATE_HOME/$appname/$version`` - """ - path = os.environ.get("XDG_STATE_HOME", "") - if not path.strip(): - path = os.path.expanduser("~/.local/state") # noqa: PTH111 - return self._append_app_name_and_version(path) + """:returns: state directory tied to the user, e.g. ``~/.local/state/$appname/$version`` or ``$XDG_STATE_HOME/$appname/$version``""" + return self._append_app_name_and_version(os.path.expanduser("~/.local/state")) # noqa: PTH111 + + @property + def site_state_dir(self) -> str: + """:returns: state directory shared by users, e.g. ``/var/lib/$appname/$version``""" + return self._append_app_name_and_version("/var/lib") @property def user_log_dir(self) -> str: - """:return: log directory tied to the user, same as `user_state_dir` if not opinionated else ``log`` in it""" + """:returns: log directory tied to the user, same as `user_state_dir` if not opinionated else ``log`` in it""" path = self.user_state_dir if self.opinion: path = os.path.join(path, "log") # noqa: PTH118 self._optionally_create_directory(path) return path + @property + def site_log_dir(self) -> str: + """:returns: log directory shared by users, e.g. ``/var/log/$appname/$version`` + + Unlike `user_log_dir`, ``opinion`` has no effect since ``/var/log`` is inherently a log directory. + + """ + return self._append_app_name_and_version("/var/log") + @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 _get_user_media_dir("XDG_DOCUMENTS_DIR", "~/Documents") @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 _get_user_media_dir("XDG_DOWNLOAD_DIR", "~/Downloads") @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 _get_user_media_dir("XDG_PICTURES_DIR", "~/Pictures") @property def user_videos_dir(self) -> str: - """:return: videos directory tied to the user, e.g. ``~/Videos``""" + """:returns: videos directory tied to the user, e.g. ``~/Videos``""" return _get_user_media_dir("XDG_VIDEOS_DIR", "~/Videos") @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 _get_user_media_dir("XDG_MUSIC_DIR", "~/Music") @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 _get_user_media_dir("XDG_DESKTOP_DIR", "~/Desktop") + @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. ``~/.local/share/applications``""" + return os.path.join(os.path.expanduser("~/.local/share"), "applications") # noqa: PTH111, PTH118 + + @property + def _site_applications_dirs(self) -> list[str]: + return [os.path.join(p, "applications") for p in ["/usr/local/share", "/usr/share"]] # noqa: PTH118 + + @property + def site_applications_dir(self) -> str: + """:returns: applications directory shared by users, e.g. ``/usr/share/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. ``/run/user/$(id -u)/$appname/$version`` or - ``$XDG_RUNTIME_DIR/$appname/$version``. + """:returns: runtime directory tied to the user, e.g. ``$XDG_RUNTIME_DIR/$appname/$version``. + + If ``$XDG_RUNTIME_DIR`` is unset, tries the platform default (``/tmp/run/user/$(id -u)`` on OpenBSD, ``/var/run/user/$(id -u)`` on FreeBSD/NetBSD, ``/run/user/$(id -u)`` otherwise). If the default is not writable, falls back to a temporary directory. - For FreeBSD/OpenBSD/NetBSD, it would return ``/var/run/user/$(id -u)/$appname/$version`` if - exists, otherwise ``/tmp/runtime-$(id -u)/$appname/$version``, if``$XDG_RUNTIME_DIR`` - is not set. """ - path = os.environ.get("XDG_RUNTIME_DIR", "") - if not path.strip(): - if sys.platform.startswith(("freebsd", "openbsd", "netbsd")): - path = f"/var/run/user/{getuid()}" - if not Path(path).exists(): - path = f"/tmp/runtime-{getuid()}" # noqa: S108 - else: - path = f"/run/user/{getuid()}" + if sys.platform.startswith("openbsd"): + path = f"/tmp/run/user/{getuid()}" # noqa: S108 + elif sys.platform.startswith(("freebsd", "netbsd")): + path = f"/var/run/user/{getuid()}" + else: + path = f"/run/user/{getuid()}" + if not os.access(path, os.W_OK): + path = f"{gettempdir()}/runtime-{getuid()}" return self._append_app_name_and_version(path) @property def site_runtime_dir(self) -> str: - """ - :return: runtime directory shared by users, e.g. ``/run/$appname/$version`` or \ - ``$XDG_RUNTIME_DIR/$appname/$version``. + """:returns: runtime directory shared by users, e.g. ``/run/$appname/$version`` or ``$XDG_RUNTIME_DIR/$appname/$version``. - Note that this behaves almost exactly like `user_runtime_dir` if ``$XDG_RUNTIME_DIR`` is set, but will - fall back to paths associated to the root user instead of a regular logged-in user if it's not set. + Note that this behaves almost exactly like `user_runtime_dir` if ``$XDG_RUNTIME_DIR`` is set, but will fall back to paths associated to the root user instead of a regular logged-in user if it's not set. - If you wish to ensure that a logged-in root user path is returned e.g. ``/run/user/0``, use `user_runtime_dir` - instead. + If you wish to ensure that a logged-in root user path is returned e.g. ``/run/user/0``, use `user_runtime_dir` instead. For FreeBSD/OpenBSD/NetBSD, it would return ``/var/run/$appname/$version`` if ``$XDG_RUNTIME_DIR`` is not set. + """ - path = os.environ.get("XDG_RUNTIME_DIR", "") - if not path.strip(): - if sys.platform.startswith(("freebsd", "openbsd", "netbsd")): - path = "/var/run" - else: - path = "/run" + if sys.platform.startswith(("freebsd", "openbsd", "netbsd")): + path = "/var/run" + else: + path = "/run" return self._append_app_name_and_version(path) @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: - """:return: config path shared by the users, returns the first item, even if ``multipath`` is set to ``True``""" + """:returns: config path shared by users, returns the 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 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) def iter_config_dirs(self) -> Iterator[str]: @@ -232,36 +208,82 @@ def iter_data_dirs(self) -> Iterator[str]: yield from self._site_data_dirs -def _get_user_media_dir(env_var: str, fallback_tilde_path: str) -> str: - media_dir = _get_user_dirs_folder(env_var) - if media_dir is None: - media_dir = os.environ.get(env_var, "").strip() - if not media_dir: - media_dir = os.path.expanduser(fallback_tilde_path) # noqa: PTH111 +class Unix(XDGMixin, _UnixDefaults): + """On Unix/Linux, we follow the `XDG Basedir Spec `_. - return media_dir + The spec allows overriding directories with environment variables. The examples shown are the default values, + alongside the name of the environment variable that overrides them. Makes use of the `appname + `, `version `, `multipath + `, `opinion `, `ensure_exists + `. + + """ + + @property + def user_data_dir(self) -> str: + """:returns: data directory tied to the user, or site equivalent when root with ``use_site_for_root``""" + return self.site_data_dir if self._use_site else super().user_data_dir + + @property + def user_config_dir(self) -> str: + """:returns: config directory tied to the user, or site equivalent when root with ``use_site_for_root``""" + return self.site_config_dir if self._use_site else super().user_config_dir + + @property + def user_cache_dir(self) -> str: + """:returns: cache directory tied to the user, or site equivalent when root with ``use_site_for_root``""" + return self.site_cache_dir if self._use_site else super().user_cache_dir + + @property + def user_state_dir(self) -> str: + """:returns: state directory tied to the user, or site equivalent when root with ``use_site_for_root``""" + return self.site_state_dir if self._use_site else super().user_state_dir + + @property + def user_log_dir(self) -> str: + """:returns: log directory tied to the user, or site equivalent when root with ``use_site_for_root``""" + return self.site_log_dir if self._use_site else super().user_log_dir + + @property + def user_applications_dir(self) -> str: + """:returns: applications directory tied to the user, or site equivalent when root with ``use_site_for_root``""" + return self.site_applications_dir if self._use_site else super().user_applications_dir + + @property + def user_runtime_dir(self) -> str: + """:returns: runtime directory tied to the user, or site equivalent when root with ``use_site_for_root``""" + return self.site_runtime_dir if self._use_site else super().user_runtime_dir + + @property + def user_bin_dir(self) -> str: + """:returns: bin directory tied to the user, or site equivalent when root with ``use_site_for_root``""" + return self.site_bin_dir if self._use_site else super().user_bin_dir + + +def _get_user_media_dir(env_var: str, fallback_tilde_path: str) -> str: + if media_dir := _get_user_dirs_folder(env_var): + return media_dir + return os.path.expanduser(fallback_tilde_path) # noqa: PTH111 def _get_user_dirs_folder(key: str) -> str | None: - """ - Return directory from user-dirs.dirs config file. + """Return directory from user-dirs.dirs config file. See https://freedesktop.org/wiki/Software/xdg-user-dirs/. """ - user_dirs_config_path = Path(Unix().user_config_dir) / "user-dirs.dirs" + config_home = os.environ.get("XDG_CONFIG_HOME", "").strip() or os.path.expanduser("~/.config") # noqa: PTH111 + user_dirs_config_path = Path(config_home) / "user-dirs.dirs" if user_dirs_config_path.exists(): parser = ConfigParser() with user_dirs_config_path.open() as stream: - # Add fake section header, so ConfigParser doesn't complain parser.read_string(f"[top]\n{stream.read()}") if key not in parser["top"]: return None path = parser["top"][key].strip('"') - # Handle relative home paths return path.replace("$HOME", os.path.expanduser("~")) # noqa: PTH111 return None diff --git a/src/pip/_vendor/platformdirs/version.py b/src/pip/_vendor/platformdirs/version.py index fcf6f03a1cc..190c600dc60 100644 --- a/src/pip/_vendor/platformdirs/version.py +++ b/src/pip/_vendor/platformdirs/version.py @@ -28,7 +28,7 @@ commit_id: COMMIT_ID __commit_id__: COMMIT_ID -__version__ = version = '4.5.1' -__version_tuple__ = version_tuple = (4, 5, 1) +__version__ = version = '4.9.4' +__version_tuple__ = version_tuple = (4, 9, 4) __commit_id__ = commit_id = None diff --git a/src/pip/_vendor/platformdirs/windows.py b/src/pip/_vendor/platformdirs/windows.py index 8d523a9c665..47403dea5ef 100644 --- a/src/pip/_vendor/platformdirs/windows.py +++ b/src/pip/_vendor/platformdirs/windows.py @@ -4,18 +4,19 @@ import os import sys -from functools import lru_cache -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, Final from .api import PlatformDirsABC if TYPE_CHECKING: from collections.abc import Callable +# Not exposed by CPython; defined in the Windows SDK (shlobj_core.h) +_KF_FLAG_DONT_VERIFY: Final[int] = 0x00004000 -class Windows(PlatformDirsABC): - """ - `MSDN on where to store app data files `_. + +class Windows(PlatformDirsABC): # noqa: PLR0904 + """`MSDN on where to store app data files `_. Makes use of the `appname `, `appauthor `, `version `, `roaming @@ -26,11 +27,7 @@ class Windows(PlatformDirsABC): @property def user_data_dir(self) -> str: - """ - :return: data directory tied to the user, e.g. - ``%USERPROFILE%\\AppData\\Local\\$appauthor\\$appname`` (not roaming) or - ``%USERPROFILE%\\AppData\\Roaming\\$appauthor\\$appname`` (roaming) - """ + r""":returns: data directory tied to the user, e.g. ``%USERPROFILE%\AppData\Local\$appauthor\$appname`` (not roaming) or ``%USERPROFILE%\AppData\Roaming\$appauthor\$appname`` (roaming)""" const = "CSIDL_APPDATA" if self.roaming else "CSIDL_LOCAL_APPDATA" path = os.path.normpath(get_win_folder(const)) return self._append_parts(path) @@ -52,91 +49,119 @@ def _append_parts(self, path: str, *, opinion_value: str | None = None) -> str: @property def site_data_dir(self) -> str: - """:return: data directory shared by users, e.g. ``C:\\ProgramData\\$appauthor\\$appname``""" + r""":returns: data directory shared by users, e.g. ``C:\ProgramData\$appauthor\$appname``""" path = os.path.normpath(get_win_folder("CSIDL_COMMON_APPDATA")) return self._append_parts(path) @property def user_config_dir(self) -> str: - """:return: config directory tied to the user, same as `user_data_dir`""" + """:returns: 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, same as `site_data_dir`""" + """:returns: config directory shared by 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 (if opinionated with ``Cache`` folder within ``$appname``) e.g. - ``%USERPROFILE%\\AppData\\Local\\$appauthor\\$appname\\Cache\\$version`` - """ + r""":returns: cache directory tied to the user (if opinionated with ``Cache`` folder within ``$appname``) e.g. ``%USERPROFILE%\AppData\Local\$appauthor\$appname\Cache\$version``""" 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``""" + r""":returns: 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`""" + """:returns: state directory tied to the user, same as `user_data_dir`""" return self.user_data_dir + @property + def site_state_dir(self) -> str: + """:returns: state directory shared by users, same as `site_data_dir`""" + return self.site_data_dir + @property def user_log_dir(self) -> str: - """:return: log directory tied to the user, same as `user_data_dir` if not opinionated else ``Logs`` in it""" + """:returns: log directory tied to the user, same as `user_data_dir` if not opinionated else ``Logs`` in it""" path = self.user_data_dir if self.opinion: path = os.path.join(path, "Logs") # noqa: PTH118 self._optionally_create_directory(path) return path + @property + def site_log_dir(self) -> str: + """:returns: log directory shared by users, same as `site_data_dir` if not opinionated else ``Logs`` in it""" + path = self.site_data_dir + if self.opinion: + path = os.path.join(path, "Logs") # noqa: PTH118 + self._optionally_create_directory(path) + return path + @property def user_documents_dir(self) -> str: - """:return: documents directory tied to the user e.g. ``%USERPROFILE%\\Documents``""" + r""":returns: documents directory tied to the user e.g. ``%USERPROFILE%\Documents``""" return os.path.normpath(get_win_folder("CSIDL_PERSONAL")) @property def user_downloads_dir(self) -> str: - """:return: downloads directory tied to the user e.g. ``%USERPROFILE%\\Downloads``""" + r""":returns: downloads directory tied to the user e.g. ``%USERPROFILE%\Downloads``""" return os.path.normpath(get_win_folder("CSIDL_DOWNLOADS")) @property def user_pictures_dir(self) -> str: - """:return: pictures directory tied to the user e.g. ``%USERPROFILE%\\Pictures``""" + r""":returns: pictures directory tied to the user e.g. ``%USERPROFILE%\Pictures``""" return os.path.normpath(get_win_folder("CSIDL_MYPICTURES")) @property def user_videos_dir(self) -> str: - """:return: videos directory tied to the user e.g. ``%USERPROFILE%\\Videos``""" + r""":returns: videos directory tied to the user e.g. ``%USERPROFILE%\Videos``""" return os.path.normpath(get_win_folder("CSIDL_MYVIDEO")) @property def user_music_dir(self) -> str: - """:return: music directory tied to the user e.g. ``%USERPROFILE%\\Music``""" + r""":returns: music directory tied to the user e.g. ``%USERPROFILE%\Music``""" return os.path.normpath(get_win_folder("CSIDL_MYMUSIC")) @property def user_desktop_dir(self) -> str: - """:return: desktop directory tied to the user, e.g. ``%USERPROFILE%\\Desktop``""" + r""":returns: desktop directory tied to the user, e.g. ``%USERPROFILE%\Desktop``""" return os.path.normpath(get_win_folder("CSIDL_DESKTOPDIRECTORY")) + @property + def user_bin_dir(self) -> str: + r""":returns: bin directory tied to the user, e.g. ``%LOCALAPPDATA%\Programs``""" + return os.path.normpath(os.path.join(get_win_folder("CSIDL_LOCAL_APPDATA"), "Programs")) # noqa: PTH118 + + @property + def site_bin_dir(self) -> str: + """:returns: bin directory shared by users, e.g. ``C:\\ProgramData\bin``""" + return os.path.normpath(os.path.join(get_win_folder("CSIDL_COMMON_APPDATA"), "bin")) # noqa: PTH118 + + @property + def user_applications_dir(self) -> str: + r""":returns: applications directory tied to the user, e.g. ``Start Menu\Programs``""" + return os.path.normpath(get_win_folder("CSIDL_PROGRAMS")) + + @property + def site_applications_dir(self) -> str: + r""":returns: applications directory shared by users, e.g. ``C:\ProgramData\Microsoft\Windows\Start Menu\Programs``""" + return os.path.normpath(get_win_folder("CSIDL_COMMON_PROGRAMS")) + @property def user_runtime_dir(self) -> str: - """ - :return: runtime directory tied to the user, e.g. - ``%USERPROFILE%\\AppData\\Local\\Temp\\$appauthor\\$appname`` - """ + r""":returns: runtime directory tied to the user, e.g. ``%USERPROFILE%\AppData\Local\Temp\$appauthor\$appname``""" path = os.path.normpath(os.path.join(get_win_folder("CSIDL_LOCAL_APPDATA"), "Temp")) # noqa: PTH118 return self._append_parts(path) @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 @@ -161,7 +186,7 @@ def get_win_folder_from_env_vars(csidl_name: str) -> str: return result -def get_win_folder_if_csidl_name_not_env_var(csidl_name: str) -> str | None: +def get_win_folder_if_csidl_name_not_env_var(csidl_name: str) -> str | None: # noqa: PLR0911 """Get a folder for a CSIDL name that does not exist as an environment variable.""" if csidl_name == "CSIDL_PERSONAL": return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Documents") # noqa: PTH118 @@ -177,12 +202,29 @@ def get_win_folder_if_csidl_name_not_env_var(csidl_name: str) -> str | None: if csidl_name == "CSIDL_MYMUSIC": return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Music") # noqa: PTH118 + + if csidl_name == "CSIDL_PROGRAMS": + return os.path.join( # noqa: PTH118 + os.path.normpath(os.environ["APPDATA"]), + "Microsoft", + "Windows", + "Start Menu", + "Programs", + ) + + if csidl_name == "CSIDL_COMMON_PROGRAMS": + return os.path.join( # noqa: PTH118 + os.path.normpath(os.environ.get("PROGRAMDATA", os.environ.get("ALLUSERSPROFILE", "C:\\ProgramData"))), + "Microsoft", + "Windows", + "Start Menu", + "Programs", + ) return None def get_win_folder_from_registry(csidl_name: str) -> str: - """ - Get folder from the registry. + """Get folder from the registry. This is a fallback technique at best. I'm not sure if using the registry for these guarantees us the correct answer for all CSIDL_* names. @@ -190,6 +232,7 @@ def get_win_folder_from_registry(csidl_name: str) -> str: """ machine_names = { "CSIDL_COMMON_APPDATA", + "CSIDL_COMMON_PROGRAMS", } shell_folder_name = { "CSIDL_APPDATA": "AppData", @@ -200,6 +243,8 @@ def get_win_folder_from_registry(csidl_name: str) -> str: "CSIDL_MYPICTURES": "My Pictures", "CSIDL_MYVIDEO": "My Video", "CSIDL_MYMUSIC": "My Music", + "CSIDL_PROGRAMS": "Programs", + "CSIDL_COMMON_PROGRAMS": "Common Programs", }.get(csidl_name) if shell_folder_name is None: msg = f"Unknown CSIDL name: {csidl_name}" @@ -216,53 +261,86 @@ def get_win_folder_from_registry(csidl_name: str) -> str: return str(directory) +_KNOWN_FOLDER_GUIDS: dict[str, str] = { + "CSIDL_APPDATA": "{3EB685DB-65F9-4CF6-A03A-E3EF65729F3D}", + "CSIDL_COMMON_APPDATA": "{62AB5D82-FDC1-4DC3-A9DD-070D1D495D97}", + "CSIDL_LOCAL_APPDATA": "{F1B32785-6FBA-4FCF-9D55-7B8E7F157091}", + "CSIDL_PERSONAL": "{FDD39AD0-238F-46AF-ADB4-6C85480369C7}", + "CSIDL_MYPICTURES": "{33E28130-4E1E-4676-835A-98395C3BC3BB}", + "CSIDL_MYVIDEO": "{18989B1D-99B5-455B-841C-AB7C74E4DDFC}", + "CSIDL_MYMUSIC": "{4BD8D571-6D19-48D3-BE97-422220080E43}", + "CSIDL_DOWNLOADS": "{374DE290-123F-4565-9164-39C4925E467B}", + "CSIDL_DESKTOPDIRECTORY": "{B4BFCC3A-DB2C-424C-B029-7FE99A87C641}", + "CSIDL_PROGRAMS": "{A77F5D77-2E2B-44C3-A6A2-ABA601054A51}", + "CSIDL_COMMON_PROGRAMS": "{0139D44E-6AFE-49F2-8690-3DAFCAE6FFB8}", +} + + def get_win_folder_via_ctypes(csidl_name: str) -> str: - """Get folder with ctypes.""" - # There is no 'CSIDL_DOWNLOADS'. - # Use 'CSIDL_PROFILE' (40) and append the default folder 'Downloads' instead. - # https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid - - import ctypes # noqa: PLC0415 - - csidl_const = { - "CSIDL_APPDATA": 26, - "CSIDL_COMMON_APPDATA": 35, - "CSIDL_LOCAL_APPDATA": 28, - "CSIDL_PERSONAL": 5, - "CSIDL_MYPICTURES": 39, - "CSIDL_MYVIDEO": 14, - "CSIDL_MYMUSIC": 13, - "CSIDL_DOWNLOADS": 40, - "CSIDL_DESKTOPDIRECTORY": 16, - }.get(csidl_name) - if csidl_const is None: + """Get folder via :func:`SHGetKnownFolderPath`. + + See https://learn.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetknownfolderpath. + + """ + if sys.platform != "win32": # only needed for type checker to know that this code runs only on Windows + raise NotImplementedError + from ctypes import HRESULT, POINTER, Structure, WinDLL, byref, create_unicode_buffer, wintypes # noqa: PLC0415 + + class _GUID(Structure): + _fields_ = [ + ("Data1", wintypes.DWORD), + ("Data2", wintypes.WORD), + ("Data3", wintypes.WORD), + ("Data4", wintypes.BYTE * 8), + ] + + ole32 = WinDLL("ole32") + ole32.CLSIDFromString.restype = HRESULT + ole32.CLSIDFromString.argtypes = [wintypes.LPCOLESTR, POINTER(_GUID)] + ole32.CoTaskMemFree.restype = None + ole32.CoTaskMemFree.argtypes = [wintypes.LPVOID] + + shell32 = WinDLL("shell32") + shell32.SHGetKnownFolderPath.restype = HRESULT + shell32.SHGetKnownFolderPath.argtypes = [POINTER(_GUID), wintypes.DWORD, wintypes.HANDLE, POINTER(wintypes.LPWSTR)] + + kernel32 = WinDLL("kernel32") + kernel32.GetShortPathNameW.restype = wintypes.DWORD + kernel32.GetShortPathNameW.argtypes = [wintypes.LPWSTR, wintypes.LPWSTR, wintypes.DWORD] + + folder_guid = _KNOWN_FOLDER_GUIDS.get(csidl_name) + if folder_guid is None: msg = f"Unknown CSIDL name: {csidl_name}" raise ValueError(msg) - buf = ctypes.create_unicode_buffer(1024) - windll = getattr(ctypes, "windll") # noqa: B009 # using getattr to avoid false positive with mypy type checker - windll.shell32.SHGetFolderPathW(None, csidl_const, None, 0, buf) + guid = _GUID() + ole32.CLSIDFromString(folder_guid, byref(guid)) - # Downgrade to short path name if it has high-bit chars. - if any(ord(c) > 255 for c in buf): # noqa: PLR2004 - buf2 = ctypes.create_unicode_buffer(1024) - if windll.kernel32.GetShortPathNameW(buf.value, buf2, 1024): - buf = buf2 + path_ptr = wintypes.LPWSTR() + shell32.SHGetKnownFolderPath(byref(guid), _KF_FLAG_DONT_VERIFY, None, byref(path_ptr)) + result = path_ptr.value + ole32.CoTaskMemFree(path_ptr) - if csidl_name == "CSIDL_DOWNLOADS": - return os.path.join(buf.value, "Downloads") # noqa: PTH118 + if result is None: + msg = f"SHGetKnownFolderPath returned NULL for {csidl_name}" + raise ValueError(msg) + + if any(ord(c) > 255 for c in result): # noqa: PLR2004 + buf = create_unicode_buffer(1024) + if kernel32.GetShortPathNameW(result, buf, 1024): + result = buf.value - return buf.value + return result def _pick_get_win_folder() -> Callable[[str], str]: + """Select the best method to resolve Windows folder paths: ctypes, then registry, then environment variables.""" try: - import ctypes # noqa: PLC0415 + import ctypes # noqa: PLC0415, F401 except ImportError: pass else: - if hasattr(ctypes, "windll"): - return get_win_folder_via_ctypes + return get_win_folder_via_ctypes try: import winreg # noqa: PLC0415, F401 except ImportError: @@ -271,7 +349,20 @@ def _pick_get_win_folder() -> Callable[[str], str]: return get_win_folder_from_registry -get_win_folder = lru_cache(maxsize=None)(_pick_get_win_folder()) +_resolve_win_folder = _pick_get_win_folder() + + +def get_win_folder(csidl_name: str) -> str: + """Get a Windows folder path, checking for ``WIN_PD_OVERRIDE_*`` environment variable overrides first. + + For example, ``CSIDL_LOCAL_APPDATA`` can be overridden by setting ``WIN_PD_OVERRIDE_LOCAL_APPDATA``. + + """ + env_var = f"WIN_PD_OVERRIDE_{csidl_name.removeprefix('CSIDL_')}" + if override := os.environ.get(env_var, "").strip(): + return override + return _resolve_win_folder(csidl_name) + __all__ = [ "Windows", diff --git a/src/pip/_vendor/vendor.txt b/src/pip/_vendor/vendor.txt index dd2f5f34853..3e8cb9ea250 100644 --- a/src/pip/_vendor/vendor.txt +++ b/src/pip/_vendor/vendor.txt @@ -3,7 +3,7 @@ distlib==0.4.0 distro==1.9.0 msgpack==1.1.2 packaging==26.0 -platformdirs==4.5.1 +platformdirs==4.9.4 pyproject-hooks==1.2.0 requests==2.32.5 certifi==2026.1.4