venv/lib/python3.11/site-packages/pip/_vendor/platformdirs/__init__.py

   1 """
   2 Utilities for determining application-specific dirs. See <https://github.com/platformdirs/platformdirs> for details and
   3 usage.
   4 """
   5 from __future__ import annotations
   6
   7 import os
   8 import sys
   9 from typing import TYPE_CHECKING
  10
  11 from .api import PlatformDirsABC
  12 from .version import __version__
  13 from .version import __version_tuple__ as __version_info__
  14
  15 if TYPE_CHECKING:
  16     from pathlib import Path
  17
  18     if sys.version_info >= (3, 8):  # pragma: no cover (py38+)
  19         from typing import Literal
  20     else:  # pragma: no cover (py38+)
  21         from pip._vendor.typing_extensions import Literal
  22
  23
  24 def _set_platform_dir_class() -> type[PlatformDirsABC]:
  25     if sys.platform == "win32":
  26         from pip._vendor.platformdirs.windows import Windows as Result
  27     elif sys.platform == "darwin":
  28         from pip._vendor.platformdirs.macos import MacOS as Result
  29     else:
  30         from pip._vendor.platformdirs.unix import Unix as Result
  31
  32     if os.getenv("ANDROID_DATA") == "/data" and os.getenv("ANDROID_ROOT") == "/system":
  33         if os.getenv("SHELL") or os.getenv("PREFIX"):
  34             return Result
  35
  36         from pip._vendor.platformdirs.android import _android_folder
  37
  38         if _android_folder() is not None:
  39             from pip._vendor.platformdirs.android import Android
  40
  41             return Android  # return to avoid redefinition of result
  42
  43     return Result
  44
  45
  46 PlatformDirs = _set_platform_dir_class()  #: Currently active platform
  47 AppDirs = PlatformDirs  #: Backwards compatibility with appdirs
  48
  49
  50 def user_data_dir(
  51     appname: str | None = None,
  52     appauthor: str | None | Literal[False] = None,
  53     version: str | None = None,
  54     roaming: bool = False,  # noqa: FBT001, FBT002
  55     ensure_exists: bool = False,  # noqa: FBT001, FBT002
  56 ) -> str:
  57     """
  58     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
  59     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
  60     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
  61     :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
  62     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
  63     :returns: data directory tied to the user
  64     """
  65     return PlatformDirs(
  66         appname=appname,
  67         appauthor=appauthor,
  68         version=version,
  69         roaming=roaming,
  70         ensure_exists=ensure_exists,
  71     ).user_data_dir
  72
  73
  74 def site_data_dir(
  75     appname: str | None = None,
  76     appauthor: str | None | Literal[False] = None,
  77     version: str | None = None,
  78     multipath: bool = False,  # noqa: FBT001, FBT002
  79     ensure_exists: bool = False,  # noqa: FBT001, FBT002
  80 ) -> str:
  81     """
  82     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
  83     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
  84     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
  85     :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.
  86     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
  87     :returns: data directory shared by users
  88     """
  89     return PlatformDirs(
  90         appname=appname,
  91         appauthor=appauthor,
  92         version=version,
  93         multipath=multipath,
  94         ensure_exists=ensure_exists,
  95     ).site_data_dir
  96
  97
  98 def user_config_dir(
  99     appname: str | None = None,
 100     appauthor: str | None | Literal[False] = None,
 101     version: str | None = None,
 102     roaming: bool = False,  # noqa: FBT001, FBT002
 103     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 104 ) -> str:
 105     """
 106     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 107     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 108     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 109     :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
 110     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 111     :returns: config directory tied to the user
 112     """
 113     return PlatformDirs(
 114         appname=appname,
 115         appauthor=appauthor,
 116         version=version,
 117         roaming=roaming,
 118         ensure_exists=ensure_exists,
 119     ).user_config_dir
 120
 121
 122 def site_config_dir(
 123     appname: str | None = None,
 124     appauthor: str | None | Literal[False] = None,
 125     version: str | None = None,
 126     multipath: bool = False,  # noqa: FBT001, FBT002
 127     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 128 ) -> str:
 129     """
 130     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 131     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 132     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 133     :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.
 134     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 135     :returns: config directory shared by the users
 136     """
 137     return PlatformDirs(
 138         appname=appname,
 139         appauthor=appauthor,
 140         version=version,
 141         multipath=multipath,
 142         ensure_exists=ensure_exists,
 143     ).site_config_dir
 144
 145
 146 def user_cache_dir(
 147     appname: str | None = None,
 148     appauthor: str | None | Literal[False] = None,
 149     version: str | None = None,
 150     opinion: bool = True,  # noqa: FBT001, FBT002
 151     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 152 ) -> str:
 153     """
 154     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 155     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 156     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 157     :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
 158     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 159     :returns: cache directory tied to the user
 160     """
 161     return PlatformDirs(
 162         appname=appname,
 163         appauthor=appauthor,
 164         version=version,
 165         opinion=opinion,
 166         ensure_exists=ensure_exists,
 167     ).user_cache_dir
 168
 169
 170 def site_cache_dir(
 171     appname: str | None = None,
 172     appauthor: str | None | Literal[False] = None,
 173     version: str | None = None,
 174     opinion: bool = True,  # noqa: FBT001, FBT002
 175     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 176 ) -> str:
 177     """
 178     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 179     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 180     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 181     :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
 182     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 183     :returns: cache directory tied to the user
 184     """
 185     return PlatformDirs(
 186         appname=appname,
 187         appauthor=appauthor,
 188         version=version,
 189         opinion=opinion,
 190         ensure_exists=ensure_exists,
 191     ).site_cache_dir
 192
 193
 194 def user_state_dir(
 195     appname: str | None = None,
 196     appauthor: str | None | Literal[False] = None,
 197     version: str | None = None,
 198     roaming: bool = False,  # noqa: FBT001, FBT002
 199     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 200 ) -> str:
 201     """
 202     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 203     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 204     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 205     :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
 206     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 207     :returns: state directory tied to the user
 208     """
 209     return PlatformDirs(
 210         appname=appname,
 211         appauthor=appauthor,
 212         version=version,
 213         roaming=roaming,
 214         ensure_exists=ensure_exists,
 215     ).user_state_dir
 216
 217
 218 def user_log_dir(
 219     appname: str | None = None,
 220     appauthor: str | None | Literal[False] = None,
 221     version: str | None = None,
 222     opinion: bool = True,  # noqa: FBT001, FBT002
 223     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 224 ) -> str:
 225     """
 226     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 227     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 228     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 229     :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
 230     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 231     :returns: log directory tied to the user
 232     """
 233     return PlatformDirs(
 234         appname=appname,
 235         appauthor=appauthor,
 236         version=version,
 237         opinion=opinion,
 238         ensure_exists=ensure_exists,
 239     ).user_log_dir
 240
 241
 242 def user_documents_dir() -> str:
 243     """:returns: documents directory tied to the user"""
 244     return PlatformDirs().user_documents_dir
 245
 246
 247 def user_downloads_dir() -> str:
 248     """:returns: downloads directory tied to the user"""
 249     return PlatformDirs().user_downloads_dir
 250
 251
 252 def user_pictures_dir() -> str:
 253     """:returns: pictures directory tied to the user"""
 254     return PlatformDirs().user_pictures_dir
 255
 256
 257 def user_videos_dir() -> str:
 258     """:returns: videos directory tied to the user"""
 259     return PlatformDirs().user_videos_dir
 260
 261
 262 def user_music_dir() -> str:
 263     """:returns: music directory tied to the user"""
 264     return PlatformDirs().user_music_dir
 265
 266
 267 def user_runtime_dir(
 268     appname: str | None = None,
 269     appauthor: str | None | Literal[False] = None,
 270     version: str | None = None,
 271     opinion: bool = True,  # noqa: FBT001, FBT002
 272     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 273 ) -> str:
 274     """
 275     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 276     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 277     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 278     :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
 279     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 280     :returns: runtime directory tied to the user
 281     """
 282     return PlatformDirs(
 283         appname=appname,
 284         appauthor=appauthor,
 285         version=version,
 286         opinion=opinion,
 287         ensure_exists=ensure_exists,
 288     ).user_runtime_dir
 289
 290
 291 def user_data_path(
 292     appname: str | None = None,
 293     appauthor: str | None | Literal[False] = None,
 294     version: str | None = None,
 295     roaming: bool = False,  # noqa: FBT001, FBT002
 296     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 297 ) -> Path:
 298     """
 299     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 300     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 301     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 302     :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
 303     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 304     :returns: data path tied to the user
 305     """
 306     return PlatformDirs(
 307         appname=appname,
 308         appauthor=appauthor,
 309         version=version,
 310         roaming=roaming,
 311         ensure_exists=ensure_exists,
 312     ).user_data_path
 313
 314
 315 def site_data_path(
 316     appname: str | None = None,
 317     appauthor: str | None | Literal[False] = None,
 318     version: str | None = None,
 319     multipath: bool = False,  # noqa: FBT001, FBT002
 320     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 321 ) -> Path:
 322     """
 323     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 324     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 325     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 326     :param multipath: See `multipath <platformdirs.api.PlatformDirsABC.multipath>`.
 327     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 328     :returns: data path shared by users
 329     """
 330     return PlatformDirs(
 331         appname=appname,
 332         appauthor=appauthor,
 333         version=version,
 334         multipath=multipath,
 335         ensure_exists=ensure_exists,
 336     ).site_data_path
 337
 338
 339 def user_config_path(
 340     appname: str | None = None,
 341     appauthor: str | None | Literal[False] = None,
 342     version: str | None = None,
 343     roaming: bool = False,  # noqa: FBT001, FBT002
 344     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 345 ) -> Path:
 346     """
 347     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 348     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 349     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 350     :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
 351     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 352     :returns: config path tied to the user
 353     """
 354     return PlatformDirs(
 355         appname=appname,
 356         appauthor=appauthor,
 357         version=version,
 358         roaming=roaming,
 359         ensure_exists=ensure_exists,
 360     ).user_config_path
 361
 362
 363 def site_config_path(
 364     appname: str | None = None,
 365     appauthor: str | None | Literal[False] = None,
 366     version: str | None = None,
 367     multipath: bool = False,  # noqa: FBT001, FBT002
 368     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 369 ) -> Path:
 370     """
 371     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 372     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 373     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 374     :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.
 375     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 376     :returns: config path shared by the users
 377     """
 378     return PlatformDirs(
 379         appname=appname,
 380         appauthor=appauthor,
 381         version=version,
 382         multipath=multipath,
 383         ensure_exists=ensure_exists,
 384     ).site_config_path
 385
 386
 387 def site_cache_path(
 388     appname: str | None = None,
 389     appauthor: str | None | Literal[False] = None,
 390     version: str | None = None,
 391     opinion: bool = True,  # noqa: FBT001, FBT002
 392     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 393 ) -> Path:
 394     """
 395     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 396     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 397     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 398     :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
 399     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 400     :returns: cache directory tied to the user
 401     """
 402     return PlatformDirs(
 403         appname=appname,
 404         appauthor=appauthor,
 405         version=version,
 406         opinion=opinion,
 407         ensure_exists=ensure_exists,
 408     ).site_cache_path
 409
 410
 411 def user_cache_path(
 412     appname: str | None = None,
 413     appauthor: str | None | Literal[False] = None,
 414     version: str | None = None,
 415     opinion: bool = True,  # noqa: FBT001, FBT002
 416     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 417 ) -> Path:
 418     """
 419     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 420     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 421     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 422     :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
 423     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 424     :returns: cache path tied to the user
 425     """
 426     return PlatformDirs(
 427         appname=appname,
 428         appauthor=appauthor,
 429         version=version,
 430         opinion=opinion,
 431         ensure_exists=ensure_exists,
 432     ).user_cache_path
 433
 434
 435 def user_state_path(
 436     appname: str | None = None,
 437     appauthor: str | None | Literal[False] = None,
 438     version: str | None = None,
 439     roaming: bool = False,  # noqa: FBT001, FBT002
 440     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 441 ) -> Path:
 442     """
 443     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 444     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 445     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 446     :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
 447     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 448     :returns: state path tied to the user
 449     """
 450     return PlatformDirs(
 451         appname=appname,
 452         appauthor=appauthor,
 453         version=version,
 454         roaming=roaming,
 455         ensure_exists=ensure_exists,
 456     ).user_state_path
 457
 458
 459 def user_log_path(
 460     appname: str | None = None,
 461     appauthor: str | None | Literal[False] = None,
 462     version: str | None = None,
 463     opinion: bool = True,  # noqa: FBT001, FBT002
 464     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 465 ) -> Path:
 466     """
 467     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 468     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 469     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 470     :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
 471     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 472     :returns: log path tied to the user
 473     """
 474     return PlatformDirs(
 475         appname=appname,
 476         appauthor=appauthor,
 477         version=version,
 478         opinion=opinion,
 479         ensure_exists=ensure_exists,
 480     ).user_log_path
 481
 482
 483 def user_documents_path() -> Path:
 484     """:returns: documents path tied to the user"""
 485     return PlatformDirs().user_documents_path
 486
 487
 488 def user_downloads_path() -> Path:
 489     """:returns: downloads path tied to the user"""
 490     return PlatformDirs().user_downloads_path
 491
 492
 493 def user_pictures_path() -> Path:
 494     """:returns: pictures path tied to the user"""
 495     return PlatformDirs().user_pictures_path
 496
 497
 498 def user_videos_path() -> Path:
 499     """:returns: videos path tied to the user"""
 500     return PlatformDirs().user_videos_path
 501
 502
 503 def user_music_path() -> Path:
 504     """:returns: music path tied to the user"""
 505     return PlatformDirs().user_music_path
 506
 507
 508 def user_runtime_path(
 509     appname: str | None = None,
 510     appauthor: str | None | Literal[False] = None,
 511     version: str | None = None,
 512     opinion: bool = True,  # noqa: FBT001, FBT002
 513     ensure_exists: bool = False,  # noqa: FBT001, FBT002
 514 ) -> Path:
 515     """
 516     :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
 517     :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
 518     :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
 519     :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
 520     :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
 521     :returns: runtime path tied to the user
 522     """
 523     return PlatformDirs(
 524         appname=appname,
 525         appauthor=appauthor,
 526         version=version,
 527         opinion=opinion,
 528         ensure_exists=ensure_exists,
 529     ).user_runtime_path
 530
 531
 532 __all__ = [
 533     "__version__",
 534     "__version_info__",
 535     "PlatformDirs",
 536     "AppDirs",
 537     "PlatformDirsABC",
 538     "user_data_dir",
 539     "user_config_dir",
 540     "user_cache_dir",
 541     "user_state_dir",
 542     "user_log_dir",
 543     "user_documents_dir",
 544     "user_downloads_dir",
 545     "user_pictures_dir",
 546     "user_videos_dir",
 547     "user_music_dir",
 548     "user_runtime_dir",
 549     "site_data_dir",
 550     "site_config_dir",
 551     "site_cache_dir",
 552     "user_data_path",
 553     "user_config_path",
 554     "user_cache_path",
 555     "user_state_path",
 556     "user_log_path",
 557     "user_documents_path",
 558     "user_downloads_path",
 559     "user_pictures_path",
 560     "user_videos_path",
 561     "user_music_path",
 562     "user_runtime_path",
 563     "site_data_path",
 564     "site_config_path",
 565     "site_cache_path",
 566 ]