dycw-utilities 0.138.4__tar.gz → 0.138.6__tar.gz

{dycw_utilities-0.138.4 → dycw_utilities-0.138.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.138.4
+Version: 0.138.6
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12

{dycw_utilities-0.138.4 → dycw_utilities-0.138.6}/pyproject.toml

@@ -105,7 +105,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.138.4"
+version = "0.138.6"
 
 [project.optional-dependencies]
 logging = [
@@ -133,7 +133,7 @@ test = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.138.4"
+current_version = "0.138.6"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

dycw_utilities-0.138.6/src/tests/test_pathlib.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from shutil import copytree
+from typing import TYPE_CHECKING, Self
+
+from hypothesis import HealthCheck, given, settings
+from hypothesis.strategies import DataObject, data, integers, sets
+from pytest import mark, param, raises
+
+from tests.conftest import SKIPIF_CI_AND_WINDOWS
+from utilities.dataclasses import replace_non_sentinel
+from utilities.hypothesis import git_repos, paths, temp_paths
+from utilities.pathlib import (
+    GetRootError,
+    _GetTailDisambiguate,
+    _GetTailEmptyError,
+    _GetTailLengthError,
+    _GetTailNonUniqueError,
+    ensure_suffix,
+    expand_path,
+    get_path,
+    get_root,
+    get_tail,
+    is_sub_path,
+    list_dir,
+    temp_cwd,
+)
+from utilities.sentinel import Sentinel, sentinel
+from utilities.tempfile import TemporaryDirectory
+
+if TYPE_CHECKING:
+    from utilities.types import MaybeCallablePathLike, PathLike
+
+
+class TestEnsureSuffix:
+    @mark.parametrize(
+        ("path", "suffix", "expected"),
+        [
+            param("foo", ".txt", "foo.txt"),
+            param("foo.txt", ".txt", "foo.txt"),
+            param("foo.bar.baz", ".baz", "foo.bar.baz"),
+            param("foo.bar.baz", ".quux", "foo.bar.baz.quux"),
+        ],
+        ids=str,
+    )
+    def test_main(self, *, path: Path, suffix: str, expected: str) -> None:
+        result = str(ensure_suffix(path, suffix))
+        assert result == expected
+
+
+class TestExpandPath:
+    @mark.parametrize(
+        ("path", "expected"),
+        [
+            param("foo", Path("foo")),
+            param("~", Path.home()),
+            param("~/foo", Path.home().joinpath("foo")),
+            param("$HOME", Path.home(), marks=SKIPIF_CI_AND_WINDOWS),
+            param(
+                "$HOME/foo", Path.home().joinpath("foo"), marks=SKIPIF_CI_AND_WINDOWS
+            ),
+        ],
+        ids=str,
+    )
+    def test_main(self, *, path: Path, expected: Path) -> None:
+        result = expand_path(path)
+        assert result == expected
+
+
+class TestGetPath:
+    @given(path=paths())
+    def test_path(self, *, path: Path) -> None:
+        assert get_path(path=path) == path
+
+    @given(path=paths())
+    def test_str(self, *, path: Path) -> None:
+        assert get_path(path=str(path)) == path
+
+    def test_none(self) -> None:
+        assert get_path(path=None) == Path.cwd()
+
+    def test_sentinel(self) -> None:
+        assert get_path(path=sentinel) is sentinel
+
+    @given(path1=paths(), path2=paths())
+    def test_replace_non_sentinel(self, *, path1: Path, path2: Path) -> None:
+        @dataclass(kw_only=True, slots=True)
+        class Example:
+            path: Path = field(default_factory=Path.cwd)
+
+            def replace(
+                self, *, path: MaybeCallablePathLike | Sentinel = sentinel
+            ) -> Self:
+                return replace_non_sentinel(self, path=get_path(path=path))
+
+        obj = Example(path=path1)
+        assert obj.path == path1
+        assert obj.replace().path == path1
+        assert obj.replace(path=path2).path == path2
+
+    @given(path=paths())
+    def test_callable(self, *, path: Path) -> None:
+        assert get_path(path=lambda: path) == path
+
+
+class TestGetRoot:
+    @given(data=data(), repo=git_repos())
+    @settings(
+        max_examples=1, suppress_health_check={HealthCheck.function_scoped_fixture}
+    )
+    def test_git_dir(self, *, data: DataObject, repo: Path) -> None:
+        path = repo.joinpath(data.draw(paths()))
+        path.mkdir(parents=True, exist_ok=True)
+        root = get_root(path=path)
+        expected = repo.resolve()
+        assert root == expected
+
+    @given(data=data(), repo=git_repos())
+    @settings(
+        max_examples=1, suppress_health_check={HealthCheck.function_scoped_fixture}
+    )
+    def test_git_file(self, *, data: DataObject, repo: Path) -> None:
+        path = repo.joinpath(data.draw(paths(min_depth=1)))
+        path.touch()
+        root = get_root(path=path)
+        expected = repo.resolve()
+        assert root == expected
+
+    @given(data=data())
+    @settings(
+        max_examples=1, suppress_health_check={HealthCheck.function_scoped_fixture}
+    )
+    def test_envrc(self, *, data: DataObject, tmp_path: Path) -> None:
+        tmp_path.joinpath(".envrc").touch()
+        path = tmp_path.joinpath(data.draw(paths()))
+        result = get_root(path=path)
+        expected = tmp_path.resolve()
+        assert result == expected
+
+    @given(data=data(), repo=git_repos())
+    @settings(
+        max_examples=1, suppress_health_check={HealthCheck.function_scoped_fixture}
+    )
+    def test_git_and_envrc(self, *, data: DataObject, repo: Path) -> None:
+        repo.joinpath(".envrc").touch()
+        path = repo.joinpath(data.draw(paths()))
+        root = get_root(path=path)
+        expected = repo.resolve()
+        assert root == expected
+
+    @given(data=data(), repo=git_repos())
+    @settings(
+        max_examples=1, suppress_health_check={HealthCheck.function_scoped_fixture}
+    )
+    def test_git_with_envrc_inside(self, *, data: DataObject, repo: Path) -> None:
+        path = repo.joinpath(data.draw(paths(min_depth=1)))
+        path.mkdir(parents=True)
+        path.joinpath(".envrc").touch()
+        root = get_root(path=path)
+        expected = path.resolve()
+        assert root == expected
+
+    @given(data=data(), repo=git_repos())
+    @settings(
+        max_examples=1, suppress_health_check={HealthCheck.function_scoped_fixture}
+    )
+    def test_envrc_with_git_inside(self, *, data: DataObject, repo: Path) -> None:
+        with TemporaryDirectory() as temp:
+            temp.joinpath(".envrc").touch()
+            path = temp.joinpath(data.draw(paths(min_depth=1)))
+            _ = copytree(repo, path)
+            root = get_root(path=path)
+            expected = path.resolve()
+            assert root == expected
+
+    def test_error(self, *, tmp_path: Path) -> None:
+        with raises(GetRootError, match="Unable to determine root from '.*'"):
+            _ = get_root(path=tmp_path)
+
+
+class TestGetTail:
+    @mark.parametrize(
+        ("path", "root", "disambiguate", "expected"),
+        [
+            param("foo/bar/baz", "foo", "raise", Path("bar/baz")),
+            param("foo/bar/baz", "foo/bar", "raise", Path("baz")),
+            param("a/b/c/d/a/b/c/d/e", "b/c", "earlier", Path("d/a/b/c/d/e")),
+            param("a/b/c/d/a/b/c/d/e", "b/c", "later", Path("d/e")),
+        ],
+    )
+    def test_main(
+        self,
+        *,
+        path: PathLike,
+        root: PathLike,
+        disambiguate: _GetTailDisambiguate,
+        expected: Path,
+    ) -> None:
+        tail = get_tail(path, root, disambiguate=disambiguate)
+        assert tail == expected
+
+    def test_error_length(self) -> None:
+        with raises(
+            _GetTailLengthError,
+            match="Unable to get the tail of 'foo' with root of length 2",
+        ):
+            _ = get_tail("foo", "bar/baz")
+
+    def test_error_empty(self) -> None:
+        with raises(
+            _GetTailEmptyError,
+            match="Unable to get the tail of 'foo/bar' with root 'baz'",
+        ):
+            _ = get_tail("foo/bar", "baz")
+
+    def test_error_non_unique(self) -> None:
+        with raises(
+            _GetTailNonUniqueError,
+            match="Path '.*' must contain exactly one tail with root 'b'; got '.*', '.*' and perhaps more",
+        ):
+            _ = get_tail("a/b/c/a/b/c", "b")
+
+
+class TestIsSubPath:
+    @mark.parametrize(
+        ("x", "y", "strict", "expected"),
+        [
+            param("foo", "foo", False, True),
+            param("foo", "foo", True, False),
+            param("foo/bar", "foo", False, True),
+            param("foo/bar", "foo", True, True),
+            param("foo/bar", "foo/baz", False, False),
+            param("foo/bar", "foo/baz", True, False),
+            param("foo", "foo/bar", False, False),
+            param("foo", "foo/bar", True, False),
+        ],
+    )
+    def test_main(
+        self, *, x: PathLike, y: PathLike, strict: bool, expected: bool
+    ) -> None:
+        result = is_sub_path(x, y, strict=strict)
+        assert result is expected
+
+
+class TestListDir:
+    @given(root=temp_paths(), nums=sets(integers(0, 100), max_size=10))
+    def test_main(self, *, root: Path, nums: set[str]) -> None:
+        for n in nums:
+            path = root.joinpath(f"{n}.txt")
+            path.touch()
+        result = list_dir(root)
+        expected = sorted(Path(root, f"{n}.txt") for n in nums)
+        assert result == expected
+
+
+class TestTempCWD:
+    def test_main(self, *, tmp_path: Path) -> None:
+        assert Path.cwd() != tmp_path
+        with temp_cwd(tmp_path):
+            assert Path.cwd() == tmp_path
+        assert Path.cwd() != tmp_path

{dycw_utilities-0.138.4 → dycw_utilities-0.138.6}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.138.4"
+__version__ = "0.138.6"

dycw_utilities-0.138.6/src/utilities/pathlib.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextlib import contextmanager
+from dataclasses import dataclass
+from itertools import chain
+from os import chdir
+from os.path import expandvars
+from pathlib import Path
+from re import IGNORECASE, search
+from subprocess import PIPE, CalledProcessError, check_output
+from typing import TYPE_CHECKING, Literal, assert_never, overload, override
+
+from utilities.errors import ImpossibleCaseError
+from utilities.sentinel import Sentinel, sentinel
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
+    from utilities.types import MaybeCallablePathLike, PathLike
+
+
+PWD = Path.cwd()
+
+
+def ensure_suffix(path: PathLike, suffix: str, /) -> Path:
+    """Ensure a path has a given suffix."""
+    path = Path(path)
+    parts = path.name.split(".")
+    parts = list(chain([parts[0]], (f".{p}" for p in parts[1:])))
+    if (len(parts) == 0) or (parts[-1] != suffix):
+        parts.append(suffix)
+    name = "".join(parts)
+    return path.with_name(name)
+
+
+##
+
+
+def expand_path(path: PathLike, /) -> Path:
+    """Expand a path."""
+    path = str(path)
+    path = expandvars(path)
+    return Path(path).expanduser()
+
+
+##
+
+
+@overload
+def get_path(*, path: MaybeCallablePathLike | None) -> Path: ...
+@overload
+def get_path(*, path: Sentinel) -> Sentinel: ...
+def get_path(
+    *, path: MaybeCallablePathLike | None | Sentinel = sentinel
+) -> Path | None | Sentinel:
+    """Get the path."""
+    match path:
+        case Path() | Sentinel():
+            return path
+        case str():
+            return Path(path)
+        case None:
+            return Path.cwd()
+        case Callable() as func:
+            return get_path(path=func())
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
+def get_root(*, path: MaybeCallablePathLike | None = None) -> Path:
+    """Get the root of a path."""
+    path = get_path(path=path)
+    path_dir = path.parent if path.is_file() else path
+    try:
+        output = check_output(
+            ["git", "rev-parse", "--show-toplevel"],
+            stderr=PIPE,
+            cwd=path_dir,
+            text=True,
+        )
+    except CalledProcessError as error:
+        # newer versions of git report "Not a git repository", whilst older
+        # versions report "not a git repository"
+        if not search("fatal: not a git repository", error.stderr, flags=IGNORECASE):
+            raise  # pragma: no cover
+        root_git = None
+    else:
+        root_git = Path(output.strip("\n")).resolve()
+    all_paths = list(chain([path_dir], path_dir.parents))
+    try:
+        root_envrc = next(
+            p.resolve()
+            for p in all_paths
+            if any(p_i.name == ".envrc" for p_i in p.iterdir())
+        )
+    except StopIteration:
+        root_envrc = None
+    match root_git, root_envrc:
+        case None, None:
+            raise GetRootError(path=path)
+        case Path(), None:
+            return root_git
+        case None, Path():
+            return root_envrc
+        case Path(), Path():
+            if root_git == root_envrc:
+                return root_git
+            if is_sub_path(root_git, root_envrc, strict=True):
+                return root_git
+            if is_sub_path(root_envrc, root_git, strict=True):
+                return root_envrc
+            raise ImpossibleCaseError(  # pragma: no cover
+                case=[f"{root_git=}", f"{root_envrc=}"]
+            )
+        case _ as never:
+            assert_never(never)
+
+
+@dataclass(kw_only=True, slots=True)
+class GetRootError(Exception):
+    path: PathLike
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to determine root from {str(self.path)!r}"
+
+
+##
+
+
+type _GetTailDisambiguate = Literal["raise", "earlier", "later"]
+
+
+def get_tail(
+    path: PathLike, root: PathLike, /, *, disambiguate: _GetTailDisambiguate = "raise"
+) -> Path:
+    """Get the tail of a path following a root match."""
+    path_parts, root_parts = [Path(p).parts for p in [path, root]]
+    len_path, len_root = map(len, [path_parts, root_parts])
+    if len_root > len_path:
+        raise _GetTailLengthError(path=path, root=root, len_root=len_root)
+    candidates = {
+        i + len_root: path_parts[i : i + len_root]
+        for i in range(len_path + 1 - len_root)
+    }
+    matches = {k: v for k, v in candidates.items() if v == root_parts}
+    match len(matches), disambiguate:
+        case 0, _:
+            raise _GetTailEmptyError(path=path, root=root)
+        case 1, _:
+            return _get_tail_core(path, next(iter(matches)))
+        case _, "raise":
+            first, second, *_ = matches
+            raise _GetTailNonUniqueError(
+                path=path,
+                root=root,
+                first=_get_tail_core(path, first),
+                second=_get_tail_core(path, second),
+            )
+        case _, "earlier":
+            return _get_tail_core(path, next(iter(matches)))
+        case _, "later":
+            return _get_tail_core(path, next(iter(reversed(matches))))
+        case _ as never:
+            assert_never(never)
+
+
+def _get_tail_core(path: PathLike, i: int, /) -> Path:
+    parts = Path(path).parts
+    return Path(*parts[i:])
+
+
+@dataclass(kw_only=True, slots=True)
+class GetTailError(Exception):
+    path: PathLike
+    root: PathLike
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetTailLengthError(GetTailError):
+    len_root: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to get the tail of {str(self.path)!r} with root of length {self.len_root}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetTailEmptyError(GetTailError):
+    @override
+    def __str__(self) -> str:
+        return (
+            f"Unable to get the tail of {str(self.path)!r} with root {str(self.root)!r}"
+        )
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetTailNonUniqueError(GetTailError):
+    first: Path
+    second: Path
+
+    @override
+    def __str__(self) -> str:
+        return f"Path {str(self.path)!r} must contain exactly one tail with root {str(self.root)!r}; got {str(self.first)!r}, {str(self.second)!r} and perhaps more"
+
+
+##
+
+
+def is_sub_path(x: PathLike, y: PathLike, /, *, strict: bool = False) -> bool:
+    """Check if a path is a sub path of another."""
+    x, y = [Path(i).resolve() for i in [x, y]]
+    return x.is_relative_to(y) and not (strict and y.is_relative_to(x))
+
+
+##
+
+
+def list_dir(path: PathLike, /) -> Sequence[Path]:
+    """List the contents of a directory."""
+    return sorted(Path(path).iterdir())
+
+
+##
+
+
+@contextmanager
+def temp_cwd(path: PathLike, /) -> Iterator[None]:
+    """Context manager with temporary current working directory set."""
+    prev = Path.cwd()
+    chdir(path)
+    try:
+        yield
+    finally:
+        chdir(prev)
+
+
+__all__ = [
+    "PWD",
+    "GetTailError",
+    "ensure_suffix",
+    "expand_path",
+    "get_path",
+    "get_tail",
+    "is_sub_path",
+    "list_dir",
+    "temp_cwd",
+]

dycw_utilities-0.138.4/src/tests/test_pathlib.py

@@ -1,145 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import TYPE_CHECKING, Self
-
-from hypothesis import given, settings
-from hypothesis.strategies import integers, sets
-from pytest import mark, param, raises
-
-from tests.conftest import SKIPIF_CI_AND_WINDOWS
-from utilities.dataclasses import replace_non_sentinel
-from utilities.hypothesis import git_repos, paths, temp_paths
-from utilities.pathlib import (
-    GetRootError,
-    ensure_suffix,
-    expand_path,
-    get_path,
-    get_root,
-    list_dir,
-    temp_cwd,
-)
-from utilities.sentinel import Sentinel, sentinel
-
-if TYPE_CHECKING:
-    from utilities.types import MaybeCallablePathLike
-
-
-class TestEnsureSuffix:
-    @mark.parametrize(
-        ("path", "suffix", "expected"),
-        [
-            param("foo", ".txt", "foo.txt"),
-            param("foo.txt", ".txt", "foo.txt"),
-            param("foo.bar.baz", ".baz", "foo.bar.baz"),
-            param("foo.bar.baz", ".quux", "foo.bar.baz.quux"),
-        ],
-        ids=str,
-    )
-    def test_main(self, *, path: Path, suffix: str, expected: str) -> None:
-        result = str(ensure_suffix(path, suffix))
-        assert result == expected
-
-
-class TestExpandPath:
-    @mark.parametrize(
-        ("path", "expected"),
-        [
-            param("foo", Path("foo")),
-            param("~", Path.home()),
-            param("~/foo", Path.home().joinpath("foo")),
-            param("$HOME", Path.home(), marks=SKIPIF_CI_AND_WINDOWS),
-            param(
-                "$HOME/foo", Path.home().joinpath("foo"), marks=SKIPIF_CI_AND_WINDOWS
-            ),
-        ],
-        ids=str,
-    )
-    def test_main(self, *, path: Path, expected: Path) -> None:
-        result = expand_path(path)
-        assert result == expected
-
-
-class TestGetPath:
-    @given(path=paths())
-    def test_path(self, *, path: Path) -> None:
-        assert get_path(path=path) == path
-
-    @given(path=paths())
-    def test_str(self, *, path: Path) -> None:
-        assert get_path(path=str(path)) == path
-
-    def test_none(self) -> None:
-        assert get_path(path=None) == Path.cwd()
-
-    def test_sentinel(self) -> None:
-        assert get_path(path=sentinel) is sentinel
-
-    @given(path1=paths(), path2=paths())
-    def test_replace_non_sentinel(self, *, path1: Path, path2: Path) -> None:
-        @dataclass(kw_only=True, slots=True)
-        class Example:
-            path: Path = field(default_factory=Path.cwd)
-
-            def replace(
-                self, *, path: MaybeCallablePathLike | Sentinel = sentinel
-            ) -> Self:
-                return replace_non_sentinel(self, path=get_path(path=path))
-
-        obj = Example(path=path1)
-        assert obj.path == path1
-        assert obj.replace().path == path1
-        assert obj.replace(path=path2).path == path2
-
-    @given(path=paths())
-    def test_callable(self, *, path: Path) -> None:
-        assert get_path(path=lambda: path) == path
-
-
-class TestGetRoot:
-    @given(repo=git_repos())
-    @settings(max_examples=1)
-    def test_git(self, *, repo: Path) -> None:
-        root = get_root(path=repo)
-        expected = repo.resolve()
-        assert root == expected
-
-    @given(root=temp_paths())
-    @settings(max_examples=1)
-    def test_envrc(self, *, root: Path) -> None:
-        root.joinpath(".envrc").touch()
-        result = get_root(path=root)
-        assert result == root
-
-    @given(root=temp_paths())
-    @settings(max_examples=1)
-    def test_envrc_from_inside(self, *, root: Path) -> None:
-        root.joinpath(".envrc").touch()
-        path = root.joinpath("foo", "bar", "baz")
-        path.mkdir(parents=True)
-        result = get_root(path=path)
-        assert result == root
-
-    def test_error(self, *, tmp_path: Path) -> None:
-        with raises(GetRootError, match="Unable to determine root from '.*'"):
-            _ = get_root(path=tmp_path)
-
-
-class TestListDir:
-    @given(root=temp_paths(), nums=sets(integers(0, 100), max_size=10))
-    def test_main(self, *, root: Path, nums: set[str]) -> None:
-        for n in nums:
-            path = root.joinpath(f"{n}.txt")
-            path.touch()
-        result = list_dir(root)
-        expected = sorted(Path(root, f"{n}.txt") for n in nums)
-        assert result == expected
-
-
-class TestTempCWD:
-    def test_main(self, *, tmp_path: Path) -> None:
-        assert Path.cwd() != tmp_path
-        with temp_cwd(tmp_path):
-            assert Path.cwd() == tmp_path
-        assert Path.cwd() != tmp_path