dycw-utilities 0.155.3__tar.gz → 0.156.0__tar.gz

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/PKG-INFO

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

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/pyproject.toml

@@ -144,7 +144,7 @@ psutil = [
   "psutil >=7.0.0, <7.1",
 ]
 pyinstrument = [
-  "pyinstrument >=5.0.3, <5.1",
+  "pyinstrument >=5.1.0, <5.2",
 ]
 pytest = [
   "pytest >=8.4.1, <8.5",
@@ -227,7 +227,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.155.3"
+version = "0.156.0"
 
 [project.entry-points.pytest11]
 pytest-randomly = "utilities.pytest_plugins.pytest_randomly"
@@ -259,7 +259,7 @@ test = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.155.3"
+current_version = "0.156.0"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/src/tests/test_click.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import enum
+import pathlib
 from dataclasses import dataclass
 from enum import auto
 from operator import attrgetter
@@ -30,11 +31,7 @@ from utilities.click import (
     Date,
     DateDelta,
     DateTimeDelta,
-    DirPath,
     Enum,
-    ExistingDirPath,
-    ExistingFilePath,
-    FilePath,
     FrozenSetChoices,
     FrozenSetEnums,
     FrozenSetInts,
@@ -46,6 +43,7 @@ from utilities.click import (
     ListInts,
     ListStrs,
     MonthDay,
+    Path,
     PlainDateTime,
     Time,
     TimeDelta,
@@ -57,6 +55,7 @@ from utilities.hypothesis import (
     date_time_deltas,
     dates,
     month_days,
+    paths,
     plain_date_times,
     text_ascii,
     time_deltas,
@@ -68,7 +67,6 @@ from utilities.text import join_strs, strip_and_dedent
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable
-    from pathlib import Path
 
 
 class TestContextSettingsHelpOptionNames:
@@ -81,91 +79,17 @@ class TestContextSettingsHelpOptionNames:
         assert result.exit_code == 0
 
 
-class TestFileAndDirPaths:
-    def test_existing_dir_path(self, *, tmp_path: Path) -> None:
-        @command()
-        @argument("path", type=ExistingDirPath)
-        def cli(*, path: Path) -> None:
-            from pathlib import Path
-
-            assert isinstance(path, Path)
+class TestPath:
+    def test_path(self, *, tmp_path: pathlib.Path) -> None:
+        path_use = pathlib.Path("~", tmp_path)
 
-        result = CliRunner().invoke(cli, [str(tmp_path)])
-        assert result.exit_code == 0
-
-        file_path = tmp_path.joinpath("file.txt")
-        file_path.touch()
-        result = CliRunner().invoke(cli, [str(file_path)])
-        assert result.exit_code == 2
-        assert search("is a file", result.stderr)
-
-        non_existent = tmp_path.joinpath("non-existent")
-        result = CliRunner().invoke(cli, [str(non_existent)])
-        assert result.exit_code == 2
-        assert search("does not exist", result.stderr)
-
-    def test_existing_file_path(self, *, tmp_path: Path) -> None:
         @command()
-        @argument("path", type=ExistingFilePath)
-        def cli(*, path: Path) -> None:
-            from pathlib import Path
-
-            assert isinstance(path, Path)
+        @argument("path", type=Path())
+        def cli(*, path: pathlib.Path) -> None:
+            assert isinstance(path, pathlib.Path)
+            assert path == path.expanduser()
 
-        result = CliRunner().invoke(cli, [str(tmp_path)])
-        assert result.exit_code == 2
-        assert search("is a directory", result.stderr)
-
-        file_path = tmp_path.joinpath("file.txt")
-        file_path.touch()
-        result = CliRunner().invoke(cli, [str(file_path)])
-        assert result.exit_code == 0
-
-        non_existent = tmp_path.joinpath("non-existent")
-        result = CliRunner().invoke(cli, [str(non_existent)])
-        assert result.exit_code == 2
-        assert search("does not exist", result.stderr)
-
-    def test_dir_path(self, *, tmp_path: Path) -> None:
-        @command()
-        @argument("path", type=DirPath)
-        def cli(*, path: Path) -> None:
-            from pathlib import Path
-
-            assert isinstance(path, Path)
-
-        result = CliRunner().invoke(cli, [str(tmp_path)])
-        assert result.exit_code == 0
-
-        file_path = tmp_path.joinpath("file.txt")
-        file_path.touch()
-        result = CliRunner().invoke(cli, [str(file_path)])
-        assert result.exit_code == 2
-        assert search("is a file", result.stderr)
-
-        non_existent = tmp_path.joinpath("non-existent")
-        result = CliRunner().invoke(cli, [str(non_existent)])
-        assert result.exit_code == 0
-
-    def test_file_path(self, *, tmp_path: Path) -> None:
-        @command()
-        @argument("path", type=FilePath)
-        def cli(*, path: Path) -> None:
-            from pathlib import Path
-
-            assert isinstance(path, Path)
-
-        result = CliRunner().invoke(cli, [str(tmp_path)])
-        assert result.exit_code == 2
-        assert search("is a directory", result.stderr)
-
-        file_path = tmp_path.joinpath("file.txt")
-        file_path.touch()
-        result = CliRunner().invoke(cli, [str(file_path)])
-        assert result.exit_code == 0
-
-        non_existent = tmp_path.joinpath("non-existent")
-        result = CliRunner().invoke(cli, [str(non_existent)])
+        result = CliRunner().invoke(cli, [str(path_use)])
         assert result.exit_code == 0
 
 
@@ -301,6 +225,9 @@ class TestParameters:
             serialize=whenever.MonthDay.format_common_iso,
             failable=True,
         ),
+        _Case(
+            param=Path(), name="path", strategy=paths(), serialize=str, failable=False
+        ),
         _Case(
             param=PlainDateTime(),
             name="plain date-time",

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/src/tests/test_hypothesis.py

@@ -125,7 +125,7 @@ from utilities.math import (
 )
 from utilities.os import temp_environ
 from utilities.platform import maybe_yield_lower_case
-from utilities.sentinel import Sentinel
+from utilities.sentinel import is_sentinel
 from utilities.version import Version
 from utilities.whenever import (
     DATE_TWO_DIGIT_YEAR_MAX,
@@ -142,6 +142,7 @@ if TYPE_CHECKING:
     from collections.abc import Set as AbstractSet
     from zoneinfo import ZoneInfo
 
+    from utilities.sentinel import Sentinel
     from utilities.tempfile import TemporaryDirectory
     from utilities.types import Number
 
@@ -786,7 +787,7 @@ class TestSentinels:
     @given(data=data())
     def test_main(self, *, data: DataObject) -> None:
         sentinel = data.draw(sentinels())
-        assert isinstance(sentinel, Sentinel)
+        assert is_sentinel(sentinel)
 
 
 class TestSetsFixedLength:

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/src/tests/test_sentinel.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from hypothesis import given
 from hypothesis.strategies import DataObject, data, sampled_from
@@ -10,6 +10,7 @@ from utilities.sentinel import (
     SENTINEL_REPR,
     ParseSentinelError,
     Sentinel,
+    is_sentinel,
     parse_sentinel,
     sentinel,
 )
@@ -18,6 +19,12 @@ if TYPE_CHECKING:
     from collections.abc import Callable
 
 
+class TestIsSentinel:
+    @mark.parametrize(("obj", "expected"), [param(None, False), param(sentinel, True)])
+    def test_main(self, *, obj: Any, expected: bool) -> None:
+        assert is_sentinel(obj) is expected
+
+
 class TestParseSentinel:
     @given(data=data())
     def test_main(self, *, data: DataObject) -> None:

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.155.3"
+__version__ = "0.156.0"

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/src/utilities/click.py

@@ -6,7 +6,6 @@ import pathlib
 import uuid
 from typing import TYPE_CHECKING, TypedDict, assert_never, override
 
-import click
 import whenever
 from click import Choice, Context, Parameter, ParamType
 from click.types import IntParamType, StringParamType
@@ -29,6 +28,7 @@ if TYPE_CHECKING:
         IPv6AddressLike,
         MaybeStr,
         MonthDayLike,
+        PathLike,
         PlainDateTimeLike,
         TimeDeltaLike,
         TimeLike,
@@ -37,16 +37,6 @@ if TYPE_CHECKING:
     )
 
 
-FilePath = click.Path(file_okay=True, dir_okay=False, path_type=pathlib.Path)
-DirPath = click.Path(file_okay=False, dir_okay=True, path_type=pathlib.Path)
-ExistingFilePath = click.Path(
-    exists=True, file_okay=True, dir_okay=False, path_type=pathlib.Path
-)
-ExistingDirPath = click.Path(
-    exists=True, file_okay=False, dir_okay=True, path_type=pathlib.Path
-)
-
-
 class _HelpOptionNames(TypedDict):
     help_option_names: Sequence[str]
 
@@ -252,6 +242,32 @@ class MonthDay(ParamType):
                 assert_never(never)
 
 
+class Path(ParamType):
+    """A path-valued parameter."""
+
+    name = "path"
+
+    @override
+    def __repr__(self) -> str:
+        return self.name.upper()
+
+    @override
+    def convert(
+        self, value: PathLike, param: Parameter | None, ctx: Context | None
+    ) -> pathlib.Path:
+        """Convert a value into the `Path` type."""
+        match value:
+            case pathlib.Path():
+                return value.expanduser()
+            case str():
+                try:
+                    return pathlib.Path(value).expanduser()
+                except ValueError as error:
+                    self.fail(str(error), param, ctx)
+            case never:
+                assert_never(never)
+
+
 class PlainDateTime(ParamType):
     """A local-datetime-valued parameter."""
 
@@ -592,11 +608,7 @@ __all__ = [
     "Date",
     "DateDelta",
     "DateTimeDelta",
-    "DirPath",
     "Enum",
-    "ExistingDirPath",
-    "ExistingFilePath",
-    "FilePath",
     "FrozenSetChoices",
     "FrozenSetEnums",
     "FrozenSetParameter",
@@ -609,6 +621,8 @@ __all__ = [
     "ListParameter",
     "ListStrs",
     "MonthDay",
+    "Path",
+    "Path",
     "PlainDateTime",
     "Time",
     "TimeDelta",

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/src/utilities/dataclasses.py

@@ -25,7 +25,7 @@ from utilities.parse import (
     serialize_object,
 )
 from utilities.re import ExtractGroupError, extract_group
-from utilities.sentinel import Sentinel, sentinel
+from utilities.sentinel import Sentinel, is_sentinel, sentinel
 from utilities.text import (
     BRACKETS,
     LIST_SEPARATOR,
@@ -275,8 +275,7 @@ def mapping_to_dataclass[T: Dataclass](
     default = {
         f.name
         for f in fields_use
-        if (not isinstance(f.default, Sentinel))
-        or (not isinstance(f.default_factory, Sentinel))
+        if (not is_sentinel(f.default)) or (not is_sentinel(f.default_factory))
     }
     have = set(field_names_to_values) | default
     missing = {f.name for f in fields_use} - have
@@ -434,12 +433,10 @@ def replace_non_sentinel[T: Dataclass](
     """Replace attributes on a dataclass, filtering out sentinel values."""
     if in_place:
         for k, v in kwargs.items():
-            if not isinstance(v, Sentinel):
+            if not is_sentinel(v):
                 setattr(obj, k, v)
         return None
-    return replace(
-        obj, **{k: v for k, v in kwargs.items() if not isinstance(v, Sentinel)}
-    )
+    return replace(obj, **{k: v for k, v in kwargs.items() if not is_sentinel(v)})
 
 
 ##
@@ -912,17 +909,11 @@ class _YieldFieldsInstance[T]:
         extra: Mapping[type[U], Callable[[U, U], bool]] | None = None,
     ) -> bool:
         """Check if the field value equals its default."""
-        if isinstance(self.default, Sentinel) and isinstance(
-            self.default_factory, Sentinel
-        ):
+        if is_sentinel(self.default) and is_sentinel(self.default_factory):
             return False
-        if (not isinstance(self.default, Sentinel)) and isinstance(
-            self.default_factory, Sentinel
-        ):
+        if (not is_sentinel(self.default)) and is_sentinel(self.default_factory):
             expected = self.default
-        elif isinstance(self.default, Sentinel) and (
-            not isinstance(self.default_factory, Sentinel)
-        ):
+        elif is_sentinel(self.default) and (not is_sentinel(self.default_factory)):
             expected = self.default_factory()
         else:  # pragma: no cover
             raise ImpossibleCaseError(

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/src/utilities/functions.py

@@ -19,7 +19,7 @@ from typing import TYPE_CHECKING, Any, Literal, TypeGuard, cast, overload, overr
 from whenever import Date, PlainDateTime, Time, TimeDelta, ZonedDateTime
 
 from utilities.reprlib import get_repr, get_repr_and_class
-from utilities.sentinel import Sentinel, sentinel
+from utilities.sentinel import Sentinel, is_sentinel, sentinel
 from utilities.types import (
     Dataclass,
     Number,
@@ -864,7 +864,7 @@ def min_nullable[T: SupportsRichComparison, U](
 ) -> T | U:
     """Compute the minimum of a set of values; ignoring nulls."""
     values = (i for i in iterable if i is not None)
-    if isinstance(default, Sentinel):
+    if is_sentinel(default):
         try:
             return min(values)
         except ValueError:
@@ -894,7 +894,7 @@ def max_nullable[T: SupportsRichComparison, U](
 ) -> T | U:
     """Compute the maximum of a set of values; ignoring nulls."""
     values = (i for i in iterable if i is not None)
-    if isinstance(default, Sentinel):
+    if is_sentinel(default):
         try:
             return max(values)
         except ValueError:

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/src/utilities/hypothesis.py

@@ -77,7 +77,7 @@ from utilities.math import (
 from utilities.os import get_env_var
 from utilities.pathlib import module_path, temp_cwd
 from utilities.platform import IS_WINDOWS
-from utilities.sentinel import Sentinel, sentinel
+from utilities.sentinel import Sentinel, is_sentinel, sentinel
 from utilities.tempfile import TEMP_DIR, TemporaryDirectory
 from utilities.version import Version
 from utilities.whenever import (
@@ -363,14 +363,14 @@ def draw2[T](
             return value
         case None, SearchStrategy(), False:
             value2 = draw(default)
-            if isinstance(value2, Sentinel):
+            if is_sentinel(value2):
                 raise _Draw2DefaultGeneratedSentinelError
             return value2
         case Sentinel(), None, _:
             raise _Draw2InputResolvedToSentinelError
         case Sentinel(), SearchStrategy(), True:
             value2 = draw(default)
-            if isinstance(value2, Sentinel):
+            if is_sentinel(value2):
                 raise _Draw2DefaultGeneratedSentinelError
             return value2
         case Sentinel(), SearchStrategy(), False:

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/src/utilities/iterables.py

@@ -40,7 +40,7 @@ from utilities.math import (
     check_integer,
 )
 from utilities.reprlib import get_repr
-from utilities.sentinel import Sentinel, sentinel
+from utilities.sentinel import Sentinel, is_sentinel, sentinel
 from utilities.types import SupportsAdd, SupportsLT
 
 if TYPE_CHECKING:
@@ -1237,7 +1237,7 @@ def reduce_mappings[K, V, W](
 ) -> Mapping[K, V | W]:
     """Reduce a function over the values of a set of mappings."""
     chained = chain_mappings(*sequence)
-    if isinstance(initial, Sentinel):
+    if is_sentinel(initial):
         func2 = cast("Callable[[V, V], V]", func)
         return {k: reduce(func2, v) for k, v in chained.items()}
     func2 = cast("Callable[[W, V], W]", func)

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/src/utilities/more_itertools.py

@@ -21,7 +21,7 @@ from more_itertools import peekable as _peekable
 from utilities.functions import get_class_name
 from utilities.iterables import OneNonUniqueError, one
 from utilities.reprlib import get_repr
-from utilities.sentinel import Sentinel, sentinel
+from utilities.sentinel import Sentinel, is_sentinel, sentinel
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator, Mapping, Sequence
@@ -290,9 +290,7 @@ class peekable[T](_peekable):  # noqa: N801
     def peek[U](self, *, default: U) -> T | U: ...
     @override
     def peek(self, *, default: Any = sentinel) -> Any:  # pyright: ignore[reportIncompatibleMethodOverride]
-        if isinstance(default, Sentinel):
-            return super().peek()
-        return super().peek(default=default)
+        return super().peek() if is_sentinel(default) else super().peek(default=default)
 
     def takewhile(self, predicate: Callable[[T], bool], /) -> Iterator[T]:
         while bool(self) and predicate(self.peek()):

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/src/utilities/pqdm.py

@@ -9,7 +9,7 @@ from tqdm.auto import tqdm as tqdm_auto
 from utilities.functions import get_func_name
 from utilities.iterables import apply_to_varargs
 from utilities.os import get_cpu_use
-from utilities.sentinel import Sentinel, sentinel
+from utilities.sentinel import Sentinel, is_sentinel, sentinel
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable
@@ -98,7 +98,7 @@ def pqdm_starmap[T](
 def _get_desc(
     desc: str | None | Sentinel, func: Callable[..., Any], /
 ) -> dict[str, str]:
-    desc_use = get_func_name(func) if isinstance(desc, Sentinel) else desc
+    desc_use = get_func_name(func) if is_sentinel(desc) else desc
     return {} if desc_use is None else {"desc": desc_use}
 
 

{dycw_utilities-0.155.3 → dycw_utilities-0.156.0}/src/utilities/sentinel.py

@@ -4,6 +4,8 @@ from dataclasses import dataclass
 from re import IGNORECASE, search
 from typing import Any, override
 
+from typing_extensions import TypeIs
+
 
 class _Meta(type):
     """Metaclass for the sentinel."""
@@ -34,6 +36,13 @@ class Sentinel(metaclass=_Meta):
 
 sentinel = Sentinel()
 
+##
+
+
+def is_sentinel(obj: Any, /) -> TypeIs[Sentinel]:
+    """Check if an object is the sentinel."""
+    return obj is sentinel
+
 
 ##
 
@@ -58,6 +67,7 @@ __all__ = [
     "SENTINEL_REPR",
     "ParseSentinelError",
     "Sentinel",
+    "is_sentinel",
     "parse_sentinel",
     "sentinel",
 ]