dycw-utilities 0.127.0__tar.gz → 0.128.0__tar.gz

{dycw_utilities-0.127.0 → dycw_utilities-0.128.0}/PKG-INFO

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

{dycw_utilities-0.127.0 → dycw_utilities-0.128.0}/pyproject.toml

@@ -94,7 +94,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.127.0"
+version = "0.128.0"
 
 [project.optional-dependencies]
 test = [
@@ -334,7 +334,7 @@ zzz-test-zoneinfo = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.127.0"
+current_version = "0.128.0"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"
@@ -447,6 +447,7 @@ filterwarnings = [
   "ignore:Task .* without outputs has no custom complete.* method:UserWarning",  # luigi
   "ignore:There is no current event loop:DeprecationWarning",  # eventkit
   "ignore:Using fork.* can cause Polars to deadlock in the child process:RuntimeWarning",  # polars/pqdm
+  "ignore:coroutine 'AsyncConnection.close' was never awaited:RuntimeWarning",
   "ignore:loop is closed:ResourceWarning",  # redis
   "ignore:unclosed <StreamWriter .*>:ResourceWarning",  # redis
   "ignore:unclosed <socket.*socket .*>:ResourceWarning",  # redis

{dycw_utilities-0.127.0 → dycw_utilities-0.128.0}/src/tests/test_asyncio.py

@@ -15,7 +15,6 @@ from hypothesis.strategies import (
     booleans,
     data,
     integers,
-    just,
     lists,
     none,
     permutations,
@@ -71,6 +70,7 @@ from utilities.hypothesis import sentinels, text_ascii
 from utilities.iterables import one, unique_everseen
 from utilities.pytest import skipif_windows
 from utilities.sentinel import Sentinel, sentinel
+from utilities.text import unique_str
 from utilities.timer import Timer
 
 if TYPE_CHECKING:
@@ -198,7 +198,6 @@ class TestEnhancedTaskGroup:
             assert looper.running
         assert not looper.running
 
-    @mark.flaky
     async def test_max_tasks_disabled(self) -> None:
         with Timer() as timer:
             async with EnhancedTaskGroup() as tg:
@@ -625,7 +624,7 @@ class TestInfiniteLooper:
         ):
             raise _InfiniteLooperDefaultEventError(looper=looper)
 
-    @given(logger=just("logger") | none())
+    @given(log=booleans())
     @mark.parametrize(("sleep_restart", "desc"), sleep_restart_cases)
     @settings(suppress_health_check={HealthCheck.function_scoped_fixture})
     async def test_error_upon_initialize(
@@ -633,7 +632,7 @@ class TestInfiniteLooper:
         *,
         sleep_restart: DurationOrEveryDuration,
         desc: str,
-        logger: str | None,
+        log: bool,
         caplog: LogCaptureFixture,
     ) -> None:
         class CustomError(Exception): ...
@@ -650,15 +649,19 @@ class TestInfiniteLooper:
 
         async with (
             timeout(1.0),
-            Example(sleep_core=0.1, sleep_restart=sleep_restart, logger=logger),
+            Example(
+                sleep_core=0.1,
+                sleep_restart=sleep_restart,
+                logger=unique_str() if log else None,
+            ),
         ):
             ...
-        if logger is not None:
+        if log:
             message = caplog.messages[0]
             expected = f"'Example' encountered 'CustomError()' whilst initializing; sleeping {desc}..."
             assert message == expected
 
-    @given(logger=just("logger") | none())
+    @given(log=booleans())
     @mark.parametrize(("sleep_restart", "desc"), sleep_restart_cases)
     @settings(suppress_health_check={HealthCheck.function_scoped_fixture})
     async def test_error_upon_core(
@@ -666,7 +669,7 @@ class TestInfiniteLooper:
         *,
         sleep_restart: DurationOrEveryDuration,
         desc: str,
-        logger: str | None,
+        log: bool,
         caplog: LogCaptureFixture,
     ) -> None:
         class CustomError(Exception): ...
@@ -679,15 +682,19 @@ class TestInfiniteLooper:
 
         async with (
             timeout(1.0),
-            Example(sleep_core=0.1, sleep_restart=sleep_restart, logger=logger),
+            Example(
+                sleep_core=0.1,
+                sleep_restart=sleep_restart,
+                logger=unique_str() if log else None,
+            ),
         ):
             ...
-        if logger is not None:
+        if log:
             message = caplog.messages[0]
             expected = f"'Example' encountered 'CustomError()'; sleeping {desc}..."
             assert message == expected
 
-    @given(logger=just("logger") | none())
+    @given(log=booleans())
     @mark.parametrize(("sleep_restart", "desc"), sleep_restart_cases)
     @settings(suppress_health_check={HealthCheck.function_scoped_fixture})
     async def test_error_upon_teardown(
@@ -695,7 +702,7 @@ class TestInfiniteLooper:
         *,
         sleep_restart: DurationOrEveryDuration,
         desc: str,
-        logger: str | None,
+        log: bool,
         caplog: LogCaptureFixture,
     ) -> None:
         class Custom1Error(Exception): ...
@@ -724,14 +731,18 @@ class TestInfiniteLooper:
 
         async with (
             timeout(1.0),
-            Example(sleep_core=0.1, sleep_restart=sleep_restart, logger=logger),
+            Example(
+                sleep_core=0.1,
+                sleep_restart=sleep_restart,
+                logger=unique_str() if log else None,
+            ),
         ):
             ...
-        if logger is not None:
+        if log:
             expected = f"'Example' encountered 'Custom2Error()' whilst tearing down; sleeping {desc}..."
             assert expected in caplog.messages
 
-    @given(logger=just("logger") | none())
+    @given(log=booleans())
     @mark.parametrize(("sleep_restart", "desc"), sleep_restart_cases)
     @settings(suppress_health_check={HealthCheck.function_scoped_fixture})
     async def test_error_group_upon_others(
@@ -739,7 +750,7 @@ class TestInfiniteLooper:
         *,
         sleep_restart: DurationOrEveryDuration,
         desc: str,
-        logger: str | None,
+        log: bool,
         caplog: LogCaptureFixture,
     ) -> None:
         class CustomError(Exception): ...
@@ -770,10 +781,14 @@ class TestInfiniteLooper:
 
         async with (
             timeout(1.0),
-            Example(sleep_core=0.05, sleep_restart=sleep_restart, logger=logger),
+            Example(
+                sleep_core=0.05,
+                sleep_restart=sleep_restart,
+                logger=unique_str() if log else None,
+            ),
         ):
             ...
-        if logger is not None:
+        if log:
             message = caplog.messages[0]
             expected = f"""\
 'Example' encountered 1 error(s):
@@ -867,11 +882,10 @@ class TestInfiniteQueueLooper:
             await looper.run_until_empty(stop=True)
         assert looper.empty()
 
-    @given(logger=just("logger") | none())
-    @mark.flaky
+    @given(log=booleans())
     @settings(suppress_health_check={HealthCheck.function_scoped_fixture})
     async def test_error_process_items(
-        self, *, logger: str | None, caplog: LogCaptureFixture
+        self, *, log: bool, caplog: LogCaptureFixture
     ) -> None:
         class CustomError(Exception): ...
 
@@ -883,9 +897,12 @@ class TestInfiniteQueueLooper:
             async def _process_queue(self) -> None:
                 raise CustomError
 
-        async with timeout(1.0), Example(sleep_core=0.05, logger=logger) as looper:
+        async with (
+            timeout(1.0),
+            Example(sleep_core=0.05, logger=unique_str() if log else None) as looper,
+        ):
             looper.put_left_nowait(1)
-        if logger is not None:
+        if log:
             message = caplog.messages[0]
             expected = "'Example' encountered 'CustomError()'; sleeping for 0:01:00..."
             assert message == expected

{dycw_utilities-0.127.0 → dycw_utilities-0.128.0}/src/tests/test_asyncio_classes/loopers.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, Any, Literal, override
 
 from pytest import approx
 
+from tests.conftest import IS_CI
 from utilities.asyncio import Looper
 from utilities.contextlib import suppress_super_object_attribute_error
 from utilities.datetime import MILLISECOND
@@ -16,7 +17,7 @@ if TYPE_CHECKING:
 
 _FREQ: Duration = 10 * MILLISECOND
 _BACKOFF: Duration = 100 * MILLISECOND
-_REL: float = 0.75
+_REL: float = 2.0 if IS_CI else 0.25
 
 
 # assert

{dycw_utilities-0.127.0 → dycw_utilities-0.128.0}/src/tests/test_hypothesis.py

@@ -4,7 +4,6 @@ import datetime as dt
 from itertools import pairwise
 from pathlib import Path
 from re import search
-from subprocess import PIPE, check_output
 from typing import TYPE_CHECKING, Any, cast
 
 from hypothesis import HealthCheck, Phase, assume, given, settings
@@ -45,7 +44,6 @@ from utilities.datetime import (
     parse_two_digit_year,
 )
 from utilities.functions import ensure_int
-from utilities.git import _GIT_REMOTE_GET_URL_ORIGIN, _GIT_REV_PARSE_ABBREV_REV_HEAD
 from utilities.hypothesis import (
     _SQLALCHEMY_ENGINE_DIALECTS,
     MaybeSearchStrategy,
@@ -590,21 +588,9 @@ class TestGitRepos:
     @given(data=data())
     @settings_with_reduced_examples()
     def test_main(self, *, data: DataObject) -> None:
-        branch = data.draw(text_ascii(min_size=1) | none())
-        remote = data.draw(text_ascii(min_size=1) | none())
-        root = data.draw(git_repos(branch=branch, remote=remote))
+        root = data.draw(git_repos())
         files = set(root.iterdir())
         assert Path(root, ".git") in files
-        if branch is not None:
-            output = check_output(
-                _GIT_REV_PARSE_ABBREV_REV_HEAD, stderr=PIPE, cwd=root, text=True
-            )
-            assert output.strip("\n") == branch
-        if remote is not None:
-            output = check_output(
-                _GIT_REMOTE_GET_URL_ORIGIN, stderr=PIPE, cwd=root, text=True
-            )
-            assert output.strip("\n") == remote
 
 
 class TestHashables:

dycw_utilities-0.128.0/src/tests/test_pathlib.py

@@ -0,0 +1,124 @@
+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 utilities.dataclasses import replace_non_sentinel
+from utilities.hypothesis import git_repos, paths, temp_paths
+from utilities.pathlib import (
+    GetRootError,
+    ensure_suffix,
+    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 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

{dycw_utilities-0.127.0 → dycw_utilities-0.128.0}/src/tests/test_python_dotenv.py

@@ -57,10 +57,10 @@ class TestLoadSettings:
             key_env = data.draw(sampled_from(["key", "KEY"]))
             value_env = data.draw(text_ascii())
             with temp_environ({key_env: value_env}):
-                settings = load_settings(SettingsUse, cwd=root)
+                settings = load_settings(SettingsUse, path=root)
             exp_value = value_env
         else:
-            settings = load_settings(SettingsUse, cwd=root)
+            settings = load_settings(SettingsUse, path=root)
             exp_value = value_file
 
         if SettingsUse is SettingsLower:
@@ -82,7 +82,7 @@ class TestLoadSettings:
             _ = fh.write(f"key = {value}\n")
             _ = fh.write(f"other = {value}\n")
 
-        settings = load_settings(Settings, cwd=root)
+        settings = load_settings(Settings, path=root)
         expected = Settings(key=value)
         assert settings == expected
 
@@ -94,7 +94,7 @@ class TestLoadSettings:
             KEY: str
 
         with raises(_LoadSettingsFileNotFoundError, match=r"Path '.*' must exist"):
-            _ = load_settings(Settings, cwd=root)
+            _ = load_settings(Settings, path=root)
 
     @given(root=git_repos(), value=integers())
     @settings_with_reduced_examples()
@@ -114,7 +114,7 @@ class TestLoadSettings:
                 flags=DOTALL,
             ),
         ):
-            _ = load_settings(Settings, cwd=root)
+            _ = load_settings(Settings, path=root)
 
     @given(root=git_repos())
     @settings_with_reduced_examples()
@@ -129,4 +129,4 @@ class TestLoadSettings:
             _LoadSettingsMissingKeysError,
             match=r"Unable to load '.*'; missing value\(s\) for 'key'",
         ):
-            _ = load_settings(Settings, cwd=root)
+            _ = load_settings(Settings, path=root)

{dycw_utilities-0.127.0 → dycw_utilities-0.128.0}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.127.0"
+__version__ = "0.128.0"

{dycw_utilities-0.127.0 → dycw_utilities-0.128.0}/src/utilities/datetime.py

@@ -509,14 +509,6 @@ def get_datetime(*, datetime: MaybeCallableDateTime) -> dt.datetime: ...
 def get_datetime(*, datetime: None) -> None: ...
 @overload
 def get_datetime(*, datetime: Sentinel) -> Sentinel: ...
-@overload
-def get_datetime(
-    *, datetime: MaybeCallableDateTime | Sentinel
-) -> dt.datetime | Sentinel: ...
-@overload
-def get_datetime(
-    *, datetime: MaybeCallableDateTime | None | Sentinel = sentinel
-) -> dt.datetime | None | Sentinel: ...
 def get_datetime(
     *, datetime: MaybeCallableDateTime | None | Sentinel = sentinel
 ) -> dt.datetime | None | Sentinel:

{dycw_utilities-0.127.0 → dycw_utilities-0.128.0}/src/utilities/hypothesis.py

@@ -506,13 +506,7 @@ def floats_extra(
 
 
 @composite
-def git_repos(
-    draw: DrawFn,
-    /,
-    *,
-    branch: MaybeSearchStrategy[str | None] = None,
-    remote: MaybeSearchStrategy[str | None] = None,
-) -> Path:
+def git_repos(draw: DrawFn, /) -> Path:
     path = draw(temp_paths())
     with temp_cwd(path):
         _ = check_call(["git", "init", "-b", "master"])
@@ -525,10 +519,6 @@ def git_repos(
         _ = check_call(["git", "commit", "-m", "add"])
         _ = check_call(["git", "rm", file_str])
         _ = check_call(["git", "commit", "-m", "rm"])
-        if (branch_ := draw2(draw, branch)) is not None:
-            _ = check_call(["git", "checkout", "-b", branch_])
-        if (remote_ := draw2(draw, remote)) is not None:
-            _ = check_call(["git", "remote", "add", "origin", remote_])
     return path
 
 

{dycw_utilities-0.127.0 → dycw_utilities-0.128.0}/src/utilities/logging.py

@@ -46,9 +46,8 @@ from utilities.datetime import (
     serialize_compact,
 )
 from utilities.errors import ImpossibleCaseError
-from utilities.git import get_repo_root
 from utilities.iterables import OneEmptyError, always_iterable, one
-from utilities.pathlib import ensure_suffix, resolve_path
+from utilities.pathlib import ensure_suffix, get_path, get_root
 from utilities.reprlib import (
     RICH_EXPAND_ALL,
     RICH_INDENT_SIZE,
@@ -68,9 +67,9 @@ if TYPE_CHECKING:
     from utilities.types import (
         LoggerOrName,
         LogLevel,
+        MaybeCallablePathLike,
         MaybeIterable,
         PathLike,
-        PathLikeOrCallable,
     )
     from utilities.version import MaybeCallableVersionLike
 
@@ -383,10 +382,10 @@ class StandaloneFileHandler(Handler):
 
     @override
     def __init__(
-        self, *, level: int = NOTSET, path: PathLikeOrCallable | None = None
+        self, *, level: int = NOTSET, path: MaybeCallablePathLike | None = None
     ) -> None:
         super().__init__(level=level)
-        self._path = path
+        self._path = get_path(path=path)
 
     @override
     def emit(self, record: LogRecord) -> None:
@@ -394,10 +393,8 @@ class StandaloneFileHandler(Handler):
         from utilities.tzlocal import get_now_local
 
         try:
-            path = (
-                resolve_path(path=self._path)
-                .joinpath(serialize_compact(get_now_local()))
-                .with_suffix(".txt")
+            path = self._path.joinpath(serialize_compact(get_now_local())).with_suffix(
+                ".txt"
             )
             formatted = self.format(record)
             with writer(path, overwrite=True) as temp, temp.open(mode="w") as fh:
@@ -473,7 +470,7 @@ class FilterForKeyError(Exception):
 
 def get_default_logging_path() -> Path:
     """Get the logging default path."""
-    return get_repo_root().joinpath(".logs")
+    return get_root().joinpath(".logs")
 
 
 ##
@@ -520,7 +517,7 @@ def setup_logging(
     console_level: LogLevel | None = "INFO",
     console_filters: Iterable[_FilterType] | None = None,
     console_fmt: str = "❯ {_zoned_datetime_str} | {name}:{funcName}:{lineno} | {message}",  # noqa: RUF001
-    files_dir: PathLikeOrCallable | None = get_default_logging_path,
+    files_dir: MaybeCallablePathLike | None = get_default_logging_path,
     files_when: _When = "D",
     files_interval: int = 1,
     files_backup_count: int = 10,
@@ -616,7 +613,7 @@ def setup_logging(
         logger_use.addHandler(console_high_and_exc_handler)
 
     # debug & info
-    directory = resolve_path(path=files_dir)  # skipif-ci-and-windows
+    directory = get_path(path=files_dir)  # skipif-ci-and-windows
     levels: list[LogLevel] = ["DEBUG", "INFO"]  # skipif-ci-and-windows
     for level, (subpath, files_or_plain_formatter) in product(  # skipif-ci-and-windows
         levels, [(Path(), files_formatter), (Path("plain"), plain_formatter)]

dycw_utilities-0.128.0/src/utilities/pathlib.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextlib import contextmanager, suppress
+from dataclasses import dataclass
+from itertools import chain
+from os import chdir
+from pathlib import Path
+from re import IGNORECASE, search
+from subprocess import PIPE, CalledProcessError, check_output
+from typing import TYPE_CHECKING, assert_never, overload, override
+
+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)
+
+
+##
+
+
+@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)
+    try:
+        output = check_output(
+            ["git", "rev-parse", "--show-toplevel"], stderr=PIPE, cwd=path, 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
+    else:
+        return Path(output.strip("\n"))
+    all_paths = list(chain([path], path.parents))
+    with suppress(StopIteration):
+        return next(
+            p for p in all_paths if any(p_i.name == ".envrc" for p_i in p.iterdir())
+        )
+    raise GetRootError(path=path)
+
+
+@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}"
+
+
+##
+
+
+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", "ensure_suffix", "get_path", "list_dir", "temp_cwd"]