platformdirs 4.12.2__tar.gz → 4.12.4__tar.gz

{platformdirs-4.12.2 → platformdirs-4.12.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: platformdirs
-Version: 4.12.2
+Version: 4.12.4
 Summary: A small Python package for determining appropriate platform-specific dirs, e.g. a `user data dir`.
 Project-URL: Changelog, https://platformdirs.readthedocs.io/en/latest/changelog.html
 Project-URL: Documentation, https://platformdirs.readthedocs.io

{platformdirs-4.12.2 → platformdirs-4.12.4}/src/platformdirs/api.py

@@ -555,10 +555,12 @@ class PlatformDirsABC(ABC):  # ruff:ignore[too-many-public-methods]
             yield Path(path)
 
     def place_config_file(self, name: str | os.PathLike[str]) -> Path:
-        """Return the path of ``name`` under `user_config_dir`, creating the missing directories on the way.
+        """Return the path of ``name`` under `user_config_path`, creating the missing directories on the way.
 
         Each directory it creates, including the user directory itself, gets mode ``0o700`` whether or not
-        `ensure_exists` is set; directories that already exist keep their mode. It does not create the file.
+        `ensure_exists` is set; directories that already exist keep their mode. On Unix, root with `use_site_for_root`
+        places the file under the site directory instead and creates the missing directories with the default mode, so
+        other users can read them. It does not create the file.
 
         :param name: file path relative to the user directory, e.g. ``"sub/app.toml"``.
 
@@ -566,41 +568,47 @@ class PlatformDirsABC(ABC):  # ruff:ignore[too-many-public-methods]
         :raises RuntimeError: if the user directory starts with ``~`` because the home directory is unknown.
 
         """
-        return self._place_file(lambda dirs: dirs.user_config_dir, name)
+        return self._place_file(lambda dirs: dirs.user_config_path, name)
 
     def place_data_file(self, name: str | os.PathLike[str]) -> Path:
-        """Like `place_config_file`, under `user_data_dir`."""
-        return self._place_file(lambda dirs: dirs.user_data_dir, name)
+        """Like `place_config_file`, under `user_data_path`."""
+        return self._place_file(lambda dirs: dirs.user_data_path, name)
 
     def place_cache_file(self, name: str | os.PathLike[str]) -> Path:
-        """Like `place_config_file`, under `user_cache_dir`."""
-        return self._place_file(lambda dirs: dirs.user_cache_dir, name)
+        """Like `place_config_file`, under `user_cache_path`."""
+        return self._place_file(lambda dirs: dirs.user_cache_path, name)
 
     def place_state_file(self, name: str | os.PathLike[str]) -> Path:
-        """Like `place_config_file`, under `user_state_dir`."""
-        return self._place_file(lambda dirs: dirs.user_state_dir, name)
+        """Like `place_config_file`, under `user_state_path`."""
+        return self._place_file(lambda dirs: dirs.user_state_path, name)
 
     def place_log_file(self, name: str | os.PathLike[str]) -> Path:
-        """Like `place_config_file`, under `user_log_dir`."""
-        return self._place_file(lambda dirs: dirs.user_log_dir, name)
+        """Like `place_config_file`, under `user_log_path`."""
+        return self._place_file(lambda dirs: dirs.user_log_path, name)
 
     def place_runtime_file(self, name: str | os.PathLike[str]) -> Path:
-        """Like `place_config_file`, under `user_runtime_dir`.
+        """Like `place_config_file`, under `user_runtime_path`.
 
         :raises PermissionError: on Unix, if another user owns the temporary fallback directory.
 
         """
-        return self._place_file(lambda dirs: dirs.user_runtime_dir, name)
+        return self._place_file(lambda dirs: dirs.user_runtime_path, name)
 
-    def _place_file(self, user_dir: Callable[[PlatformDirsABC], str], name: str | os.PathLike[str]) -> Path:
+    def _place_file(self, user_path: Callable[[PlatformDirsABC], Path], name: str | os.PathLike[str]) -> Path:
         _ensure_inside_base("name", relative := os.fspath(name))
         if not Path(relative).parts:
             msg = f"name must point to a file, got {relative!r}"
             raise ValueError(msg)
         # Under ensure_exists the lookup itself would create the user directory with the default mode, not 0o700.
         (lookup := copy(self)).ensure_exists = False
-        _ensure_home_known(directory := user_dir(lookup))
-        _make_private_directories((path := Path(directory, relative)).parent)
+        # Under multipath *_dir joins the site directories with os.pathsep, so place under the single *_path.
+        _ensure_home_known(str(directory := user_path(lookup)))
+        path = directory / relative
+        if self._use_site:
+            # Site directories keep the default mode, as under ensure_exists, so other users can still read them.
+            path.parent.mkdir(parents=True, exist_ok=True)
+        else:
+            _make_private_directories(path.parent)
         return path
 
     def find_config_file(self, name: str | os.PathLike[str]) -> Path | None:

{platformdirs-4.12.2 → platformdirs-4.12.4}/src/platformdirs/testing.py

@@ -11,7 +11,7 @@ from platformdirs.api import PlatformDirsABC
 
 if TYPE_CHECKING:
     import os
-    from collections.abc import Iterator
+    from collections.abc import Generator
 
 _APP_KINDS: Final[frozenset[str]] = frozenset({
     "user_data",
@@ -31,7 +31,7 @@ _APP_KINDS: Final[frozenset[str]] = frozenset({
 
 
 @contextmanager
-def isolated_dirs(root: str | os.PathLike[str]) -> Iterator[Path]:
+def isolated_dirs(root: str | os.PathLike[str]) -> Generator[Path, None, None]:
     """Resolve every directory of :data:`~platformdirs.PlatformDirs` under ``root`` while the context is active.
 
     Each kind maps to ``<root>/<kind>``, where ``kind`` is the property name without ``_dir``, such as ``user_config``.

{platformdirs-4.12.2 → platformdirs-4.12.4}/src/platformdirs/unix.py

@@ -275,7 +275,7 @@ class Unix(XDGMixin, _UnixDefaults):
         if not (path := _xdg_dir("XDG_RUNTIME_DIR")):
             reason = "XDG_RUNTIME_DIR is not set"
         else:
-            with suppress(FileExistsError):
+            with suppress(OSError):
                 self._optionally_create_directory(path, private=True)
             if not (problem := _runtime_dir_problem(path)):
                 return self._append_app_name_and_version(path, private=True)

{platformdirs-4.12.2 → platformdirs-4.12.4}/src/platformdirs/version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '4.12.2'
-__version_tuple__ = version_tuple = (4, 12, 2)
+__version__ = version = '4.12.4'
+__version_tuple__ = version_tuple = (4, 12, 4)
 
 __commit_id__ = commit_id = None

{platformdirs-4.12.2 → platformdirs-4.12.4}/tests/test_api.py

@@ -475,6 +475,19 @@ def test_find_config_file_accepts_nested_path_like(dirs: Unix, config_paths: lis
     assert dirs.find_config_file(Path("sub", "app.toml")) == nested
 
 
+@pytest.mark.parametrize("multipath", [pytest.param(True, id="multipath"), pytest.param(False, id="single-path")])
+@pytest.mark.parametrize("kind", [pytest.param(kind, id=kind) for kind in ("config", "data")])
+def test_find_file_finds_root_placed_file_in_first_site_dir(
+    dirs: Unix, mocker: MockerFixture, kind: str, multipath: bool
+) -> None:
+    mocker.patch("platformdirs.unix.getuid", return_value=0)
+    dirs.use_site_for_root = True
+    dirs.multipath = multipath
+    getattr(dirs, f"place_{kind}_file")("app.toml").touch()
+    first_site_dir = os.environ[f"XDG_{kind.upper()}_DIRS"].split(os.pathsep)[0]
+    assert getattr(dirs, f"find_{kind}_file")("app.toml") == Path(first_site_dir, "find-files-test", "app.toml")
+
+
 @pytest.mark.parametrize("suffix", _SUFFIXES)
 @pytest.mark.parametrize("kind", _KINDS)
 def test_find_creates_no_directory_with_ensure_exists(dirs: Unix, tmp_path: Path, kind: str, suffix: str) -> None:

{platformdirs-4.12.2 → platformdirs-4.12.4}/tests/test_unix.py

@@ -400,6 +400,10 @@ _PROBLEMS: typing.Final = {
     "mode-755": "has mode 0755, not 0700",
     "mode-500": "has mode 0500, not 0700",
 }
+_UNREACHABLE: typing.Final = {
+    "file": "Not a directory",
+    "symlink-loop": "Too many levels of symbolic links",
+}
 _DEFAULT_PREFIXES: typing.Final = {
     "linux": "run/user",
     "freebsd": "var/run/user",
@@ -472,17 +476,20 @@ def test_runtime_dir_xdg_runtime_dir_of_other_user_warns(
 
 @_POSIX_ONLY
 @pytest.mark.usefixtures("runtime_uid")
+@pytest.mark.parametrize("kind", list(_UNREACHABLE))
+@pytest.mark.parametrize("ensure_exists", [pytest.param(False, id="lazy"), pytest.param(True, id="ensure-exists")])
 def test_runtime_dir_unreachable_xdg_runtime_dir_warns(
-    runtime_temp_dir: Path, temp_dir: Path, monkeypatch: pytest.MonkeyPatch
+    runtime_temp_dir: Path, temp_dir: Path, monkeypatch: pytest.MonkeyPatch, kind: str, ensure_exists: bool
 ) -> None:
-    (blocker := runtime_temp_dir / "blocker").touch()
+    _create(blocker := runtime_temp_dir / "blocker", kind)
     monkeypatch.setenv("XDG_RUNTIME_DIR", str(blocker / "session"))
     with pytest.warns(RuntimeDirWarning) as record:
-        _ = Unix(appname="app").user_runtime_dir
+        assert Unix(appname="app", ensure_exists=ensure_exists).user_runtime_dir == str(temp_dir / "app")
     expected: typing.Final = (
-        f"XDG_RUNTIME_DIR {blocker / 'session'} cannot be checked: Not a directory, falling back to {temp_dir}"
+        f"XDG_RUNTIME_DIR {blocker / 'session'} cannot be checked: {_UNREACHABLE[kind]}, falling back to {temp_dir}"
     )
     assert [str(warning.message) for warning in record] == [expected]
+    assert (temp_dir / "app").is_dir() is ensure_exists
 
 
 @_POSIX_ONLY
@@ -602,6 +609,8 @@ def _create(path: Path, kind: str) -> None:
             path.symlink_to(target)
         case "file":
             path.touch()
+        case "symlink-loop":
+            path.symlink_to(path)
 
 
 def test_ensure_exists_creates_folder(monkeypatch: pytest.MonkeyPatch, posix_tmp_path: str) -> None:
@@ -1226,6 +1235,23 @@ def test_user_path_site_redirect(
     assert getattr(dirs, prop) == Path(base) / ("applications" if prop == "user_applications_path" else "foo/1.0")
 
 
+@pytest.mark.skipif(sys.platform == "win32", reason="Windows ignores POSIX mode bits")
+@pytest.mark.parametrize("uid", [pytest.param(0, id="root"), pytest.param(1000, id="user")], indirect=True)
+@pytest.mark.parametrize("kind", ["config", "data"])
+def test_place_file_with_use_site_for_root_keeps_site_dir_readable(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, uid: int, kind: str
+) -> None:
+    monkeypatch.setenv(f"XDG_{kind.upper()}_HOME", str(tmp_path / "user"))
+    monkeypatch.setenv(f"XDG_{kind.upper()}_DIRS", str(tmp_path / "site"))
+    getattr(Unix(appname="foo", use_site_for_root=True), f"place_{kind}_file")("sub/app.toml")
+    (reference := tmp_path / "reference").mkdir()
+    expected: typing.Final = stat.S_IMODE(reference.stat().st_mode) if uid == 0 else 0o700
+    created: typing.Final = (tmp_path / ("site" if uid == 0 else "user")).rglob("*")
+    assert {path.name: oct(stat.S_IMODE(path.stat().st_mode)) for path in created} == dict.fromkeys(
+        ["foo", "sub"], oct(expected)
+    )
+
+
 @pytest.fixture
 def uid(request: pytest.FixtureRequest, mocker: MockerFixture) -> int:
     value: typing.Final = typing.cast("int", request.param)