venv/lib/python3.11/site-packages/pkg_resources/_vendor/platformdirs/api.py

   1 from __future__ import annotations
   2
   3 import os
   4 import sys
   5 from abc import ABC, abstractmethod
   6 from pathlib import Path
   7
   8 if sys.version_info >= (3, 8):  # pragma: no branch
   9     from typing import Literal  # pragma: no cover
  10
  11
  12 class PlatformDirsABC(ABC):
  13     """
  14     Abstract base class for platform directories.
  15     """
  16
  17     def __init__(
  18         self,
  19         appname: str | None = None,
  20         appauthor: str | None | Literal[False] = None,
  21         version: str | None = None,
  22         roaming: bool = False,
  23         multipath: bool = False,
  24         opinion: bool = True,
  25     ):
  26         """
  27         Create a new platform directory.
  28
  29         :param appname: See `appname`.
  30         :param appauthor: See `appauthor`.
  31         :param version: See `version`.
  32         :param roaming: See `roaming`.
  33         :param multipath: See `multipath`.
  34         :param opinion: See `opinion`.
  35         """
  36         self.appname = appname  #: The name of application.
  37         self.appauthor = appauthor
  38         """
  39         The name of the app author or distributing body for this application. Typically, it is the owning company name.
  40         Defaults to `appname`. You may pass ``False`` to disable it.
  41         """
  42         self.version = version
  43         """
  44         An optional version path element to append to the path. You might want to use this if you want multiple versions
  45         of your app to be able to run independently. If used, this would typically be ``<major>.<minor>``.
  46         """
  47         self.roaming = roaming
  48         """
  49         Whether to use the roaming appdata directory on Windows. That means that for users on a Windows network setup
  50         for roaming profiles, this user data will be synced on login (see
  51         `here <http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>`_).
  52         """
  53         self.multipath = multipath
  54         """
  55         An optional parameter only applicable to Unix/Linux which indicates that the entire list of data dirs should be
  56         returned. By default, the first item would only be returned.
  57         """
  58         self.opinion = opinion  #: A flag to indicating to use opinionated values.
  59
  60     def _append_app_name_and_version(self, *base: str) -> str:
  61         params = list(base[1:])
  62         if self.appname:
  63             params.append(self.appname)
  64             if self.version:
  65                 params.append(self.version)
  66         return os.path.join(base[0], *params)
  67
  68     @property
  69     @abstractmethod
  70     def user_data_dir(self) -> str:
  71         """:return: data directory tied to the user"""
  72
  73     @property
  74     @abstractmethod
  75     def site_data_dir(self) -> str:
  76         """:return: data directory shared by users"""
  77
  78     @property
  79     @abstractmethod
  80     def user_config_dir(self) -> str:
  81         """:return: config directory tied to the user"""
  82
  83     @property
  84     @abstractmethod
  85     def site_config_dir(self) -> str:
  86         """:return: config directory shared by the users"""
  87
  88     @property
  89     @abstractmethod
  90     def user_cache_dir(self) -> str:
  91         """:return: cache directory tied to the user"""
  92
  93     @property
  94     @abstractmethod
  95     def user_state_dir(self) -> str:
  96         """:return: state directory tied to the user"""
  97
  98     @property
  99     @abstractmethod
 100     def user_log_dir(self) -> str:
 101         """:return: log directory tied to the user"""
 102
 103     @property
 104     @abstractmethod
 105     def user_documents_dir(self) -> str:
 106         """:return: documents directory tied to the user"""
 107
 108     @property
 109     @abstractmethod
 110     def user_runtime_dir(self) -> str:
 111         """:return: runtime directory tied to the user"""
 112
 113     @property
 114     def user_data_path(self) -> Path:
 115         """:return: data path tied to the user"""
 116         return Path(self.user_data_dir)
 117
 118     @property
 119     def site_data_path(self) -> Path:
 120         """:return: data path shared by users"""
 121         return Path(self.site_data_dir)
 122
 123     @property
 124     def user_config_path(self) -> Path:
 125         """:return: config path tied to the user"""
 126         return Path(self.user_config_dir)
 127
 128     @property
 129     def site_config_path(self) -> Path:
 130         """:return: config path shared by the users"""
 131         return Path(self.site_config_dir)
 132
 133     @property
 134     def user_cache_path(self) -> Path:
 135         """:return: cache path tied to the user"""
 136         return Path(self.user_cache_dir)
 137
 138     @property
 139     def user_state_path(self) -> Path:
 140         """:return: state path tied to the user"""
 141         return Path(self.user_state_dir)
 142
 143     @property
 144     def user_log_path(self) -> Path:
 145         """:return: log path tied to the user"""
 146         return Path(self.user_log_dir)
 147
 148     @property
 149     def user_documents_path(self) -> Path:
 150         """:return: documents path tied to the user"""
 151         return Path(self.user_documents_dir)
 152
 153     @property
 154     def user_runtime_path(self) -> Path:
 155         """:return: runtime path tied to the user"""
 156         return Path(self.user_runtime_dir)