dycw-utilities 0.108.1__tar.gz → 0.108.3__tar.gz

{dycw_utilities-0.108.1 → dycw_utilities-0.108.3}/PKG-INFO

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

{dycw_utilities-0.108.1 → dycw_utilities-0.108.3}/pyproject.toml

@@ -89,7 +89,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.108.1"
+version = "0.108.3"
 
 [project.optional-dependencies]
 test = [
@@ -332,7 +332,7 @@ zzz-test-zoneinfo = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.108.1"
+current_version = "0.108.3"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

{dycw_utilities-0.108.1 → dycw_utilities-0.108.3}/src/tests/test_functions.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 from functools import cache, cached_property, lru_cache, partial, wraps
 from itertools import chain
 from operator import neg
+from pathlib import Path
 from types import NoneType
 from typing import TYPE_CHECKING, Any, ClassVar, ParamSpec, TypeVar, cast
 
@@ -37,6 +38,7 @@ from utilities.functions import (
     EnsureMemberError,
     EnsureNotNoneError,
     EnsureNumberError,
+    EnsurePathError,
     EnsureSizedError,
     EnsureSizedNotStrError,
     EnsureStrError,
@@ -56,6 +58,7 @@ from utilities.functions import (
     ensure_member,
     ensure_not_none,
     ensure_number,
+    ensure_path,
     ensure_sized,
     ensure_sized_not_str,
     ensure_str,
@@ -336,6 +339,24 @@ class TestEnsureNumber:
             _ = ensure_number(sentinel, nullable=nullable)
 
 
+class TestEnsurePath:
+    @given(case=sampled_from([(Path.home(), False), (Path.home(), True), (None, True)]))
+    def test_main(self, *, case: tuple[int | None, bool]) -> None:
+        obj, nullable = case
+        _ = ensure_path(obj, nullable=nullable)
+
+    @given(
+        case=sampled_from([
+            (False, "Object '.*' of type '.*' must be a Path"),
+            (True, "Object '.*' of type '.*' must be a Path or None"),
+        ])
+    )
+    def test_error(self, *, case: tuple[bool, str]) -> None:
+        nullable, match = case
+        with raises(EnsurePathError, match=match):
+            _ = ensure_path(sentinel, nullable=nullable)
+
+
 class TestEnsureSized:
     @given(obj=sampled_from([[], (), ""]))
     def test_main(self, *, obj: Any) -> None:

dycw_utilities-0.108.3/src/tests/test_parse.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import datetime as dt
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from types import NoneType
+from typing import Literal
+
+from hypothesis import given
+from hypothesis.strategies import booleans, dates, floats, integers, sampled_from, times
+from pytest import raises
+
+from tests.test_operator import TruthEnum
+from utilities.functions import ensure_path
+from utilities.hypothesis import (
+    local_datetimes,
+    paths,
+    text_ascii,
+    timedeltas_2w,
+    versions,
+    zoned_datetimes,
+)
+from utilities.math import is_equal
+from utilities.parse import ParseTextError, parse_text
+from utilities.sentinel import Sentinel, sentinel
+from utilities.version import Version
+from utilities.whenever import (
+    serialize_date,
+    serialize_datetime,
+    serialize_time,
+    serialize_timedelta,
+)
+
+
+class TestParseText:
+    @given(value=booleans())
+    def test_bool(self, *, value: bool) -> None:
+        text = str(value)
+        result = parse_text(bool, text)
+        assert result is value
+
+    @given(date=dates())
+    def test_date(self, *, date: dt.date) -> None:
+        text = serialize_date(date)
+        result = parse_text(dt.date, text)
+        assert result == date
+
+    @given(datetime=local_datetimes() | zoned_datetimes())
+    def test_datetime(self, *, datetime: dt.datetime) -> None:
+        text = serialize_datetime(datetime)
+        result = parse_text(dt.datetime, text)
+        assert result == datetime
+
+    @given(truth=sampled_from(TruthEnum))
+    def test_enum(self, *, truth: TruthEnum) -> None:
+        text = truth.name
+        result = parse_text(TruthEnum, text)
+        assert result is truth
+
+    @given(value=floats())
+    def test_float(self, *, value: float) -> None:
+        text = str(value)
+        result = parse_text(float, text)
+        assert is_equal(result, value)
+
+    @given(value=integers())
+    def test_int(self, *, value: int) -> None:
+        text = str(value)
+        result = parse_text(int, text)
+        assert result == value
+
+    @given(truth=sampled_from(["true", "false"]))
+    def test_literal(self, *, truth: Literal["true", "false"]) -> None:
+        result = parse_text(Literal["true", "false"], truth)
+        assert result == truth
+
+    def test_nullable_int_none(self) -> None:
+        text = str(None)
+        result = parse_text(int | None, text)
+        assert result is None
+
+    @given(value=integers())
+    def test_nullable_int_int(self, *, value: int) -> None:
+        text = str(value)
+        result = parse_text(int | None, text)
+        assert result == value
+
+    def test_none(self) -> None:
+        text = str(None)
+        result = parse_text(None, text)
+        assert result is None
+
+    def test_none_type(self) -> None:
+        text = str(None)
+        result = parse_text(NoneType, text)
+        assert result is None
+
+    @given(path=paths())
+    def test_path(self, *, path: Path) -> None:
+        text = str(path)
+        result = parse_text(Path, text)
+        assert result == path
+
+    @given(path=paths())
+    def test_path_expanded(self, *, path: Path) -> None:
+        path_use = Path("~", path)
+        text = str(path_use)
+        result = ensure_path(parse_text(Path, text))
+        assert result == result.expanduser()
+
+    def test_sentinel(self) -> None:
+        text = str(sentinel)
+        result = parse_text(Sentinel, text)
+        assert result is sentinel
+
+    @given(text=text_ascii())
+    def test_str(self, *, text: str) -> None:
+        result = parse_text(str, text)
+        assert result == text
+
+    @given(time=times())
+    def test_time(self, *, time: dt.time) -> None:
+        text = serialize_time(time)
+        result = parse_text(dt.time, text)
+        assert result == time
+
+    @given(timedelta=timedeltas_2w())
+    def test_timedelta(self, *, timedelta: dt.timedelta) -> None:
+        text = serialize_timedelta(timedelta)
+        result = parse_text(dt.timedelta, text)
+        assert result == timedelta
+
+    @given(version=versions())
+    def test_version(self, *, version: Version) -> None:
+        text = str(version)
+        result = parse_text(Version, text)
+        assert result == version
+
+    def test_error_bool(self) -> None:
+        with raises(
+            ParseTextError, match="Unable to parse <class 'bool'>; got 'invalid'"
+        ):
+            _ = parse_text(bool, "invalid")
+
+    def test_error_date(self) -> None:
+        with raises(
+            ParseTextError,
+            match=r"Unable to parse <class 'datetime\.date'>; got 'invalid'",
+        ):
+            _ = parse_text(dt.date, "invalid")
+
+    def test_error_datetime(self) -> None:
+        with raises(
+            ParseTextError,
+            match=r"Unable to parse <class 'datetime\.datetime'>; got 'invalid'",
+        ):
+            _ = parse_text(dt.datetime, "invalid")
+
+    def test_error_enum(self) -> None:
+        with raises(
+            ParseTextError, match="Unable to parse <enum 'TruthEnum'>; got 'invalid'"
+        ):
+            _ = parse_text(TruthEnum, "invalid")
+
+    def test_error_float(self) -> None:
+        with raises(
+            ParseTextError, match="Unable to parse <class 'float'>; got 'invalid'"
+        ):
+            _ = parse_text(float, "invalid")
+
+    def test_error_int(self) -> None:
+        with raises(
+            ParseTextError, match="Unable to parse <class 'int'>; got 'invalid'"
+        ):
+            _ = parse_text(int, "invalid")
+
+    def test_error_none(self) -> None:
+        with raises(ParseTextError, match="Unable to parse None; got 'invalid'"):
+            _ = parse_text(None, "invalid")
+
+    def test_error_none_type(self) -> None:
+        with raises(
+            ParseTextError, match="Unable to parse <class 'NoneType'>; got 'invalid'"
+        ):
+            _ = parse_text(NoneType, "invalid")
+
+    def test_error_nullable_int(self) -> None:
+        with raises(
+            ParseTextError, match=r"Unable to parse int \| None; got 'invalid'"
+        ):
+            _ = parse_text(int | None, "invalid")
+
+    def test_error_nullable_not_type(self) -> None:
+        with raises(
+            ParseTextError,
+            match=r"Unable to parse collections\.abc\.Iterable\[None\] \| None; got 'invalid'",
+        ):
+            _ = parse_text(Iterable[None] | None, "invalid")
+
+    def test_error_sentinel(self) -> None:
+        with raises(
+            ParseTextError,
+            match=r"Unable to parse <class 'utilities\.sentinel\.Sentinel'>; got 'invalid'",
+        ):
+            _ = parse_text(Sentinel, "invalid")
+
+    def test_error_time(self) -> None:
+        with raises(
+            ParseTextError,
+            match=r"Unable to parse <class 'datetime\.time'>; got 'invalid'",
+        ):
+            _ = parse_text(dt.time, "invalid")
+
+    def test_error_timedelta(self) -> None:
+        with raises(
+            ParseTextError,
+            match=r"Unable to parse <class 'datetime\.timedelta'>; got 'invalid'",
+        ):
+            _ = parse_text(dt.timedelta, "invalid")
+
+    def test_error_unknown_annotation(self) -> None:
+        with raises(ParseTextError, match=r"Unable to parse int \| str; got 'invalid'"):
+            _ = parse_text(int | str, "invalid")
+
+    def test_error_unknown_type(self) -> None:
+        @dataclass(kw_only=True)
+        class Example:
+            pass
+
+        with raises(
+            ParseTextError,
+            match=r"Unable to parse <class 'tests\.test_parse\.TestParseText\.test_error_unknown_type\.<locals>\.Example'>; got 'invalid'",
+        ):
+            _ = parse_text(Example, "invalid")
+
+    def test_error_version(self) -> None:
+        with raises(
+            ParseTextError,
+            match=r"Unable to parse <class 'utilities\.version\.Version'>; got 'invalid'",
+        ):
+            _ = parse_text(Version, "invalid")

dycw_utilities-0.108.3/src/tests/test_python_dotenv.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from re import DOTALL
+from typing import TYPE_CHECKING
+
+from hypothesis import given
+from hypothesis.strategies import DataObject, booleans, data, integers, sampled_from
+from pytest import raises
+
+from utilities.errors import ImpossibleCaseError
+from utilities.hypothesis import git_repos, settings_with_reduced_examples, text_ascii
+from utilities.os import temp_environ
+from utilities.python_dotenv import (
+    _LoadSettingsDuplicateKeysError,
+    _LoadSettingsEmptyError,
+    _LoadSettingsFileNotFoundError,
+    _LoadSettingsParseTextError,
+    load_settings,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class TestLoadSettings:
+    @given(
+        data=data(),
+        root=git_repos(),
+        key_file=sampled_from(["key", "KEY"]),
+        value_file=text_ascii(),
+        use_env=booleans(),
+    )
+    @settings_with_reduced_examples()
+    def test_main(
+        self,
+        *,
+        data: DataObject,
+        root: Path,
+        key_file: str,
+        value_file: str,
+        use_env: bool,
+    ) -> None:
+        with root.joinpath(".env").open(mode="w") as fh:
+            _ = fh.write(f"{key_file} = {value_file}\n")
+
+        @dataclass(kw_only=True, slots=True)
+        class SettingsLower:
+            key: str
+
+        @dataclass(kw_only=True, slots=True)
+        class SettingsUpper:
+            KEY: str
+
+        SettingsUse = data.draw(sampled_from([SettingsLower, SettingsUpper]))  # noqa: N806
+        if use_env:
+            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)
+            exp_value = value_env
+        else:
+            settings = load_settings(SettingsUse, cwd=root)
+            exp_value = value_file
+
+        if SettingsUse is SettingsLower:
+            expected = SettingsLower(key=exp_value)
+        elif SettingsUse is SettingsUpper:
+            expected = SettingsUpper(KEY=exp_value)
+        else:
+            raise ImpossibleCaseError(case=[f"{SettingsUse=}"])
+        assert settings == expected
+
+    @given(root=git_repos(), value=text_ascii())
+    @settings_with_reduced_examples()
+    def test_file_extra_key(self, *, root: Path, value: str) -> None:
+        @dataclass(kw_only=True, slots=True)
+        class Settings:
+            key: str
+
+        with root.joinpath(".env").open(mode="w") as fh:
+            _ = fh.write(f"key = {value}\n")
+            _ = fh.write(f"other = {value}\n")
+
+        settings = load_settings(Settings, cwd=root)
+        expected = Settings(key=value)
+        assert settings == expected
+
+    @given(root=git_repos())
+    @settings_with_reduced_examples()
+    def test_error_file_not_found(self, *, root: Path) -> None:
+        @dataclass(kw_only=True, slots=True)
+        class Settings:
+            KEY: str
+
+        with raises(_LoadSettingsFileNotFoundError, match=r"Path '.*' must exist"):
+            _ = load_settings(Settings, cwd=root)
+
+    @given(root=git_repos(), value=integers())
+    @settings_with_reduced_examples()
+    def test_error_duplicate_keys(self, *, root: Path, value: int) -> None:
+        @dataclass(kw_only=True, slots=True)
+        class Settings:
+            key: str
+
+        with root.joinpath(".env").open(mode="w") as fh:
+            _ = fh.write(f"key = {value}\n")
+            _ = fh.write(f"KEY = {value}\n")
+
+        with raises(
+            _LoadSettingsDuplicateKeysError,
+            match=re.compile(
+                r"Mapping .* keys must not contain duplicates \(modulo case\); got .*",
+                flags=DOTALL,
+            ),
+        ):
+            _ = load_settings(Settings, cwd=root)
+
+    @given(root=git_repos())
+    @settings_with_reduced_examples()
+    def test_error_field_missing(self, *, root: Path) -> None:
+        @dataclass(kw_only=True, slots=True)
+        class Settings:
+            key: str
+
+        root.joinpath(".env").touch()
+
+        with raises(
+            _LoadSettingsEmptyError, match=r"Field 'key' must exist \(modulo case\)"
+        ):
+            _ = load_settings(Settings, cwd=root)
+
+    @given(root=git_repos())
+    @settings_with_reduced_examples()
+    def test_error_parse_text(self, *, root: Path) -> None:
+        @dataclass(kw_only=True, slots=True)
+        class Settings:
+            key: int
+
+        with root.joinpath(".env").open(mode="w") as fh:
+            _ = fh.write("key = '...'\n")
+
+        with raises(
+            _LoadSettingsParseTextError,
+            match=r"Unable to parse field 'key' of type <class 'int'>; got '...'",
+        ):
+            _ = load_settings(Settings, cwd=root)

dycw_utilities-0.108.3/src/tests/test_sentinel.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hypothesis import given
+from hypothesis.strategies import DataObject, data, sampled_from
+from pytest import mark, param, raises
+
+from utilities.sentinel import (
+    SENTINEL_REPR,
+    ParseSentinelError,
+    Sentinel,
+    parse_sentinel,
+    sentinel,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class TestParseSentinel:
+    @given(data=data())
+    def test_main(self, *, data: DataObject) -> None:
+        text = str(sentinel)
+        text_use = data.draw(sampled_from(["", text, text.lower(), text.upper()]))
+        result = parse_sentinel(text_use)
+        assert result is sentinel
+
+    def test_error(self) -> None:
+        with raises(
+            ParseSentinelError, match="Unable to parse sentinel value; got 'invalid'"
+        ):
+            _ = parse_sentinel("invalid")
+
+
+class TestSentinel:
+    def test_isinstance(self) -> None:
+        assert isinstance(sentinel, Sentinel)
+
+    @mark.parametrize("method", [param(repr), param(str)])
+    def test_repr_and_str(self, method: Callable[..., str]) -> None:
+        assert method(sentinel) == SENTINEL_REPR
+
+    def test_singletone(self) -> None:
+        assert Sentinel() is sentinel

{dycw_utilities-0.108.1 → dycw_utilities-0.108.3}/src/tests/test_text.py

@@ -16,8 +16,10 @@ from utilities.hypothesis import text_ascii
 from utilities.sentinel import sentinel
 from utilities.text import (
     ParseBoolError,
+    ParseNoneError,
     join_strs,
     parse_bool,
+    parse_none,
     repr_encode,
     snake_case,
     split_str,
@@ -29,18 +31,33 @@ from utilities.text import (
 class TestParseBool:
     @given(data=data(), value=booleans())
     def test_main(self, *, data: DataObject, value: bool) -> None:
-        text = data.draw(sampled_from([str(value), str(int(value))]))
-        text = data.draw(sampled_from([text, text.lower(), text.upper()]))
-        result = parse_bool(text)
+        text = str(value)
+        text_use = data.draw(
+            sampled_from([str(int(value)), text, text.lower(), text.upper()])
+        )
+        result = parse_bool(text_use)
         assert result is value
 
     def test_error(self) -> None:
         with raises(
-            ParseBoolError, match="Unable to parse 'invalid' into a boolean value"
+            ParseBoolError, match="Unable to parse boolean value; got 'invalid'"
         ):
             _ = parse_bool("invalid")
 
 
+class TestParseNone:
+    @given(data=data())
+    def test_main(self, *, data: DataObject) -> None:
+        text = str(None)
+        text_use = data.draw(sampled_from(["", text, text.lower(), text.upper()]))
+        result = parse_none(text_use)
+        assert result is None
+
+    def test_error(self) -> None:
+        with raises(ParseNoneError, match="Unable to parse null value; got 'invalid'"):
+            _ = parse_none("invalid")
+
+
 class TestReprEncode:
     @given(n=integers())
     def test_main(self, *, n: int) -> None:

{dycw_utilities-0.108.1 → dycw_utilities-0.108.3}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.108.1"
+__version__ = "0.108.3"

{dycw_utilities-0.108.1 → dycw_utilities-0.108.3}/src/utilities/functions.py

@@ -5,6 +5,7 @@ from collections.abc import Callable, Iterable, Iterator, Sequence
 from dataclasses import asdict, dataclass, is_dataclass
 from functools import _lru_cache_wrapper, cached_property, partial, reduce, wraps
 from inspect import getattr_static
+from pathlib import Path
 from re import findall
 from types import (
     BuiltinFunctionType,
@@ -405,6 +406,31 @@ class EnsureNumberError(Exception):
 ##
 
 
+@overload
+def ensure_path(obj: Any, /, *, nullable: bool) -> Path | None: ...
+@overload
+def ensure_path(obj: Any, /, *, nullable: Literal[False] = False) -> Path: ...
+def ensure_path(obj: Any, /, *, nullable: bool = False) -> Path | None:
+    """Ensure an object is a Path."""
+    try:
+        return ensure_class(obj, Path, nullable=nullable)
+    except EnsureClassError as error:
+        raise EnsurePathError(obj=error.obj, nullable=nullable) from None
+
+
+@dataclass(kw_only=True, slots=True)
+class EnsurePathError(Exception):
+    obj: Any
+    nullable: bool
+
+    @override
+    def __str__(self) -> str:
+        return _make_error_msg(self.obj, "a Path", nullable=self.nullable)
+
+
+##
+
+
 def ensure_sized(obj: Any, /) -> Sized:
     """Ensure an object is sized."""
     if is_sized(obj):
@@ -985,6 +1011,7 @@ __all__ = [
     "EnsureMemberError",
     "EnsureNotNoneError",
     "EnsureNumberError",
+    "EnsurePathError",
     "EnsureSizedError",
     "EnsureSizedNotStrError",
     "EnsureStrError",
@@ -1004,6 +1031,7 @@ __all__ = [
     "ensure_member",
     "ensure_not_none",
     "ensure_number",
+    "ensure_path",
     "ensure_sized",
     "ensure_sized_not_str",
     "ensure_str",