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.
Files changed (29) hide show
  1. {platformdirs-4.13.7 → platformdirs-4.14.2}/PKG-INFO +1 -1
  2. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/__init__.py +126 -54
  3. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/_xdg.py +21 -8
  4. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/api.py +21 -10
  5. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/macos.py +49 -3
  6. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/unix.py +102 -25
  7. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/version.py +2 -2
  8. {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/conftest.py +17 -1
  9. {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_api.py +62 -10
  10. {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_macos.py +165 -0
  11. {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_main.py +1 -1
  12. {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_testing.py +1 -1
  13. {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_unix.py +486 -36
  14. {platformdirs-4.13.7 → platformdirs-4.14.2}/.gitignore +0 -0
  15. {platformdirs-4.13.7 → platformdirs-4.14.2}/LICENSE +0 -0
  16. {platformdirs-4.13.7 → platformdirs-4.14.2}/pyproject.toml +0 -0
  17. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/__main__.py +0 -0
  18. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/android.py +0 -0
  19. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/ios.py +0 -0
  20. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/py.typed +0 -0
  21. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/pytest_plugin.py +0 -0
  22. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/testing.py +0 -0
  23. {platformdirs-4.13.7 → platformdirs-4.14.2}/src/platformdirs/windows.py +0 -0
  24. {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_android.py +0 -0
  25. {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_comp_with_appdirs.py +0 -0
  26. {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_ios.py +0 -0
  27. {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_pytest_plugin.py +0 -0
  28. {platformdirs-4.13.7 → platformdirs-4.14.2}/tests/test_windows.py +0 -0
  29. {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.13.7
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
- """:returns: documents directory tied to the user"""
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
- def user_pictures_dir() -> str:
343
- """:returns: pictures directory tied to the user"""
344
- return PlatformDirs().user_pictures_dir
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
- """:returns: videos directory tied to the user"""
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
- def user_music_dir() -> str:
353
- """:returns: music directory tied to the user"""
354
- return PlatformDirs().user_music_dir
364
+ """
365
+ return PlatformDirs(ensure_exists=ensure_exists).user_videos_dir
355
366
 
356
367
 
357
- def user_desktop_dir() -> str:
358
- """:returns: desktop directory tied to the user"""
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
- def user_projects_dir() -> str:
363
- """:returns: projects directory tied to the user"""
364
- return PlatformDirs().user_projects_dir
373
+ """
374
+ return PlatformDirs(ensure_exists=ensure_exists).user_music_dir
365
375
 
366
376
 
367
- def user_publicshare_dir() -> str:
368
- """:returns: public share directory tied to the user"""
369
- return PlatformDirs().user_publicshare_dir
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 user_templates_dir() -> str:
373
- """:returns: templates directory tied to the user"""
374
- return PlatformDirs().user_templates_dir
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
- """:returns: documents path tied to the user"""
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
- def user_pictures_path() -> Path:
811
- """:returns: pictures path tied to the user"""
812
- return PlatformDirs().user_pictures_path
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
- """:returns: videos path tied to the user"""
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
- def user_music_path() -> Path:
821
- """:returns: music path tied to the user"""
822
- return PlatformDirs().user_music_path
868
+ """
869
+ return PlatformDirs(ensure_exists=ensure_exists).user_videos_path
823
870
 
824
871
 
825
- def user_desktop_path() -> Path:
826
- """:returns: desktop path tied to the user"""
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
- def user_projects_path() -> Path:
831
- """:returns: projects path tied to the user"""
832
- return PlatformDirs().user_projects_path
877
+ """
878
+ return PlatformDirs(ensure_exists=ensure_exists).user_music_path
833
879
 
834
880
 
835
- def user_publicshare_path() -> Path:
836
- """:returns: public share path tied to the user"""
837
- return PlatformDirs().user_publicshare_path
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 user_templates_path() -> Path:
841
- """:returns: templates path tied to the user"""
842
- return PlatformDirs().user_templates_path
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
- return self._append_app_name_and_version(path, private=True)
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 an empty ``HOME`` as unset on POSIX.
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 / for an empty HOME; Rust's std::env::home_dir treats it as unset too
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.startswith("~"):
186
- msg = f"could not determine the home directory for {path!r}, set HOME or an absolute XDG variable"
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 running as root (uid 0).
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
- with suppress(FileExistsError):
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._find_files(lambda dirs: dirs.iter_runtime_paths(), name), None)
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._find_files(lambda dirs: dirs.iter_runtime_paths(), name))
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[str] = set()
720
+ seen: set[Path] = set()
710
721
  for path in dirs:
711
- if path not in seen:
712
- seen.add(path)
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 :attr:`~platformdirs.unix.Unix.user_runtime_dir` cannot use ``$XDG_RUNTIME_DIR``."""
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 typing import Final
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("/Library/Caches"))
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
  ]