Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/platformdirs/__init__.py: 54%
90 statements
« prev ^ index » next coverage.py v7.3.1, created at 2023-09-25 06:08 +0000
1"""
2Utilities for determining application-specific dirs. See <https://github.com/platformdirs/platformdirs> for details and
3usage.
4"""
5from __future__ import annotations
7import os
8import sys
9from typing import TYPE_CHECKING
11from .api import PlatformDirsABC
12from .version import __version__
13from .version import __version_tuple__ as __version_info__
15if TYPE_CHECKING:
16 from pathlib import Path
18 if sys.version_info >= (3, 8): # pragma: no cover (py38+)
19 from typing import Literal
20 else: # pragma: no cover (py38+)
21 from typing_extensions import Literal
24def _set_platform_dir_class() -> type[PlatformDirsABC]:
25 if sys.platform == "win32":
26 from platformdirs.windows import Windows as Result
27 elif sys.platform == "darwin":
28 from platformdirs.macos import MacOS as Result
29 else:
30 from platformdirs.unix import Unix as Result
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
36 from platformdirs.android import _android_folder
38 if _android_folder() is not None:
39 from platformdirs.android import Android
41 return Android # return to avoid redefinition of result
43 return Result
46PlatformDirs = _set_platform_dir_class() #: Currently active platform
47AppDirs = PlatformDirs #: Backwards compatibility with appdirs
50def 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
74def 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
98def 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
122def 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
146def 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
170def 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
194def 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
218def 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
242def user_documents_dir() -> str:
243 """:returns: documents directory tied to the user"""
244 return PlatformDirs().user_documents_dir
247def user_downloads_dir() -> str:
248 """:returns: downloads directory tied to the user"""
249 return PlatformDirs().user_downloads_dir
252def user_pictures_dir() -> str:
253 """:returns: pictures directory tied to the user"""
254 return PlatformDirs().user_pictures_dir
257def user_videos_dir() -> str:
258 """:returns: videos directory tied to the user"""
259 return PlatformDirs().user_videos_dir
262def user_music_dir() -> str:
263 """:returns: music directory tied to the user"""
264 return PlatformDirs().user_music_dir
267def user_desktop_dir() -> str:
268 """:returns: desktop directory tied to the user"""
269 return PlatformDirs().user_desktop_dir
272def user_runtime_dir(
273 appname: str | None = None,
274 appauthor: str | None | Literal[False] = None,
275 version: str | None = None,
276 opinion: bool = True, # noqa: FBT001, FBT002
277 ensure_exists: bool = False, # noqa: FBT001, FBT002
278) -> str:
279 """
280 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
281 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
282 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
283 :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
284 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
285 :returns: runtime directory tied to the user
286 """
287 return PlatformDirs(
288 appname=appname,
289 appauthor=appauthor,
290 version=version,
291 opinion=opinion,
292 ensure_exists=ensure_exists,
293 ).user_runtime_dir
296def site_runtime_dir(
297 appname: str | None = None,
298 appauthor: str | None | Literal[False] = None,
299 version: str | None = None,
300 opinion: bool = True, # noqa: FBT001, FBT002
301 ensure_exists: bool = False, # noqa: FBT001, FBT002
302) -> str:
303 """
304 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
305 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
306 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
307 :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
308 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
309 :returns: runtime directory shared by users
310 """
311 return PlatformDirs(
312 appname=appname,
313 appauthor=appauthor,
314 version=version,
315 opinion=opinion,
316 ensure_exists=ensure_exists,
317 ).site_runtime_dir
320def user_data_path(
321 appname: str | None = None,
322 appauthor: str | None | Literal[False] = None,
323 version: str | None = None,
324 roaming: bool = False, # noqa: FBT001, FBT002
325 ensure_exists: bool = False, # noqa: FBT001, FBT002
326) -> Path:
327 """
328 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
329 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
330 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
331 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
332 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
333 :returns: data path tied to the user
334 """
335 return PlatformDirs(
336 appname=appname,
337 appauthor=appauthor,
338 version=version,
339 roaming=roaming,
340 ensure_exists=ensure_exists,
341 ).user_data_path
344def site_data_path(
345 appname: str | None = None,
346 appauthor: str | None | Literal[False] = None,
347 version: str | None = None,
348 multipath: bool = False, # noqa: FBT001, FBT002
349 ensure_exists: bool = False, # noqa: FBT001, FBT002
350) -> Path:
351 """
352 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
353 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
354 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
355 :param multipath: See `multipath <platformdirs.api.PlatformDirsABC.multipath>`.
356 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
357 :returns: data path shared by users
358 """
359 return PlatformDirs(
360 appname=appname,
361 appauthor=appauthor,
362 version=version,
363 multipath=multipath,
364 ensure_exists=ensure_exists,
365 ).site_data_path
368def user_config_path(
369 appname: str | None = None,
370 appauthor: str | None | Literal[False] = None,
371 version: str | None = None,
372 roaming: bool = False, # noqa: FBT001, FBT002
373 ensure_exists: bool = False, # noqa: FBT001, FBT002
374) -> Path:
375 """
376 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
377 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
378 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
379 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
380 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
381 :returns: config path tied to the user
382 """
383 return PlatformDirs(
384 appname=appname,
385 appauthor=appauthor,
386 version=version,
387 roaming=roaming,
388 ensure_exists=ensure_exists,
389 ).user_config_path
392def site_config_path(
393 appname: str | None = None,
394 appauthor: str | None | Literal[False] = None,
395 version: str | None = None,
396 multipath: bool = False, # noqa: FBT001, FBT002
397 ensure_exists: bool = False, # noqa: FBT001, FBT002
398) -> Path:
399 """
400 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
401 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
402 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
403 :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.
404 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
405 :returns: config path shared by the users
406 """
407 return PlatformDirs(
408 appname=appname,
409 appauthor=appauthor,
410 version=version,
411 multipath=multipath,
412 ensure_exists=ensure_exists,
413 ).site_config_path
416def site_cache_path(
417 appname: str | None = None,
418 appauthor: str | None | Literal[False] = None,
419 version: str | None = None,
420 opinion: bool = True, # noqa: FBT001, FBT002
421 ensure_exists: bool = False, # noqa: FBT001, FBT002
422) -> Path:
423 """
424 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
425 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
426 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
427 :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
428 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
429 :returns: cache directory tied to the user
430 """
431 return PlatformDirs(
432 appname=appname,
433 appauthor=appauthor,
434 version=version,
435 opinion=opinion,
436 ensure_exists=ensure_exists,
437 ).site_cache_path
440def user_cache_path(
441 appname: str | None = None,
442 appauthor: str | None | Literal[False] = None,
443 version: str | None = None,
444 opinion: bool = True, # noqa: FBT001, FBT002
445 ensure_exists: bool = False, # noqa: FBT001, FBT002
446) -> Path:
447 """
448 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
449 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
450 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
451 :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
452 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
453 :returns: cache path tied to the user
454 """
455 return PlatformDirs(
456 appname=appname,
457 appauthor=appauthor,
458 version=version,
459 opinion=opinion,
460 ensure_exists=ensure_exists,
461 ).user_cache_path
464def user_state_path(
465 appname: str | None = None,
466 appauthor: str | None | Literal[False] = None,
467 version: str | None = None,
468 roaming: bool = False, # noqa: FBT001, FBT002
469 ensure_exists: bool = False, # noqa: FBT001, FBT002
470) -> Path:
471 """
472 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
473 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
474 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
475 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
476 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
477 :returns: state path tied to the user
478 """
479 return PlatformDirs(
480 appname=appname,
481 appauthor=appauthor,
482 version=version,
483 roaming=roaming,
484 ensure_exists=ensure_exists,
485 ).user_state_path
488def user_log_path(
489 appname: str | None = None,
490 appauthor: str | None | Literal[False] = None,
491 version: str | None = None,
492 opinion: bool = True, # noqa: FBT001, FBT002
493 ensure_exists: bool = False, # noqa: FBT001, FBT002
494) -> Path:
495 """
496 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
497 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
498 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
499 :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
500 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
501 :returns: log path tied to the user
502 """
503 return PlatformDirs(
504 appname=appname,
505 appauthor=appauthor,
506 version=version,
507 opinion=opinion,
508 ensure_exists=ensure_exists,
509 ).user_log_path
512def user_documents_path() -> Path:
513 """:returns: documents path tied to the user"""
514 return PlatformDirs().user_documents_path
517def user_downloads_path() -> Path:
518 """:returns: downloads path tied to the user"""
519 return PlatformDirs().user_downloads_path
522def user_pictures_path() -> Path:
523 """:returns: pictures path tied to the user"""
524 return PlatformDirs().user_pictures_path
527def user_videos_path() -> Path:
528 """:returns: videos path tied to the user"""
529 return PlatformDirs().user_videos_path
532def user_music_path() -> Path:
533 """:returns: music path tied to the user"""
534 return PlatformDirs().user_music_path
537def user_desktop_path() -> Path:
538 """:returns: desktop path tied to the user"""
539 return PlatformDirs().user_desktop_path
542def user_runtime_path(
543 appname: str | None = None,
544 appauthor: str | None | Literal[False] = None,
545 version: str | None = None,
546 opinion: bool = True, # noqa: FBT001, FBT002
547 ensure_exists: bool = False, # noqa: FBT001, FBT002
548) -> Path:
549 """
550 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
551 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
552 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
553 :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
554 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
555 :returns: runtime path tied to the user
556 """
557 return PlatformDirs(
558 appname=appname,
559 appauthor=appauthor,
560 version=version,
561 opinion=opinion,
562 ensure_exists=ensure_exists,
563 ).user_runtime_path
566def site_runtime_path(
567 appname: str | None = None,
568 appauthor: str | None | Literal[False] = None,
569 version: str | None = None,
570 opinion: bool = True, # noqa: FBT001, FBT002
571 ensure_exists: bool = False, # noqa: FBT001, FBT002
572) -> Path:
573 """
574 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
575 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
576 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
577 :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
578 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
579 :returns: runtime path shared by users
580 """
581 return PlatformDirs(
582 appname=appname,
583 appauthor=appauthor,
584 version=version,
585 opinion=opinion,
586 ensure_exists=ensure_exists,
587 ).site_runtime_path
590__all__ = [
591 "__version__",
592 "__version_info__",
593 "PlatformDirs",
594 "AppDirs",
595 "PlatformDirsABC",
596 "user_data_dir",
597 "user_config_dir",
598 "user_cache_dir",
599 "user_state_dir",
600 "user_log_dir",
601 "user_documents_dir",
602 "user_downloads_dir",
603 "user_pictures_dir",
604 "user_videos_dir",
605 "user_music_dir",
606 "user_desktop_dir",
607 "user_runtime_dir",
608 "site_data_dir",
609 "site_config_dir",
610 "site_cache_dir",
611 "site_runtime_dir",
612 "user_data_path",
613 "user_config_path",
614 "user_cache_path",
615 "user_state_path",
616 "user_log_path",
617 "user_documents_path",
618 "user_downloads_path",
619 "user_pictures_path",
620 "user_videos_path",
621 "user_music_path",
622 "user_desktop_path",
623 "user_runtime_path",
624 "site_data_path",
625 "site_config_path",
626 "site_cache_path",
627 "site_runtime_path",
628]