dycw-utilities 0.131.13__tar.gz → 0.131.15__tar.gz

{dycw_utilities-0.131.13 → dycw_utilities-0.131.15}/PKG-INFO

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

{dycw_utilities-0.131.13 → dycw_utilities-0.131.15}/pyproject.toml

@@ -61,6 +61,7 @@ dev = [
   "streamlit >= 1.45.0, < 1.46",
   "tenacity >= 8.5.0, < 9.0",  # limited by luigi
   "tomlkit >= 0.13.2, < 0.14",
+  "typed-settings >= 24.6.0, < 24.7",
   "tzdata >= 2025.2, < 2025.3",
   "uvicorn >= 0.34.1, < 0.35",
   "vegafusion >= 2.0.2, < 2.1",
@@ -94,7 +95,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.131.13"
+version = "0.131.15"
 
 [project.optional-dependencies]
 logging = [
@@ -121,7 +122,7 @@ test = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.131.13"
+current_version = "0.131.15"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"
@@ -319,6 +320,7 @@ select = [
   "S101",  # assert
   "SLF001",  # private-member-access
 ]
+"src/tests/test_typed_settings.py" = ["I002"]  # missing-required-import
 "src/tests/test_typing_funcs/no_future.py" = ["I002"]  # missing-required-import
 
 [tool.ruff.lint.flake8-tidy-imports]

{dycw_utilities-0.131.13 → dycw_utilities-0.131.15}/src/tests/test_hypothesis.py

@@ -43,7 +43,6 @@ from utilities.datetime import (
 )
 from utilities.functions import ensure_int
 from utilities.hypothesis import (
-    MaybeSearchStrategy,
     PlainDateTimesError,
     Shape,
     ZonedDateTimesError,
@@ -67,7 +66,6 @@ from utilities.hypothesis import (
     int64s,
     int_arrays,
     lists_fixed_length,
-    min_and_max_datetimes,
     months,
     namespace_mixins,
     numbers,
@@ -704,29 +702,6 @@ class TestListsFixedLength:
             assert sorted(result) == result
 
 
-class TestMinAndMaxDateTimes:
-    @given(
-        data=data(),
-        min_value=zoned_datetimes() | none() | just(zoned_datetimes() | none()),
-        max_value=zoned_datetimes() | none() | just(zoned_datetimes() | none()),
-    )
-    def test_main(
-        self,
-        *,
-        data: DataObject,
-        min_value: MaybeSearchStrategy[dt.datetime | None],
-        max_value: MaybeSearchStrategy[dt.datetime | None],
-    ) -> None:
-        min_datetime, max_datetime = data.draw(
-            min_and_max_datetimes(min_value=min_value, max_value=max_value)
-        )
-        assert min_datetime <= max_datetime
-        if isinstance(min_value, dt.datetime):
-            assert min_datetime == min_value
-        if isinstance(max_value, dt.datetime):
-            assert max_datetime == max_value
-
-
 class TestMonths:
     @given(data=data())
     def test_main(self, *, data: DataObject) -> None:

{dycw_utilities-0.131.13 → dycw_utilities-0.131.15}/src/tests/test_luigi.py

@@ -1,28 +1,25 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast, override
+from typing import TYPE_CHECKING, Any, Literal, cast, override
 
 from hypothesis import given
-from hypothesis.strategies import DataObject, booleans, data, sampled_from, times
-from luigi import BoolParameter, Parameter, Task
+from hypothesis.strategies import booleans
+from luigi import BoolParameter, Task
+from pytest import mark, param
 
-from utilities.hypothesis import namespace_mixins, temp_paths, zoned_datetimes
+from utilities.hypothesis import namespace_mixins, temp_paths, zoned_datetimes_whenever
 from utilities.luigi import (
-    DateHourParameter,
-    DateMinuteParameter,
-    DateSecondParameter,
     ExternalFile,
     ExternalTask,
     PathTarget,
-    TimeParameter,
+    ZonedDateTimeParameter,
     _ExternalTaskDummyTarget,
     build,
 )
-from utilities.whenever import serialize_time, serialize_zoned_datetime
 
 if TYPE_CHECKING:
-    import datetime as dt
+    from whenever import ZonedDateTime
 
 
 class TestBuild:
@@ -34,20 +31,17 @@ class TestBuild:
 
 
 class TestDateTimeParameter:
-    @given(
-        data=data(),
-        param_cls=sampled_from([
-            DateHourParameter,
-            DateMinuteParameter,
-            DateSecondParameter,
-        ]),
-        datetime=zoned_datetimes(),
-    )
+    @given(datetime=zoned_datetimes_whenever())
+    @mark.parametrize("type_", [param("datetime"), param("str")])
     def test_main(
-        self, *, data: DataObject, param_cls: type[Parameter], datetime: dt.datetime
+        self, *, datetime: ZonedDateTime, type_: Literal["datetime", "str"]
     ) -> None:
-        param = param_cls()
-        input_ = data.draw(sampled_from([datetime, serialize_zoned_datetime(datetime)]))
+        param = ZonedDateTimeParameter()
+        match type_:
+            case "datetime":
+                input_ = datetime
+            case "str":
+                input_ = datetime.format_common_iso()
         norm = param.normalize(input_)
         assert param.parse(param.serialize(norm)) == norm
 
@@ -90,12 +84,3 @@ class TestPathTarget:
         assert not target.exists()
         path.touch()
         assert target.exists()
-
-
-class TestTimeParameter:
-    @given(data=data(), time=times())
-    def test_main(self, *, data: DataObject, time: dt.time) -> None:
-        param = TimeParameter()
-        input_ = data.draw(sampled_from([time, serialize_time(time)]))
-        norm = param.normalize(input_)
-        assert param.parse(param.serialize(norm)) == time

dycw_utilities-0.131.15/src/tests/test_typed_settings.py

@@ -0,0 +1,97 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from operator import eq
+from pathlib import Path
+from typing import TypeVar
+
+from hypothesis import given
+from hypothesis.strategies import DataObject, SearchStrategy, data, tuples
+from pytest import mark, param
+from typed_settings import FileLoader, TomlFormat, load_settings
+from whenever import Date, DateDelta, PlainDateTime, Time, TimeDelta, ZonedDateTime
+
+from utilities.hypothesis import (
+    date_deltas_whenever,
+    dates_whenever,
+    plain_datetimes_whenever,
+    temp_paths,
+    text_ascii,
+    time_deltas_whenever,
+    times_whenever,
+    zoned_datetimes_whenever,
+)
+from utilities.typed_settings import ExtendedTSConverter
+
+app_names = text_ascii(min_size=1).map(str.lower)
+
+
+_T = TypeVar("_T")
+
+
+class TestExtendedTSConverter:
+    @given(data=data(), root=temp_paths(), appname=text_ascii(min_size=1))
+    @mark.parametrize(
+        ("test_cls", "strategy", "serialize"),
+        [
+            param(Date, dates_whenever(), Date.format_common_iso),
+            param(
+                DateDelta,
+                date_deltas_whenever(parsable=True),
+                DateDelta.format_common_iso,
+            ),
+            param(
+                PlainDateTime,
+                plain_datetimes_whenever(),
+                PlainDateTime.format_common_iso,
+            ),
+            param(Time, times_whenever(), Time.format_common_iso),
+            param(TimeDelta, time_deltas_whenever(), TimeDelta.format_common_iso),
+            param(
+                ZonedDateTime,
+                zoned_datetimes_whenever(),
+                ZonedDateTime.format_common_iso,
+            ),
+        ],
+    )
+    def test_main(
+        self,
+        *,
+        data: DataObject,
+        root: Path,
+        appname: str,
+        test_cls: type[_T],
+        strategy: SearchStrategy[_T],
+        serialize: Callable[[_T], str],
+    ) -> None:
+        default, value = data.draw(tuples(strategy, strategy))
+        self._run_test(test_cls, default, root, appname, serialize, value, eq)
+
+    def _run_test(
+        self,
+        test_cls: type[_T],
+        default: _T,
+        root: Path,
+        appname: str,
+        serialize: Callable[[_T], str],
+        value: _T,
+        equal: Callable[[_T, _T], bool],
+        /,
+    ) -> None:
+        @dataclass(frozen=True, kw_only=True, slots=True)
+        class Settings:
+            value: test_cls = default  # pyright: ignore[reportInvalidTypeForm]
+
+        settings_default = load_settings(
+            Settings, loaders=[], converter=ExtendedTSConverter()
+        )
+        assert settings_default.value == default
+        _ = hash(settings_default)
+        file = Path(root, "file.toml")
+        with file.open(mode="w") as fh:
+            _ = fh.write(f'[{appname}]\nvalue = "{serialize(value)}"')
+        settings_loaded = load_settings(
+            Settings,
+            loaders=[FileLoader(formats={"*.toml": TomlFormat(appname)}, files=[file])],
+            converter=ExtendedTSConverter(),
+        )
+        assert equal(settings_loaded.value, value)

{dycw_utilities-0.131.13 → dycw_utilities-0.131.15}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.131.13"
+__version__ = "0.131.15"

{dycw_utilities-0.131.13 → dycw_utilities-0.131.15}/src/utilities/hypothesis.py

@@ -716,85 +716,6 @@ def lists_fixed_length(
 ##
 
 
-@composite
-def min_and_max_datetimes(
-    draw: DrawFn,
-    /,
-    *,
-    min_value: MaybeSearchStrategy[dt.datetime | None] = None,
-    max_value: MaybeSearchStrategy[dt.datetime | None] = None,
-    time_zone: MaybeSearchStrategy[ZoneInfo | timezone] = UTC,
-    round_: MathRoundMode | None = None,
-    timedelta: dt.timedelta | None = None,
-    rel_tol: float | None = None,
-    abs_tol: float | None = None,
-    valid: bool = False,
-) -> tuple[dt.datetime, dt.datetime]:
-    """Strategy for generating min/max datetimes."""
-    match min_value, max_value:
-        case None, None:
-            return draw(
-                pairs(
-                    zoned_datetimes(
-                        time_zone=time_zone,
-                        round_=round_,
-                        timedelta=timedelta,
-                        rel_tol=rel_tol,
-                        abs_tol=abs_tol,
-                        valid=valid,
-                    ),
-                    sorted=True,
-                )
-            )
-        case None, dt.datetime():
-            min_value_ = draw(
-                zoned_datetimes(
-                    max_value=max_value,
-                    time_zone=time_zone,
-                    round_=round_,
-                    timedelta=timedelta,
-                    rel_tol=rel_tol,
-                    abs_tol=abs_tol,
-                    valid=valid,
-                )
-            )
-            return min_value_, max_value
-        case dt.datetime(), None:
-            max_value_ = draw(
-                zoned_datetimes(
-                    min_value=min_value,
-                    time_zone=time_zone,
-                    round_=round_,
-                    timedelta=timedelta,
-                    rel_tol=rel_tol,
-                    abs_tol=abs_tol,
-                    valid=valid,
-                )
-            )
-            return min_value, max_value_
-        case dt.datetime(), dt.datetime():
-            _ = assume(min_value <= max_value)
-            return min_value, max_value
-        case _, _:
-            strategy = zoned_datetimes(
-                time_zone=time_zone,
-                round_=round_,
-                timedelta=timedelta,
-                rel_tol=rel_tol,
-                abs_tol=abs_tol,
-                valid=valid,
-            )
-            min_value_ = draw2(draw, min_value, strategy)
-            max_value_ = draw2(draw, max_value, strategy)
-            _ = assume(min_value_ <= max_value_)
-            return min_value_, max_value_
-        case _ as never:
-            assert_never(never)
-
-
-##
-
-
 @composite
 def months(
     draw: DrawFn,
@@ -1561,14 +1482,12 @@ __all__ = [
     "int64s",
     "int_arrays",
     "lists_fixed_length",
-    "min_and_max_datetimes",
     "months",
     "namespace_mixins",
     "numbers",
     "pairs",
     "paths",
     "plain_datetimes",
-    "plain_datetimes",
     "plain_datetimes_whenever",
     "random_states",
     "sentinels",

dycw_utilities-0.131.15/src/utilities/luigi.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    TypeVar,
+    assert_never,
+    cast,
+    overload,
+    override,
+)
+
+import luigi
+from luigi import Parameter, PathParameter, Target, Task
+from luigi import build as _build
+from luigi.parameter import ParameterVisibility, _no_value
+from whenever import ZonedDateTime
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+
+    from luigi.execution_summary import LuigiRunResult
+
+    from utilities.types import DateTimeRoundUnit, LogLevel, PathLike, ZonedDateTimeLike
+
+
+_T = TypeVar("_T")
+
+
+# parameters
+
+
+class ZonedDateTimeParameter(Parameter):
+    """A parameter which takes the value of a zoned datetime."""
+
+    _unit: DateTimeRoundUnit
+    _increment: int
+
+    @override
+    def __init__(
+        self,
+        default: Any = _no_value,
+        is_global: bool = False,
+        significant: bool = True,
+        description: str | None = None,
+        config_path: None = None,
+        positional: bool = True,
+        always_in_help: bool = False,
+        batch_method: Callable[[Iterable[_T]], _T] | None = None,
+        visibility: ParameterVisibility = ParameterVisibility.PUBLIC,
+        *,
+        unit: DateTimeRoundUnit = "second",
+        increment: int = 1,
+    ) -> None:
+        super().__init__(
+            default,
+            is_global,
+            significant,
+            description,
+            config_path,
+            positional,
+            always_in_help,
+            batch_method,
+            visibility,
+        )
+        self._unit = unit
+        self._increment = increment
+
+    @override
+    def normalize(self, x: ZonedDateTimeLike) -> ZonedDateTime:
+        match x:
+            case ZonedDateTime() as date_time:
+                ...
+            case str() as text:
+                date_time = ZonedDateTime.parse_common_iso(text)
+            case _ as never:
+                assert_never(never)
+        return date_time.round(self._unit, increment=self._increment, mode="floor")
+
+    @override
+    def parse(self, x: str) -> ZonedDateTime:
+        return ZonedDateTime.parse_common_iso(x)
+
+    @override
+    def serialize(self, x: ZonedDateTime) -> str:
+        return x.format_common_iso()
+
+
+# targets
+
+
+class PathTarget(Target):
+    """A local target whose `path` attribute is a Pathlib instance."""
+
+    def __init__(self, path: PathLike, /) -> None:
+        super().__init__()
+        self.path = Path(path)
+
+    @override
+    def exists(self) -> bool:  # pyright: ignore[reportIncompatibleMethodOverride]
+        """Check if the target exists."""
+        return self.path.exists()
+
+
+# tasks
+
+
+class ExternalTask(ABC, luigi.ExternalTask):
+    """An external task with `exists()` defined here."""
+
+    @abstractmethod
+    def exists(self) -> bool:
+        """Predicate on which the external task is deemed to exist."""
+        msg = f"{self=}"  # pragma: no cover
+        raise NotImplementedError(msg)  # pragma: no cover
+
+    @override
+    def output(self) -> _ExternalTaskDummyTarget:  # pyright: ignore[reportIncompatibleMethodOverride]
+        return _ExternalTaskDummyTarget(self)
+
+
+class _ExternalTaskDummyTarget(Target):
+    """Dummy target for `ExternalTask`."""
+
+    def __init__(self, task: ExternalTask, /) -> None:
+        super().__init__()
+        self._task = task
+
+    @override
+    def exists(self) -> bool:  # pyright: ignore[reportIncompatibleMethodOverride]
+        return self._task.exists()
+
+
+class ExternalFile(ExternalTask):
+    """Await an external file on the local disk."""
+
+    path: Path = cast("Any", PathParameter())
+
+    @override
+    def exists(self) -> bool:
+        return self.path.exists()
+
+
+# functions
+
+
+@overload
+def build(
+    task: Iterable[Task],
+    /,
+    *,
+    detailed_summary: Literal[False] = False,
+    local_scheduler: bool = False,
+    log_level: LogLevel | None = None,
+    workers: int | None = None,
+) -> bool: ...
+@overload
+def build(
+    task: Iterable[Task],
+    /,
+    *,
+    detailed_summary: Literal[True],
+    local_scheduler: bool = False,
+    log_level: LogLevel | None = None,
+    workers: int | None = None,
+) -> LuigiRunResult: ...
+def build(
+    task: Iterable[Task],
+    /,
+    *,
+    detailed_summary: bool = False,
+    local_scheduler: bool = False,
+    log_level: LogLevel | None = None,
+    workers: int | None = None,
+) -> bool | LuigiRunResult:
+    """Build a set of tasks."""
+    return _build(
+        task,
+        detailed_summary=detailed_summary,
+        local_scheduler=local_scheduler,
+        **({} if log_level is None else {"log_level": log_level}),
+        **({} if workers is None else {"workers": workers}),
+    )
+
+
+__all__ = [
+    "ExternalFile",
+    "ExternalTask",
+    "PathTarget",
+    "ZonedDateTimeParameter",
+    "build",
+]

dycw_utilities-0.131.15/src/utilities/typed_settings.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypeVar, override
+
+from typed_settings.converters import TSConverter
+from whenever import (
+    Date,
+    DateDelta,
+    DateTimeDelta,
+    PlainDateTime,
+    Time,
+    TimeDelta,
+    ZonedDateTime,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+_T = TypeVar("_T")
+
+
+class ExtendedTSConverter(TSConverter):
+    """An extension of the TSConverter for custom types."""
+
+    @override
+    def __init__(
+        self,
+        *,
+        resolve_paths: bool = True,
+        strlist_sep: str | Callable[[str], list] | None = ":",
+    ) -> None:
+        super().__init__(resolve_paths=resolve_paths, strlist_sep=strlist_sep)
+        cases: list[tuple[type[Any], Callable[..., Any]]] = [
+            (Date, Date.parse_common_iso),
+            (DateDelta, DateDelta.parse_common_iso),
+            (DateTimeDelta, DateTimeDelta.parse_common_iso),
+            (PlainDateTime, PlainDateTime.parse_common_iso),
+            (Time, Time.parse_common_iso),
+            (TimeDelta, TimeDelta.parse_common_iso),
+            (ZonedDateTime, ZonedDateTime.parse_common_iso),
+        ]
+        extras = {cls: _make_converter(cls, func) for cls, func in cases}
+        self.scalar_converters |= extras
+
+
+def _make_converter(
+    cls: type[_T], parser: Callable[[str], _T], /
+) -> Callable[[Any, type[Any]], Any]:
+    def hook(value: _T | str, _: type[_T] = cls, /) -> Any:
+        if not isinstance(value, (cls, str)):  # pragma: no cover
+            msg = f"Invalid type {type(value).__name__!r}; expected '{cls.__name__}' or 'str'"
+            raise TypeError(msg)
+        if isinstance(value, str):
+            return parser(value)
+        return value
+
+    return hook
+
+
+__all__ = ["ExtendedTSConverter"]