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

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

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

{dycw_utilities-0.108.2 → 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.2"
+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.2"
+current_version = "0.108.3"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

{dycw_utilities-0.108.2 → 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.2 → dycw_utilities-0.108.3}/src/tests/test_parse.py

@@ -12,6 +12,7 @@ from hypothesis.strategies import booleans, dates, floats, integers, sampled_fro
 from pytest import raises
 
 from tests.test_operator import TruthEnum
+from utilities.functions import ensure_path
 from utilities.hypothesis import (
     local_datetimes,
     paths,
@@ -101,6 +102,13 @@ class TestParseText:
         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)

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.2 → dycw_utilities-0.108.3}/src/utilities/__init__.py

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

{dycw_utilities-0.108.2 → 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",

dycw_utilities-0.108.3/src/utilities/python_dotenv.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import partial
+from os import environ
+from typing import TYPE_CHECKING, Any, override
+
+from dotenv import dotenv_values
+
+from utilities.dataclasses import (
+    _MappingToDataclassEmptyError,
+    _YieldFieldsClass,
+    mapping_to_dataclass,
+)
+from utilities.git import get_repo_root
+from utilities.iterables import MergeStrMappingsError, merge_str_mappings
+from utilities.parse import ParseTextError, parse_text
+from utilities.pathlib import PWD
+from utilities.reprlib import get_repr
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+    from utilities.types import PathLike, StrMapping, TDataclass
+
+
+def load_settings(
+    cls: type[TDataclass],
+    /,
+    *,
+    cwd: PathLike = PWD,
+    globalns: StrMapping | None = None,
+    localns: StrMapping | None = None,
+) -> TDataclass:
+    """Load a set of settings from the `.env` file."""
+    path = get_repo_root(cwd=cwd).joinpath(".env")
+    if not path.exists():
+        raise _LoadSettingsFileNotFoundError(path=path) from None
+    maybe_values_dotenv = dotenv_values(path)
+    try:
+        maybe_values = merge_str_mappings(maybe_values_dotenv, environ)
+    except MergeStrMappingsError as error:
+        raise _LoadSettingsDuplicateKeysError(
+            path=path, values=error.mapping, counts=error.counts
+        ) from None
+    values = {k: v for k, v in maybe_values.items() if v is not None}
+    try:
+        return mapping_to_dataclass(
+            cls,
+            values,
+            globalns=globalns,
+            localns=localns,
+            post=partial(_load_settings_post, path=path, values=values),
+        )
+    except _MappingToDataclassEmptyError as error:
+        raise _LoadSettingsEmptyError(
+            path=path, values=error.mapping, field=error.field
+        ) from None
+
+
+def _load_settings_post(
+    field: _YieldFieldsClass[Any], text: str, /, *, path: Path, values: StrMapping
+) -> Any:
+    try:
+        return parse_text(field.type_, text)
+    except ParseTextError:
+        raise _LoadSettingsParseTextError(
+            path=path, values=values, field=field, text=text
+        ) from None
+
+
+@dataclass(kw_only=True, slots=True)
+class LoadSettingsError(Exception):
+    path: Path
+
+
+@dataclass(kw_only=True, slots=True)
+class _LoadSettingsDuplicateKeysError(LoadSettingsError):
+    values: StrMapping
+    counts: Mapping[str, int]
+
+    @override
+    def __str__(self) -> str:
+        return f"Mapping {get_repr(dict(self.values))} keys must not contain duplicates (modulo case); got {get_repr(self.counts)}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _LoadSettingsEmptyError(LoadSettingsError):
+    values: StrMapping
+    field: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Field {self.field!r} must exist (modulo case)"
+
+
+@dataclass(kw_only=True, slots=True)
+class _LoadSettingsFileNotFoundError(LoadSettingsError):
+    @override
+    def __str__(self) -> str:
+        return f"Path {str(self.path)!r} must exist"
+
+
+@dataclass(kw_only=True, slots=True)
+class _LoadSettingsParseTextError(LoadSettingsError):
+    values: StrMapping
+    field: _YieldFieldsClass[Any]
+    text: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to parse field {self.field.name!r} of type {self.field.type_!r}; got {self.text!r}"
+
+
+__all__ = ["LoadSettingsError", "load_settings"]