Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/platformdirs/api.py: 64%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""Base API."""
3from __future__ import annotations
5import os
6from abc import ABC, abstractmethod
7from pathlib import Path
8from typing import TYPE_CHECKING
10if TYPE_CHECKING:
11 from collections.abc import Iterator
12 from typing import Literal
15class PlatformDirsABC(ABC): # noqa: PLR0904
16 """Abstract base class defining all platform directory properties, their :class:`~pathlib.Path` variants, and iterators.
18 Platform-specific subclasses (e.g. :class:`~platformdirs.windows.Windows`, :class:`~platformdirs.macos.MacOS`,
19 :class:`~platformdirs.unix.Unix`) implement the abstract properties to return the appropriate paths for each
20 operating system.
22 """
24 def __init__( # noqa: PLR0913, PLR0917
25 self,
26 appname: str | None = None,
27 appauthor: str | Literal[False] | None = None,
28 version: str | None = None,
29 roaming: bool = False, # noqa: FBT001, FBT002
30 multipath: bool = False, # noqa: FBT001, FBT002
31 opinion: bool = True, # noqa: FBT001, FBT002
32 ensure_exists: bool = False, # noqa: FBT001, FBT002
33 use_site_for_root: bool = False, # noqa: FBT001, FBT002
34 ) -> None:
35 """Create a new platform directory.
37 :param appname: See `appname`.
38 :param appauthor: See `appauthor`.
39 :param version: See `version`.
40 :param roaming: See `roaming`.
41 :param multipath: See `multipath`.
42 :param opinion: See `opinion`.
43 :param ensure_exists: See `ensure_exists`.
44 :param use_site_for_root: See `use_site_for_root`.
46 """
47 self.appname = appname #: The name of the application.
48 self.appauthor = appauthor
49 """The name of the app author or distributing body for this application.
51 Typically, it is the owning company name. Defaults to `appname`. You may pass ``False`` to disable it.
53 """
54 self.version = version
55 """An optional version path element to append to the path.
57 You might want to use this if you want multiple versions of your app to be able to run independently. If used,
58 this would typically be ``<major>.<minor>``.
60 """
61 self.roaming = roaming
62 """Whether to use the roaming appdata directory on Windows.
64 That means that for users on a Windows network setup for roaming profiles, this user data will be synced on
65 login (see `here <https://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>`_).
67 """
68 self.multipath = multipath
69 """An optional parameter which indicates that the entire list of data dirs should be returned.
71 By default, the first item would only be returned. Only affects ``site_data_dir`` and ``site_config_dir`` on
72 Unix and macOS.
74 """
75 self.opinion = opinion
76 """Whether to use opinionated values.
78 When enabled, appends an additional subdirectory for certain directories: e.g. ``Cache`` for cache and ``Logs``
79 for logs on Windows, ``log`` for logs on Unix.
81 """
82 self.ensure_exists = ensure_exists
83 """Optionally create the directory (and any missing parents) upon access if it does not exist.
85 By default, no directories are created.
87 """
88 self.use_site_for_root = use_site_for_root
89 """Whether to redirect ``user_*_dir`` calls to their ``site_*_dir`` equivalents when running as root (uid 0).
91 Only has an effect on Unix. Disabled by default for backwards compatibility. When enabled, XDG user environment
92 variables (e.g. ``XDG_DATA_HOME``) are bypassed for the redirected directories.
94 """
96 def _append_app_name_and_version(self, *base: str) -> str:
97 params = list(base[1:])
98 if self.appname:
99 params.append(self.appname)
100 if self.version:
101 params.append(self.version)
102 path = os.path.join(base[0], *params) # noqa: PTH118
103 self._optionally_create_directory(path)
104 return path
106 def _optionally_create_directory(self, path: str) -> None:
107 if self.ensure_exists:
108 Path(path).mkdir(parents=True, exist_ok=True)
110 def _first_item_as_path_if_multipath(self, directory: str) -> Path:
111 if self.multipath:
112 # If multipath is True, the first path is returned.
113 directory = directory.partition(os.pathsep)[0]
114 return Path(directory)
116 @property
117 @abstractmethod
118 def user_data_dir(self) -> str:
119 """:returns: data directory tied to the user"""
121 @property
122 @abstractmethod
123 def site_data_dir(self) -> str:
124 """:returns: data directory shared by users"""
126 @property
127 @abstractmethod
128 def user_config_dir(self) -> str:
129 """:returns: config directory tied to the user"""
131 @property
132 @abstractmethod
133 def site_config_dir(self) -> str:
134 """:returns: config directory shared by users"""
136 @property
137 @abstractmethod
138 def user_cache_dir(self) -> str:
139 """:returns: cache directory tied to the user"""
141 @property
142 @abstractmethod
143 def site_cache_dir(self) -> str:
144 """:returns: cache directory shared by users"""
146 @property
147 @abstractmethod
148 def user_state_dir(self) -> str:
149 """:returns: state directory tied to the user"""
151 @property
152 @abstractmethod
153 def site_state_dir(self) -> str:
154 """:returns: state directory shared by users"""
156 @property
157 @abstractmethod
158 def user_log_dir(self) -> str:
159 """:returns: log directory tied to the user"""
161 @property
162 @abstractmethod
163 def site_log_dir(self) -> str:
164 """:returns: log directory shared by users"""
166 @property
167 @abstractmethod
168 def user_documents_dir(self) -> str:
169 """:returns: documents directory tied to the user"""
171 @property
172 @abstractmethod
173 def user_downloads_dir(self) -> str:
174 """:returns: downloads directory tied to the user"""
176 @property
177 @abstractmethod
178 def user_pictures_dir(self) -> str:
179 """:returns: pictures directory tied to the user"""
181 @property
182 @abstractmethod
183 def user_videos_dir(self) -> str:
184 """:returns: videos directory tied to the user"""
186 @property
187 @abstractmethod
188 def user_music_dir(self) -> str:
189 """:returns: music directory tied to the user"""
191 @property
192 @abstractmethod
193 def user_desktop_dir(self) -> str:
194 """:returns: desktop directory tied to the user"""
196 @property
197 @abstractmethod
198 def user_bin_dir(self) -> str:
199 """:returns: bin directory tied to the user"""
201 @property
202 @abstractmethod
203 def site_bin_dir(self) -> str:
204 """:returns: bin directory shared by users"""
206 @property
207 @abstractmethod
208 def user_applications_dir(self) -> str:
209 """:returns: applications directory tied to the user"""
211 @property
212 @abstractmethod
213 def site_applications_dir(self) -> str:
214 """:returns: applications directory shared by users"""
216 @property
217 @abstractmethod
218 def user_runtime_dir(self) -> str:
219 """:returns: runtime directory tied to the user"""
221 @property
222 @abstractmethod
223 def site_runtime_dir(self) -> str:
224 """:returns: runtime directory shared by users"""
226 @property
227 def user_data_path(self) -> Path:
228 """:returns: data path tied to the user"""
229 return Path(self.user_data_dir)
231 @property
232 def site_data_path(self) -> Path:
233 """:returns: data path shared by users"""
234 return Path(self.site_data_dir)
236 @property
237 def user_config_path(self) -> Path:
238 """:returns: config path tied to the user"""
239 return Path(self.user_config_dir)
241 @property
242 def site_config_path(self) -> Path:
243 """:returns: config path shared by users"""
244 return Path(self.site_config_dir)
246 @property
247 def user_cache_path(self) -> Path:
248 """:returns: cache path tied to the user"""
249 return Path(self.user_cache_dir)
251 @property
252 def site_cache_path(self) -> Path:
253 """:returns: cache path shared by users"""
254 return Path(self.site_cache_dir)
256 @property
257 def user_state_path(self) -> Path:
258 """:returns: state path tied to the user"""
259 return Path(self.user_state_dir)
261 @property
262 def site_state_path(self) -> Path:
263 """:returns: state path shared by users"""
264 return Path(self.site_state_dir)
266 @property
267 def user_log_path(self) -> Path:
268 """:returns: log path tied to the user"""
269 return Path(self.user_log_dir)
271 @property
272 def site_log_path(self) -> Path:
273 """:returns: log path shared by users"""
274 return Path(self.site_log_dir)
276 @property
277 def user_documents_path(self) -> Path:
278 """:returns: documents path tied to the user"""
279 return Path(self.user_documents_dir)
281 @property
282 def user_downloads_path(self) -> Path:
283 """:returns: downloads path tied to the user"""
284 return Path(self.user_downloads_dir)
286 @property
287 def user_pictures_path(self) -> Path:
288 """:returns: pictures path tied to the user"""
289 return Path(self.user_pictures_dir)
291 @property
292 def user_videos_path(self) -> Path:
293 """:returns: videos path tied to the user"""
294 return Path(self.user_videos_dir)
296 @property
297 def user_music_path(self) -> Path:
298 """:returns: music path tied to the user"""
299 return Path(self.user_music_dir)
301 @property
302 def user_desktop_path(self) -> Path:
303 """:returns: desktop path tied to the user"""
304 return Path(self.user_desktop_dir)
306 @property
307 def user_bin_path(self) -> Path:
308 """:returns: bin path tied to the user"""
309 return Path(self.user_bin_dir)
311 @property
312 def site_bin_path(self) -> Path:
313 """:returns: bin path shared by users"""
314 return Path(self.site_bin_dir)
316 @property
317 def user_applications_path(self) -> Path:
318 """:returns: applications path tied to the user"""
319 return Path(self.user_applications_dir)
321 @property
322 def site_applications_path(self) -> Path:
323 """:returns: applications path shared by users"""
324 return Path(self.site_applications_dir)
326 @property
327 def user_runtime_path(self) -> Path:
328 """:returns: runtime path tied to the user"""
329 return Path(self.user_runtime_dir)
331 @property
332 def site_runtime_path(self) -> Path:
333 """:returns: runtime path shared by users"""
334 return Path(self.site_runtime_dir)
336 def iter_config_dirs(self) -> Iterator[str]:
337 """:yield: all user and site configuration directories."""
338 yield self.user_config_dir
339 yield self.site_config_dir
341 def iter_data_dirs(self) -> Iterator[str]:
342 """:yield: all user and site data directories."""
343 yield self.user_data_dir
344 yield self.site_data_dir
346 def iter_cache_dirs(self) -> Iterator[str]:
347 """:yield: all user and site cache directories."""
348 yield self.user_cache_dir
349 yield self.site_cache_dir
351 def iter_state_dirs(self) -> Iterator[str]:
352 """:yield: all user and site state directories."""
353 yield self.user_state_dir
354 yield self.site_state_dir
356 def iter_log_dirs(self) -> Iterator[str]:
357 """:yield: all user and site log directories."""
358 yield self.user_log_dir
359 yield self.site_log_dir
361 def iter_runtime_dirs(self) -> Iterator[str]:
362 """:yield: all user and site runtime directories."""
363 yield self.user_runtime_dir
364 yield self.site_runtime_dir
366 def iter_config_paths(self) -> Iterator[Path]:
367 """:yield: all user and site configuration paths."""
368 for path in self.iter_config_dirs():
369 yield Path(path)
371 def iter_data_paths(self) -> Iterator[Path]:
372 """:yield: all user and site data paths."""
373 for path in self.iter_data_dirs():
374 yield Path(path)
376 def iter_cache_paths(self) -> Iterator[Path]:
377 """:yield: all user and site cache paths."""
378 for path in self.iter_cache_dirs():
379 yield Path(path)
381 def iter_state_paths(self) -> Iterator[Path]:
382 """:yield: all user and site state paths."""
383 for path in self.iter_state_dirs():
384 yield Path(path)
386 def iter_log_paths(self) -> Iterator[Path]:
387 """:yield: all user and site log paths."""
388 for path in self.iter_log_dirs():
389 yield Path(path)
391 def iter_runtime_paths(self) -> Iterator[Path]:
392 """:yield: all user and site runtime paths."""
393 for path in self.iter_runtime_dirs():
394 yield Path(path)