djavu-asus/emacs/elpy/rpc-venv/lib/python3.11/site-packages/platformdirs/api.py

   1 """Base API."""
   2 from __future__ import annotations
   3
   4 import os
   5 from abc import ABC, abstractmethod
   6 from pathlib import Path
   7 from typing import TYPE_CHECKING
   8
   9 if TYPE_CHECKING:
  10     import sys
  11
  12     if sys.version_info >= (3, 8):  # pragma: no cover (py38+)
  13         from typing import Literal
  14     else:  # pragma: no cover (py38+)
  15         from typing_extensions import Literal
  16
  17
  18 class PlatformDirsABC(ABC):
  19     """Abstract base class for platform directories."""
  20
  21     def __init__(  # noqa: PLR0913
  22         self,
  23         appname: str | None = None,
  24         appauthor: str | None | Literal[False] = None,
  25         version: str | None = None,
  26         roaming: bool = False,  # noqa: FBT001, FBT002
  27         multipath: bool = False,  # noqa: FBT001, FBT002
  28         opinion: bool = True,  # noqa: FBT001, FBT002
  29         ensure_exists: bool = False,  # noqa: FBT001, FBT002
  30     ) -> None:
  31         """
  32         Create a new platform directory.
  33
  34         :param appname: See `appname`.
  35         :param appauthor: See `appauthor`.
  36         :param version: See `version`.
  37         :param roaming: See `roaming`.
  38         :param multipath: See `multipath`.
  39         :param opinion: See `opinion`.
  40         :param ensure_exists: See `ensure_exists`.
  41         """
  42         self.appname = appname  #: The name of application.
  43         self.appauthor = appauthor
  44         """
  45         The name of the app author or distributing body for this application. Typically, it is the owning company name.
  46         Defaults to `appname`. You may pass ``False`` to disable it.
  47         """
  48         self.version = version
  49         """
  50         An optional version path element to append to the path. You might want to use this if you want multiple versions
  51         of your app to be able to run independently. If used, this would typically be ``<major>.<minor>``.
  52         """
  53         self.roaming = roaming
  54         """
  55         Whether to use the roaming appdata directory on Windows. That means that for users on a Windows network setup
  56         for roaming profiles, this user data will be synced on login (see
  57         `here <http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>`_).
  58         """
  59         self.multipath = multipath
  60         """
  61         An optional parameter which indicates that the entire list of data dirs should be returned.
  62         By default, the first item would only be returned.
  63         """
  64         self.opinion = opinion  #: A flag to indicating to use opinionated values.
  65         self.ensure_exists = ensure_exists
  66         """
  67         Optionally create the directory (and any missing parents) upon access if it does not exist.
  68         By default, no directories are created.
  69         """
  70
  71     def _append_app_name_and_version(self, *base: str) -> str:
  72         params = list(base[1:])
  73         if self.appname:
  74             params.append(self.appname)
  75             if self.version:
  76                 params.append(self.version)
  77         path = os.path.join(base[0], *params)  # noqa: PTH118
  78         self._optionally_create_directory(path)
  79         return path
  80
  81     def _optionally_create_directory(self, path: str) -> None:
  82         if self.ensure_exists:
  83             Path(path).mkdir(parents=True, exist_ok=True)
  84
  85     @property
  86     @abstractmethod
  87     def user_data_dir(self) -> str:
  88         """:return: data directory tied to the user"""
  89
  90     @property
  91     @abstractmethod
  92     def site_data_dir(self) -> str:
  93         """:return: data directory shared by users"""
  94
  95     @property
  96     @abstractmethod
  97     def user_config_dir(self) -> str:
  98         """:return: config directory tied to the user"""
  99
 100     @property
 101     @abstractmethod
 102     def site_config_dir(self) -> str:
 103         """:return: config directory shared by the users"""
 104
 105     @property
 106     @abstractmethod
 107     def user_cache_dir(self) -> str:
 108         """:return: cache directory tied to the user"""
 109
 110     @property
 111     @abstractmethod
 112     def site_cache_dir(self) -> str:
 113         """:return: cache directory shared by users"""
 114
 115     @property
 116     @abstractmethod
 117     def user_state_dir(self) -> str:
 118         """:return: state directory tied to the user"""
 119
 120     @property
 121     @abstractmethod
 122     def user_log_dir(self) -> str:
 123         """:return: log directory tied to the user"""
 124
 125     @property
 126     @abstractmethod
 127     def user_documents_dir(self) -> str:
 128         """:return: documents directory tied to the user"""
 129
 130     @property
 131     @abstractmethod
 132     def user_downloads_dir(self) -> str:
 133         """:return: downloads directory tied to the user"""
 134
 135     @property
 136     @abstractmethod
 137     def user_pictures_dir(self) -> str:
 138         """:return: pictures directory tied to the user"""
 139
 140     @property
 141     @abstractmethod
 142     def user_videos_dir(self) -> str:
 143         """:return: videos directory tied to the user"""
 144
 145     @property
 146     @abstractmethod
 147     def user_music_dir(self) -> str:
 148         """:return: music directory tied to the user"""
 149
 150     @property
 151     @abstractmethod
 152     def user_desktop_dir(self) -> str:
 153         """:return: desktop directory tied to the user"""
 154
 155     @property
 156     @abstractmethod
 157     def user_runtime_dir(self) -> str:
 158         """:return: runtime directory tied to the user"""
 159
 160     @property
 161     @abstractmethod
 162     def site_runtime_dir(self) -> str:
 163         """:return: runtime directory shared by users"""
 164
 165     @property
 166     def user_data_path(self) -> Path:
 167         """:return: data path tied to the user"""
 168         return Path(self.user_data_dir)
 169
 170     @property
 171     def site_data_path(self) -> Path:
 172         """:return: data path shared by users"""
 173         return Path(self.site_data_dir)
 174
 175     @property
 176     def user_config_path(self) -> Path:
 177         """:return: config path tied to the user"""
 178         return Path(self.user_config_dir)
 179
 180     @property
 181     def site_config_path(self) -> Path:
 182         """:return: config path shared by the users"""
 183         return Path(self.site_config_dir)
 184
 185     @property
 186     def user_cache_path(self) -> Path:
 187         """:return: cache path tied to the user"""
 188         return Path(self.user_cache_dir)
 189
 190     @property
 191     def site_cache_path(self) -> Path:
 192         """:return: cache path shared by users"""
 193         return Path(self.site_cache_dir)
 194
 195     @property
 196     def user_state_path(self) -> Path:
 197         """:return: state path tied to the user"""
 198         return Path(self.user_state_dir)
 199
 200     @property
 201     def user_log_path(self) -> Path:
 202         """:return: log path tied to the user"""
 203         return Path(self.user_log_dir)
 204
 205     @property
 206     def user_documents_path(self) -> Path:
 207         """:return: documents path tied to the user"""
 208         return Path(self.user_documents_dir)
 209
 210     @property
 211     def user_downloads_path(self) -> Path:
 212         """:return: downloads path tied to the user"""
 213         return Path(self.user_downloads_dir)
 214
 215     @property
 216     def user_pictures_path(self) -> Path:
 217         """:return: pictures path tied to the user"""
 218         return Path(self.user_pictures_dir)
 219
 220     @property
 221     def user_videos_path(self) -> Path:
 222         """:return: videos path tied to the user"""
 223         return Path(self.user_videos_dir)
 224
 225     @property
 226     def user_music_path(self) -> Path:
 227         """:return: music path tied to the user"""
 228         return Path(self.user_music_dir)
 229
 230     @property
 231     def user_desktop_path(self) -> Path:
 232         """:return: desktop path tied to the user"""
 233         return Path(self.user_desktop_dir)
 234
 235     @property
 236     def user_runtime_path(self) -> Path:
 237         """:return: runtime path tied to the user"""
 238         return Path(self.user_runtime_dir)
 239
 240     @property
 241     def site_runtime_path(self) -> Path:
 242         """:return: runtime path shared by users"""
 243         return Path(self.site_runtime_dir)