platformdirs 4.13.7__tar.gz → 4.14.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {platformdirs-4.13.7 → platformdirs-4.14.2}/PKG-INFO +1 -1
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/__init__.py +126 -54
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/_xdg.py +21 -8
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/api.py +21 -10
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/macos.py +49 -3
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/unix.py +102 -25
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/version.py +2 -2
- {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/conftest.py +17 -1
- {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_api.py +62 -10
- {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_macos.py +165 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_main.py +1 -1
- {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_testing.py +1 -1
- {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_unix.py +486 -36
- {platformdirs-4.13.7 → platformdirs-4.14.2}/.gitignore +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/LICENSE +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/pyproject.toml +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/__main__.py +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/android.py +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/ios.py +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/py.typed +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/pytest_plugin.py +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/testing.py +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/windows.py +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_android.py +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_comp_with_appdirs.py +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_ios.py +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_pytest_plugin.py +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_windows.py +0 -0
- {platformdirs-4.13.7 → platformdirs-4.14.2}/tox.toml +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: platformdirs
|
|
3
|
-
Version: 4.
|
|
3
|
+
Version: 4.14.2
|
|
4
4
|
Import-Name: platformdirs
|
|
5
5
|
Summary: A small Python package for determining appropriate platform-specific dirs, e.g. a `user data dir`.
|
|
6
6
|
Project-URL: Changelog, https://platformdirs.readthedocs.io/en/latest/changelog.html
|
|
@@ -329,49 +329,85 @@ def site_log_dir(
|
|
|
329
329
|
).site_log_dir
|
|
330
330
|
|
|
331
331
|
|
|
332
|
-
def user_documents_dir() -> str:
|
|
333
|
-
""":
|
|
334
|
-
return PlatformDirs().user_documents_dir
|
|
332
|
+
def user_documents_dir(*, ensure_exists: bool = False) -> str:
|
|
333
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
335
334
|
|
|
335
|
+
:returns: documents directory tied to the user
|
|
336
|
+
|
|
337
|
+
"""
|
|
338
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_documents_dir
|
|
339
|
+
|
|
340
|
+
|
|
341
|
+
def user_downloads_dir(*, ensure_exists: bool = False) -> str:
|
|
342
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
343
|
+
|
|
344
|
+
:returns: downloads directory tied to the user
|
|
345
|
+
|
|
346
|
+
"""
|
|
347
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_downloads_dir
|
|
336
348
|
|
|
337
|
-
def user_downloads_dir() -> str:
|
|
338
|
-
""":returns: downloads directory tied to the user"""
|
|
339
|
-
return PlatformDirs().user_downloads_dir
|
|
340
349
|
|
|
350
|
+
def user_pictures_dir(*, ensure_exists: bool = False) -> str:
|
|
351
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
341
352
|
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
353
|
+
:returns: pictures directory tied to the user
|
|
354
|
+
|
|
355
|
+
"""
|
|
356
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_pictures_dir
|
|
345
357
|
|
|
346
358
|
|
|
347
|
-
def user_videos_dir() -> str:
|
|
348
|
-
""":
|
|
349
|
-
return PlatformDirs().user_videos_dir
|
|
359
|
+
def user_videos_dir(*, ensure_exists: bool = False) -> str:
|
|
360
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
350
361
|
|
|
362
|
+
:returns: videos directory tied to the user
|
|
351
363
|
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
return PlatformDirs().user_music_dir
|
|
364
|
+
"""
|
|
365
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_videos_dir
|
|
355
366
|
|
|
356
367
|
|
|
357
|
-
def
|
|
358
|
-
""":
|
|
359
|
-
return PlatformDirs().user_desktop_dir
|
|
368
|
+
def user_music_dir(*, ensure_exists: bool = False) -> str:
|
|
369
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
360
370
|
|
|
371
|
+
:returns: music directory tied to the user
|
|
361
372
|
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
return PlatformDirs().user_projects_dir
|
|
373
|
+
"""
|
|
374
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_music_dir
|
|
365
375
|
|
|
366
376
|
|
|
367
|
-
def
|
|
368
|
-
""":
|
|
369
|
-
|
|
377
|
+
def user_desktop_dir(*, ensure_exists: bool = False) -> str:
|
|
378
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
379
|
+
|
|
380
|
+
:returns: desktop directory tied to the user
|
|
381
|
+
|
|
382
|
+
"""
|
|
383
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_desktop_dir
|
|
370
384
|
|
|
371
385
|
|
|
372
|
-
def
|
|
373
|
-
""":
|
|
374
|
-
|
|
386
|
+
def user_projects_dir(*, ensure_exists: bool = False) -> str:
|
|
387
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
388
|
+
|
|
389
|
+
:returns: projects directory tied to the user
|
|
390
|
+
|
|
391
|
+
"""
|
|
392
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_projects_dir
|
|
393
|
+
|
|
394
|
+
|
|
395
|
+
def user_publicshare_dir(*, ensure_exists: bool = False) -> str:
|
|
396
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
397
|
+
|
|
398
|
+
:returns: public share directory tied to the user
|
|
399
|
+
|
|
400
|
+
"""
|
|
401
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_publicshare_dir
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
def user_templates_dir(*, ensure_exists: bool = False) -> str:
|
|
405
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
406
|
+
|
|
407
|
+
:returns: templates directory tied to the user
|
|
408
|
+
|
|
409
|
+
"""
|
|
410
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_templates_dir
|
|
375
411
|
|
|
376
412
|
|
|
377
413
|
def user_fonts_dir() -> str:
|
|
@@ -797,49 +833,85 @@ def site_log_path(
|
|
|
797
833
|
).site_log_path
|
|
798
834
|
|
|
799
835
|
|
|
800
|
-
def user_documents_path() -> Path:
|
|
801
|
-
""":
|
|
802
|
-
return PlatformDirs().user_documents_path
|
|
836
|
+
def user_documents_path(*, ensure_exists: bool = False) -> Path:
|
|
837
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
803
838
|
|
|
839
|
+
:returns: documents path tied to the user
|
|
840
|
+
|
|
841
|
+
"""
|
|
842
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_documents_path
|
|
843
|
+
|
|
844
|
+
|
|
845
|
+
def user_downloads_path(*, ensure_exists: bool = False) -> Path:
|
|
846
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
847
|
+
|
|
848
|
+
:returns: downloads path tied to the user
|
|
849
|
+
|
|
850
|
+
"""
|
|
851
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_downloads_path
|
|
804
852
|
|
|
805
|
-
def user_downloads_path() -> Path:
|
|
806
|
-
""":returns: downloads path tied to the user"""
|
|
807
|
-
return PlatformDirs().user_downloads_path
|
|
808
853
|
|
|
854
|
+
def user_pictures_path(*, ensure_exists: bool = False) -> Path:
|
|
855
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
809
856
|
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
857
|
+
:returns: pictures path tied to the user
|
|
858
|
+
|
|
859
|
+
"""
|
|
860
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_pictures_path
|
|
813
861
|
|
|
814
862
|
|
|
815
|
-
def user_videos_path() -> Path:
|
|
816
|
-
""":
|
|
817
|
-
return PlatformDirs().user_videos_path
|
|
863
|
+
def user_videos_path(*, ensure_exists: bool = False) -> Path:
|
|
864
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
818
865
|
|
|
866
|
+
:returns: videos path tied to the user
|
|
819
867
|
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
return PlatformDirs().user_music_path
|
|
868
|
+
"""
|
|
869
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_videos_path
|
|
823
870
|
|
|
824
871
|
|
|
825
|
-
def
|
|
826
|
-
""":
|
|
827
|
-
return PlatformDirs().user_desktop_path
|
|
872
|
+
def user_music_path(*, ensure_exists: bool = False) -> Path:
|
|
873
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
828
874
|
|
|
875
|
+
:returns: music path tied to the user
|
|
829
876
|
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
return PlatformDirs().user_projects_path
|
|
877
|
+
"""
|
|
878
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_music_path
|
|
833
879
|
|
|
834
880
|
|
|
835
|
-
def
|
|
836
|
-
""":
|
|
837
|
-
|
|
881
|
+
def user_desktop_path(*, ensure_exists: bool = False) -> Path:
|
|
882
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
883
|
+
|
|
884
|
+
:returns: desktop path tied to the user
|
|
885
|
+
|
|
886
|
+
"""
|
|
887
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_desktop_path
|
|
838
888
|
|
|
839
889
|
|
|
840
|
-
def
|
|
841
|
-
""":
|
|
842
|
-
|
|
890
|
+
def user_projects_path(*, ensure_exists: bool = False) -> Path:
|
|
891
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
892
|
+
|
|
893
|
+
:returns: projects path tied to the user
|
|
894
|
+
|
|
895
|
+
"""
|
|
896
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_projects_path
|
|
897
|
+
|
|
898
|
+
|
|
899
|
+
def user_publicshare_path(*, ensure_exists: bool = False) -> Path:
|
|
900
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
901
|
+
|
|
902
|
+
:returns: public share path tied to the user
|
|
903
|
+
|
|
904
|
+
"""
|
|
905
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_publicshare_path
|
|
906
|
+
|
|
907
|
+
|
|
908
|
+
def user_templates_path(*, ensure_exists: bool = False) -> Path:
|
|
909
|
+
""":param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
|
|
910
|
+
|
|
911
|
+
:returns: templates path tied to the user
|
|
912
|
+
|
|
913
|
+
"""
|
|
914
|
+
return PlatformDirs(ensure_exists=ensure_exists).user_templates_path
|
|
843
915
|
|
|
844
916
|
|
|
845
917
|
def user_fonts_path() -> Path:
|
|
@@ -6,6 +6,7 @@ import os
|
|
|
6
6
|
import posixpath
|
|
7
7
|
import sys
|
|
8
8
|
from contextlib import suppress
|
|
9
|
+
from pathlib import Path
|
|
9
10
|
from typing import Final
|
|
10
11
|
|
|
11
12
|
from .api import PlatformDirsABC
|
|
@@ -66,9 +67,16 @@ class XDGMixin(PlatformDirsABC):
|
|
|
66
67
|
|
|
67
68
|
@property
|
|
68
69
|
def user_runtime_dir(self) -> str:
|
|
69
|
-
"""Runtime directory tied to the user, from ``$XDG_RUNTIME_DIR`` if set, else platform default."""
|
|
70
|
+
"""Runtime directory tied to the user, from ``$XDG_RUNTIME_DIR`` if set and private, else platform default."""
|
|
71
|
+
from .unix import _runtime_dir_problem, _warn_once # ruff:ignore[import-outside-top-level] # unix imports _xdg
|
|
72
|
+
|
|
70
73
|
if path := _xdg_dir("XDG_RUNTIME_DIR"):
|
|
71
|
-
|
|
74
|
+
with suppress(OSError):
|
|
75
|
+
self._optionally_create_directory(path, private=True)
|
|
76
|
+
# Another user can pre-create the path in a shared parent, and XDG requires an owned runtime dir with mode 0700.
|
|
77
|
+
if not (problem := _runtime_dir_problem(path, missing_ok=not self.ensure_exists)):
|
|
78
|
+
return self._append_app_name_and_version(path, private=True)
|
|
79
|
+
_warn_once(f"XDG_RUNTIME_DIR {problem}, falling back to the platform default")
|
|
72
80
|
return super().user_runtime_dir
|
|
73
81
|
|
|
74
82
|
@property
|
|
@@ -168,13 +176,13 @@ def _xdg_dir_list(env_var: str) -> list[str]:
|
|
|
168
176
|
|
|
169
177
|
|
|
170
178
|
def _expand_user(path: str) -> str:
|
|
171
|
-
"""Expand the leading ``~`` of ``path`` like :func:`os.path.expanduser`, treating
|
|
179
|
+
"""Expand the leading ``~`` of ``path`` like :func:`os.path.expanduser`, treating a relative ``HOME`` as unset on POSIX.
|
|
172
180
|
|
|
173
|
-
:raises RuntimeError: if the home directory cannot be resolved.
|
|
181
|
+
:raises RuntimeError: if the home directory cannot be resolved to an absolute path.
|
|
174
182
|
|
|
175
183
|
"""
|
|
176
|
-
if sys.platform != "win32" and "HOME" in os.environ and not os.environ["HOME"]:
|
|
177
|
-
# expanduser roots the path at /
|
|
184
|
+
if sys.platform != "win32" and "HOME" in os.environ and not _is_absolute(os.environ["HOME"]):
|
|
185
|
+
# expanduser uses HOME verbatim, so an empty one roots the path at / and a relative one at the working directory
|
|
178
186
|
expanded = path
|
|
179
187
|
with suppress(ImportError, KeyError):
|
|
180
188
|
import pwd # ruff:ignore[import-outside-top-level] # missing on WASI
|
|
@@ -182,12 +190,17 @@ def _expand_user(path: str) -> str:
|
|
|
182
190
|
expanded = pwd.getpwuid(os.getuid()).pw_dir.rstrip("/") + path[1:] or "/"
|
|
183
191
|
else:
|
|
184
192
|
expanded = os.path.expanduser(path) # ruff:ignore[os-path-expanduser] # str(Path) rewrites separators on Windows
|
|
185
|
-
if expanded
|
|
186
|
-
msg = f"could not determine the home directory for {path!r}, set HOME or
|
|
193
|
+
if not _is_absolute(expanded):
|
|
194
|
+
msg = f"could not determine the home directory for {path!r}, set an absolute HOME or XDG variable"
|
|
187
195
|
raise RuntimeError(msg)
|
|
188
196
|
return expanded
|
|
189
197
|
|
|
190
198
|
|
|
199
|
+
def _is_absolute(path: str) -> bool:
|
|
200
|
+
# is_absolute accepts a Windows drive path, posixpath.isabs the POSIX home the Unix class gets on any host
|
|
201
|
+
return posixpath.isabs(path) or Path(path).is_absolute()
|
|
202
|
+
|
|
203
|
+
|
|
191
204
|
__all__ = [
|
|
192
205
|
"XDGMixin",
|
|
193
206
|
"_expand_user",
|
|
@@ -4,7 +4,6 @@ from __future__ import annotations
|
|
|
4
4
|
|
|
5
5
|
import os
|
|
6
6
|
from abc import ABC, abstractmethod
|
|
7
|
-
from contextlib import suppress
|
|
8
7
|
from copy import copy
|
|
9
8
|
from pathlib import Path
|
|
10
9
|
from typing import TYPE_CHECKING
|
|
@@ -60,7 +59,9 @@ class PlatformDirsABC(ABC): # ruff:ignore[too-many-public-methods]
|
|
|
60
59
|
"""An optional parameter which indicates that the entire list of data dirs should be returned.
|
|
61
60
|
|
|
62
61
|
When ``False``, only the first item is returned. Affects ``site_data_dir``, ``site_config_dir`` and
|
|
63
|
-
``site_applications_dir`` on Unix and macOS, and ``site_cache_dir`` on macOS under Homebrew.
|
|
62
|
+
``site_applications_dir`` on Unix and macOS, and ``site_cache_dir`` on macOS under Homebrew. All but
|
|
63
|
+
``site_applications_dir`` raise :class:`ValueError` under it when `appname` or `version` contains
|
|
64
|
+
:data:`os.pathsep`.
|
|
64
65
|
|
|
65
66
|
"""
|
|
66
67
|
self.opinion = opinion
|
|
@@ -78,7 +79,7 @@ class PlatformDirsABC(ABC): # ruff:ignore[too-many-public-methods]
|
|
|
78
79
|
|
|
79
80
|
"""
|
|
80
81
|
self.use_site_for_root = use_site_for_root
|
|
81
|
-
"""Whether to redirect ``user_*_dir`` calls to their ``site_*_dir`` equivalents when
|
|
82
|
+
"""Whether to redirect ``user_*_dir`` calls to their ``site_*_dir`` equivalents when the effective uid is 0.
|
|
82
83
|
|
|
83
84
|
Only has an effect on Unix. Disabled by default for backwards compatibility. When enabled, XDG user environment
|
|
84
85
|
variables (e.g. ``XDG_DATA_HOME``) are bypassed for the redirected directories.
|
|
@@ -156,12 +157,19 @@ class PlatformDirsABC(ABC): # ruff:ignore[too-many-public-methods]
|
|
|
156
157
|
def _optionally_create_media_directory(self, path: str) -> None:
|
|
157
158
|
# Only called for a media directory the user configured. Media directories are often symlinks to removable or
|
|
158
159
|
# network storage, so a dangling link is returned as-is, like before ensure_exists covered them.
|
|
159
|
-
|
|
160
|
+
try:
|
|
160
161
|
self._optionally_create_directory(path, private=False)
|
|
162
|
+
except FileExistsError:
|
|
163
|
+
if not (directory := Path(path)).is_symlink() or directory.exists():
|
|
164
|
+
raise
|
|
161
165
|
|
|
162
166
|
def _select_site_dirs(self, dirs: list[str]) -> str:
|
|
163
167
|
# Site lists are built without touching the disk, so ensure_exists only creates what the caller gets back.
|
|
164
168
|
selected = dirs if self.multipath else dirs[:1]
|
|
169
|
+
if self.multipath and any(os.pathsep in path for path in selected):
|
|
170
|
+
# Callers split the joined string on os.pathsep, so a separator inside one entry reads as two directories.
|
|
171
|
+
msg = f"multipath cannot join site directories that contain {os.pathsep!r}, got {selected!r}"
|
|
172
|
+
raise ValueError(msg)
|
|
165
173
|
for path in selected:
|
|
166
174
|
self._optionally_create_directory(path, private=False)
|
|
167
175
|
return os.pathsep.join(selected)
|
|
@@ -670,11 +678,14 @@ class PlatformDirsABC(ABC): # ruff:ignore[too-many-public-methods]
|
|
|
670
678
|
|
|
671
679
|
def find_runtime_file(self, name: str | os.PathLike[str]) -> Path | None:
|
|
672
680
|
"""Like :meth:`find_config_file`, searching :meth:`iter_runtime_paths`."""
|
|
673
|
-
return next(self.
|
|
681
|
+
return next(self._find_runtime_files(name), None)
|
|
674
682
|
|
|
675
683
|
def find_runtime_files(self, name: str | os.PathLike[str]) -> list[Path]:
|
|
676
684
|
"""Like :meth:`find_config_files`, searching :meth:`iter_runtime_paths`."""
|
|
677
|
-
return list(self.
|
|
685
|
+
return list(self._find_runtime_files(name))
|
|
686
|
+
|
|
687
|
+
def _find_runtime_files(self, name: str | os.PathLike[str]) -> Iterator[Path]:
|
|
688
|
+
return self._find_files(lambda dirs: dirs.iter_runtime_paths(), name)
|
|
678
689
|
|
|
679
690
|
def _find_files(
|
|
680
691
|
self, iter_paths: Callable[[PlatformDirsABC], Iterator[Path]], name: str | os.PathLike[str]
|
|
@@ -706,10 +717,10 @@ def _unique(dirs: Iterable[str]) -> Iterator[str]:
|
|
|
706
717
|
""":yield: ``dirs`` in order, skipping any directory already yielded."""
|
|
707
718
|
# Lazy on purpose: under ensure_exists reading a site_*_dir creates it, so draining ``dirs`` up front would
|
|
708
719
|
# create directories for a caller that stops after the first entry.
|
|
709
|
-
seen: set[
|
|
720
|
+
seen: set[Path] = set()
|
|
710
721
|
for path in dirs:
|
|
711
|
-
if path not in seen:
|
|
712
|
-
seen.add(
|
|
722
|
+
if (normalized := Path(path)) not in seen:
|
|
723
|
+
seen.add(normalized)
|
|
713
724
|
yield path
|
|
714
725
|
|
|
715
726
|
|
|
@@ -725,4 +736,4 @@ def _make_private_directories(path: Path) -> None:
|
|
|
725
736
|
|
|
726
737
|
|
|
727
738
|
class RuntimeDirWarning(UserWarning):
|
|
728
|
-
"""Emitted when the Unix
|
|
739
|
+
"""Emitted when the Unix or macOS ``user_runtime_dir`` cannot use ``$XDG_RUNTIME_DIR``."""
|
|
@@ -3,12 +3,24 @@
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
5
|
import re
|
|
6
|
+
import stat
|
|
6
7
|
import sys
|
|
7
|
-
from
|
|
8
|
+
from contextlib import suppress
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from typing import Final, NoReturn
|
|
8
11
|
|
|
9
12
|
from ._xdg import XDGMixin, _expand_user
|
|
10
13
|
from .api import PlatformDirsABC
|
|
11
14
|
|
|
15
|
+
if sys.platform == "win32":
|
|
16
|
+
|
|
17
|
+
def geteuid() -> NoReturn:
|
|
18
|
+
msg = "should only be used on macOS"
|
|
19
|
+
raise RuntimeError(msg)
|
|
20
|
+
|
|
21
|
+
else:
|
|
22
|
+
from os import geteuid
|
|
23
|
+
|
|
12
24
|
|
|
13
25
|
class _MacOSDefaults(PlatformDirsABC): # ruff:ignore[too-many-public-methods]
|
|
14
26
|
"""Default platform directories for macOS without XDG environment variable overrides.
|
|
@@ -19,6 +31,30 @@ class _MacOSDefaults(PlatformDirsABC): # ruff:ignore[too-many-public-methods]
|
|
|
19
31
|
|
|
20
32
|
"""
|
|
21
33
|
|
|
34
|
+
def _optionally_create_directory(self, path: str, *, private: bool) -> None:
|
|
35
|
+
if self.ensure_exists and (shared := Path(_SITE_CACHE)) in (target := Path(path)).parents:
|
|
36
|
+
# Every user can write to /Library/Caches, so another one may have created this entry first.
|
|
37
|
+
entry = shared / target.relative_to(shared).parts[0]
|
|
38
|
+
with suppress(FileExistsError):
|
|
39
|
+
super()._optionally_create_directory(str(entry), private=private)
|
|
40
|
+
if problem := self._shared_entry_problem(entry):
|
|
41
|
+
msg = f"site cache directory {problem}"
|
|
42
|
+
raise PermissionError(msg)
|
|
43
|
+
if target == entry:
|
|
44
|
+
return
|
|
45
|
+
super()._optionally_create_directory(path, private=private)
|
|
46
|
+
|
|
47
|
+
@staticmethod
|
|
48
|
+
def _shared_entry_problem(path: Path) -> str | None:
|
|
49
|
+
info = path.lstat()
|
|
50
|
+
if stat.S_ISLNK(info.st_mode):
|
|
51
|
+
return f"{path} is a symlink"
|
|
52
|
+
if not stat.S_ISDIR(info.st_mode):
|
|
53
|
+
return f"{path} is not a directory"
|
|
54
|
+
if info.st_uid != 0 and info.st_uid != (euid := geteuid()):
|
|
55
|
+
return f"{path} is owned by uid {info.st_uid}, not root or {euid}"
|
|
56
|
+
return None
|
|
57
|
+
|
|
22
58
|
def _base_user_app_support_dir(self) -> str:
|
|
23
59
|
return self._append_app_name_and_version(_expand_user("~/Library/Application Support"), private=True)
|
|
24
60
|
|
|
@@ -53,12 +89,18 @@ class _MacOSDefaults(PlatformDirsABC): # ruff:ignore[too-many-public-methods]
|
|
|
53
89
|
@property
|
|
54
90
|
def _site_cache_dirs(self) -> list[str]:
|
|
55
91
|
path_list = [self._join_app_name_and_version(f"{prefix}/var/cache")] if (prefix := _homebrew_prefix()) else []
|
|
56
|
-
path_list.append(self._join_app_name_and_version(
|
|
92
|
+
path_list.append(self._join_app_name_and_version(_SITE_CACHE))
|
|
57
93
|
return path_list
|
|
58
94
|
|
|
59
95
|
@property
|
|
60
96
|
def site_cache_dir(self) -> str:
|
|
61
|
-
"""Cache directory shared by users, e.g. ``/Library/Caches/$appname/$version``. If we're using a Python binary managed by `Homebrew <https://brew.sh>`_, the directory will be under the Homebrew prefix, e.g. ``$homebrew_prefix/var/cache/$appname/$version``. If `multipath <platformdirs.api.PlatformDirsABC.multipath>` is enabled, and we're in Homebrew, the response is a multi-path string separated by ":", e.g. ``$homebrew_prefix/var/cache/$appname/$version:/Library/Caches/$appname/$version``.
|
|
97
|
+
"""Cache directory shared by users, e.g. ``/Library/Caches/$appname/$version``. If we're using a Python binary managed by `Homebrew <https://brew.sh>`_, the directory will be under the Homebrew prefix, e.g. ``$homebrew_prefix/var/cache/$appname/$version``. If `multipath <platformdirs.api.PlatformDirsABC.multipath>` is enabled, and we're in Homebrew, the response is a multi-path string separated by ":", e.g. ``$homebrew_prefix/var/cache/$appname/$version:/Library/Caches/$appname/$version``.
|
|
98
|
+
|
|
99
|
+
:raises PermissionError: under `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`, if
|
|
100
|
+
``/Library/Caches/$appname`` is a symlink, not a directory or owned by a user other than root and the
|
|
101
|
+
current one.
|
|
102
|
+
|
|
103
|
+
"""
|
|
62
104
|
return self._select_site_dirs(self._site_cache_dirs)
|
|
63
105
|
|
|
64
106
|
@property
|
|
@@ -202,6 +244,10 @@ def _homebrew_prefix() -> str | None:
|
|
|
202
244
|
return None
|
|
203
245
|
|
|
204
246
|
|
|
247
|
+
# Unlike the other /Library site bases, macOS ships this one world-writable and sticky, like /tmp.
|
|
248
|
+
_SITE_CACHE: Final = "/Library/Caches"
|
|
249
|
+
|
|
250
|
+
|
|
205
251
|
__all__ = [
|
|
206
252
|
"MacOS",
|
|
207
253
|
]
|