dycw-utilities 0.129.10__py3-none-any.whl → 0.175.17__py3-none-any.whl

utilities/luigi.py

@@ -1,228 +0,0 @@
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal, cast, overload, override
-
-import luigi
-from luigi import Parameter, PathParameter, Target, Task
-from luigi import build as _build
-
-from utilities.datetime import EPOCH_UTC
-
-if TYPE_CHECKING:
-    import datetime as dt
-    from collections.abc import Iterable
-
-    from luigi.execution_summary import LuigiRunResult
-
-    from utilities.types import LogLevel, MaybeStr, PathLike
-
-
-# parameters
-
-
-class DateHourParameter(luigi.DateHourParameter):
-    """A parameter which takes the value of an hourly `dt.datetime`."""
-
-    def __init__(self, interval: int = 1, **kwargs: Any) -> None:
-        super().__init__(interval, EPOCH_UTC, **kwargs)
-
-    @override
-    def normalize(self, dt: MaybeStr[dt.datetime]) -> dt.datetime:
-        from utilities.whenever import ensure_zoned_datetime
-
-        return ensure_zoned_datetime(dt)
-
-    @override
-    def parse(self, s: str) -> dt.datetime:
-        from utilities.whenever import parse_zoned_datetime
-
-        return parse_zoned_datetime(s)
-
-    @override
-    def serialize(self, dt: dt.datetime) -> str:
-        from utilities.whenever import serialize_zoned_datetime
-
-        return serialize_zoned_datetime(dt)
-
-
-class DateMinuteParameter(luigi.DateMinuteParameter):
-    """A parameter which takes the value of a minutely `dt.datetime`."""
-
-    def __init__(self, interval: int = 1, **kwargs: Any) -> None:
-        super().__init__(interval=interval, start=EPOCH_UTC, **kwargs)
-
-    @override
-    def normalize(self, dt: MaybeStr[dt.datetime]) -> dt.datetime:
-        from utilities.whenever import ensure_zoned_datetime
-
-        return ensure_zoned_datetime(dt)
-
-    @override
-    def parse(self, s: str) -> dt.datetime:
-        from utilities.whenever import parse_zoned_datetime
-
-        return parse_zoned_datetime(s)
-
-    @override
-    def serialize(self, dt: dt.datetime) -> str:
-        from utilities.whenever import serialize_zoned_datetime
-
-        return serialize_zoned_datetime(dt)
-
-
-class DateSecondParameter(luigi.DateSecondParameter):
-    """A parameter which takes the value of a secondly `dt.datetime`."""
-
-    def __init__(self, interval: int = 1, **kwargs: Any) -> None:
-        super().__init__(interval, EPOCH_UTC, **kwargs)
-
-    @override
-    def normalize(self, dt: MaybeStr[dt.datetime]) -> dt.datetime:
-        from utilities.whenever import ensure_zoned_datetime
-
-        return ensure_zoned_datetime(dt)
-
-    @override
-    def parse(self, s: str) -> dt.datetime:
-        from utilities.whenever import parse_zoned_datetime
-
-        return parse_zoned_datetime(s)
-
-    @override
-    def serialize(self, dt: dt.datetime) -> str:
-        from utilities.whenever import serialize_zoned_datetime
-
-        return serialize_zoned_datetime(dt)
-
-
-class TimeParameter(Parameter):
-    """A parameter which takes the value of a `dt.time`."""
-
-    @override
-    def normalize(self, x: MaybeStr[dt.time]) -> dt.time:
-        from utilities.whenever import ensure_time
-
-        return ensure_time(x)
-
-    @override
-    def parse(self, x: str) -> dt.time:
-        from utilities.whenever import parse_time
-
-        return parse_time(x)
-
-    @override
-    def serialize(self, x: dt.time) -> str:
-        from utilities.whenever import serialize_time
-
-        return serialize_time(x)
-
-
-# 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__ = [
-    "DateHourParameter",
-    "DateMinuteParameter",
-    "DateSecondParameter",
-    "ExternalFile",
-    "ExternalTask",
-    "PathTarget",
-    "TimeParameter",
-    "build",
-]

utilities/period.py

@@ -1,324 +0,0 @@
-from __future__ import annotations
-
-import datetime as dt
-from dataclasses import dataclass, field
-from functools import cached_property
-from itertools import permutations
-from typing import (
-    TYPE_CHECKING,
-    Generic,
-    Literal,
-    Self,
-    TypedDict,
-    TypeVar,
-    assert_never,
-    cast,
-    override,
-)
-
-from utilities.datetime import ZERO_TIME
-from utilities.functions import get_class_name
-from utilities.iterables import OneUniqueNonUniqueError, always_iterable, one_unique
-from utilities.sentinel import Sentinel, sentinel
-from utilities.typing import is_instance_gen
-from utilities.whenever import (
-    serialize_date,
-    serialize_plain_datetime,
-    serialize_zoned_datetime,
-)
-from utilities.zoneinfo import EnsureTimeZoneError, ensure_time_zone
-
-if TYPE_CHECKING:
-    from zoneinfo import ZoneInfo
-
-    from utilities.iterables import MaybeIterable
-    from utilities.types import DateOrDateTime
-
-
-type _DateOrDateTime = Literal["date", "datetime"]
-_TPeriod = TypeVar("_TPeriod", dt.date, dt.datetime)
-
-
-class _PeriodAsDict(TypedDict, Generic[_TPeriod]):
-    start: _TPeriod
-    end: _TPeriod
-
-
-@dataclass(repr=False, order=True, unsafe_hash=True)
-class Period(Generic[_TPeriod]):
-    """A period of time."""
-
-    start: _TPeriod
-    end: _TPeriod
-    req_duration: MaybeIterable[dt.timedelta] | None = field(
-        default=None, repr=False, kw_only=True
-    )
-    min_duration: dt.timedelta | None = field(default=None, repr=False, kw_only=True)
-    max_duration: dt.timedelta | None = field(default=None, repr=False, kw_only=True)
-
-    def __post_init__(self) -> None:
-        if any(
-            is_instance_gen(left, cls) is not is_instance_gen(right, cls)
-            for left, right in permutations([self.start, self.end], 2)
-            for cls in [dt.date, dt.datetime]
-        ):
-            raise _PeriodDateAndDateTimeMixedError(start=self.start, end=self.end)
-        for date in [self.start, self.end]:
-            if isinstance(date, dt.datetime):
-                try:
-                    _ = ensure_time_zone(date)
-                except EnsureTimeZoneError:
-                    raise _PeriodNaiveDateTimeError(
-                        start=self.start, end=self.end
-                    ) from None
-        duration = self.end - self.start
-        if duration < ZERO_TIME:
-            raise _PeriodInvalidError(start=self.start, end=self.end)
-        if (self.req_duration is not None) and (
-            duration not in always_iterable(self.req_duration)
-        ):
-            raise _PeriodReqDurationError(
-                start=self.start,
-                end=self.end,
-                duration=duration,
-                req_duration=self.req_duration,
-            )
-        if (self.min_duration is not None) and (duration < self.min_duration):
-            raise _PeriodMinDurationError(
-                start=self.start,
-                end=self.end,
-                duration=duration,
-                min_duration=self.min_duration,
-            )
-        if (self.max_duration is not None) and (duration > self.max_duration):
-            raise _PeriodMaxDurationError(
-                start=self.start,
-                end=self.end,
-                duration=duration,
-                max_duration=self.max_duration,
-            )
-
-    def __add__(self, other: dt.timedelta, /) -> Self:
-        """Offset the period."""
-        return self.replace(start=self.start + other, end=self.end + other)
-
-    def __contains__(self, other: DateOrDateTime, /) -> bool:
-        """Check if a date/datetime lies in the period."""
-        match self.kind:
-            case "date":
-                if isinstance(other, dt.datetime):
-                    raise _PeriodDateContainsDateTimeError(
-                        start=self.start, end=self.end
-                    )
-            case "datetime":
-                if not isinstance(other, dt.datetime):
-                    raise _PeriodDateTimeContainsDateError(
-                        start=self.start, end=self.end
-                    )
-            case _ as never:
-                assert_never(never)
-        return self.start <= other <= self.end
-
-    @override
-    def __repr__(self) -> str:
-        cls = get_class_name(self)
-        match self.kind:
-            case "date":
-                result = cast("Period[dt.date]", self)
-                start, end = map(serialize_date, [result.start, result.end])
-                return f"{cls}({start}, {end})"
-            case "datetime":
-                result = cast("Period[dt.datetime]", self)
-                try:
-                    time_zone = result.time_zone
-                except _PeriodTimeZoneNonUniqueError:
-                    start, end = map(
-                        serialize_zoned_datetime, [result.start, result.end]
-                    )
-                    return f"{cls}({start}, {end})"
-                start, end = (
-                    serialize_plain_datetime(t.replace(tzinfo=None))
-                    for t in [result.start, result.end]
-                )
-                return f"{cls}({start}, {end}, {time_zone})"
-            case _ as never:
-                assert_never(never)
-
-    def __sub__(self, other: dt.timedelta, /) -> Self:
-        """Offset the period."""
-        return self.replace(start=self.start - other, end=self.end - other)
-
-    def astimezone(self, time_zone: ZoneInfo, /) -> Self:
-        """Convert the timezone of the period, if it is a datetime period."""
-        match self.kind:
-            case "date":
-                raise _PeriodAsTimeZoneInapplicableError(start=self.start, end=self.end)
-            case "datetime":
-                result = cast("Period[dt.datetime]", self)
-                result = result.replace(
-                    start=result.start.astimezone(time_zone),
-                    end=result.end.astimezone(time_zone),
-                )
-                return cast("Self", result)
-            case _ as never:
-                assert_never(never)
-
-    @cached_property
-    def duration(self) -> dt.timedelta:
-        """The duration of the period."""
-        return self.end - self.start
-
-    @cached_property
-    def kind(self) -> _DateOrDateTime:
-        """The kind of the period."""
-        return "date" if is_instance_gen(self.start, dt.date) else "datetime"
-
-    def replace(
-        self,
-        *,
-        start: _TPeriod | None = None,
-        end: _TPeriod | None = None,
-        req_duration: MaybeIterable[dt.timedelta] | None | Sentinel = sentinel,
-        min_duration: dt.timedelta | None | Sentinel = sentinel,
-        max_duration: dt.timedelta | None | Sentinel = sentinel,
-    ) -> Self:
-        """Replace elements of the period."""
-        return type(self)(
-            self.start if start is None else start,
-            self.end if end is None else end,
-            req_duration=self.req_duration
-            if isinstance(req_duration, Sentinel)
-            else req_duration,
-            min_duration=self.min_duration
-            if isinstance(min_duration, Sentinel)
-            else min_duration,
-            max_duration=self.max_duration
-            if isinstance(max_duration, Sentinel)
-            else max_duration,
-        )
-
-    @cached_property
-    def time_zone(self) -> ZoneInfo:
-        """The time zone of the period."""
-        match self.kind:
-            case "date":
-                raise _PeriodTimeZoneInapplicableError(
-                    start=self.start, end=self.end
-                ) from None
-            case "datetime":
-                result = cast("Period[dt.datetime]", self)
-                try:
-                    return one_unique(map(ensure_time_zone, [result.start, result.end]))
-                except OneUniqueNonUniqueError as error:
-                    raise _PeriodTimeZoneNonUniqueError(
-                        start=self.start,
-                        end=self.end,
-                        first=error.first,
-                        second=error.second,
-                    ) from None
-            case _ as never:
-                assert_never(never)
-
-    def to_dict(self) -> _PeriodAsDict:
-        """Convert the period to a dictionary."""
-        return {"start": self.start, "end": self.end}
-
-
-@dataclass(kw_only=True, slots=True)
-class PeriodError(Generic[_TPeriod], Exception):
-    start: _TPeriod
-    end: _TPeriod
-
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodDateAndDateTimeMixedError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return f"Invalid period; got date and datetime mix ({self.start}, {self.end})"
-
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodNaiveDateTimeError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return f"Invalid period; got naive datetime(s) ({self.start}, {self.end})"
-
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodInvalidError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return f"Invalid period; got {self.start} > {self.end}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodReqDurationError(PeriodError[_TPeriod]):
-    duration: dt.timedelta
-    req_duration: MaybeIterable[dt.timedelta]
-
-    @override
-    def __str__(self) -> str:
-        return f"Period must have duration {self.req_duration}; got {self.duration})"
-
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodMinDurationError(PeriodError[_TPeriod]):
-    duration: dt.timedelta
-    min_duration: dt.timedelta
-
-    @override
-    def __str__(self) -> str:
-        return (
-            f"Period must have min duration {self.min_duration}; got {self.duration})"
-        )
-
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodMaxDurationError(PeriodError[_TPeriod]):
-    duration: dt.timedelta
-    max_duration: dt.timedelta
-
-    @override
-    def __str__(self) -> str:
-        return f"Period must have duration at most {self.max_duration}; got {self.duration})"
-
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodAsTimeZoneInapplicableError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return "Period of dates does not have a timezone attribute"
-
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodDateContainsDateTimeError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return "Period of dates cannot contain datetimes"
-
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodDateTimeContainsDateError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return "Period of datetimes cannot contain dates"
-
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodTimeZoneInapplicableError(PeriodError[_TPeriod]):
-    @override
-    def __str__(self) -> str:
-        return "Period of dates does not have a timezone attribute"
-
-
-@dataclass(kw_only=True, slots=True)
-class _PeriodTimeZoneNonUniqueError(PeriodError[_TPeriod]):
-    first: ZoneInfo
-    second: ZoneInfo
-
-    @override
-    def __str__(self) -> str:
-        return f"Period must contain exactly one time zone; got {self.first} and {self.second}"
-
-
-__all__ = ["Period", "PeriodError"]

utilities/pyrsistent.py

@@ -1,89 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any, TypeVar, dataclass_transform, overload
-
-from pyrsistent import PRecord as _PRecord
-from pyrsistent import field as _field
-from pyrsistent._field_common import (
-    PFIELD_NO_FACTORY,
-    PFIELD_NO_INITIAL,
-    PFIELD_NO_INVARIANT,
-    PFIELD_NO_SERIALIZER,
-    PFIELD_NO_TYPE,
-)
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-    from utilities.types import TypeLike
-
-
-_T = TypeVar("_T")
-_U = TypeVar("_U")
-
-
-@overload
-def field(
-    *,
-    type: type[_T],
-    invariant: Callable[[Any], tuple[bool, Any]] = ...,
-    default: Any = ...,
-    mandatory: bool = ...,
-    factory: Callable[[_U], _U] = ...,
-    serializer: Callable[[Any, Any], Any] = ...,
-) -> _T: ...
-@overload
-def field(
-    *,
-    type: tuple[type[_T]],
-    invariant: Callable[[Any], tuple[bool, Any]] = ...,
-    default: Any = ...,
-    mandatory: bool = ...,
-    factory: Callable[[_U], _U] = ...,
-    serializer: Callable[[Any, Any], Any] = ...,
-) -> _T: ...
-@overload
-def field(
-    *,
-    type: tuple[type[_T], type[_U]],
-    invariant: Callable[[Any], tuple[bool, Any]] = ...,
-    default: Any = ...,
-    mandatory: bool = ...,
-    factory: Callable[[_U], _U] = ...,
-    serializer: Callable[[Any, Any], Any] = ...,
-) -> _T | _U: ...
-@overload
-def field(
-    *,
-    type: tuple[Any, ...] = ...,
-    invariant: Callable[[Any], tuple[bool, Any]] = ...,
-    default: Any = ...,
-    mandatory: bool = ...,
-    factory: Callable[[_U], _U] = ...,
-    serializer: Callable[[Any, Any], Any] = ...,
-) -> Any: ...
-def field(
-    *,
-    type: TypeLike[_T] = PFIELD_NO_TYPE,  # noqa: A002
-    invariant: Callable[[Any], tuple[bool, Any]] = PFIELD_NO_INVARIANT,
-    default: Any = PFIELD_NO_INITIAL,
-    mandatory: bool = False,
-    factory: Callable[[_U], _U] = PFIELD_NO_FACTORY,
-    serializer: Callable[[Any, Any], Any] = PFIELD_NO_SERIALIZER,
-) -> Any:
-    """Field specification factory for :py:class:`PRecord`."""
-    return _field(
-        type=type,
-        invariant=invariant,
-        initial=default,
-        mandatory=mandatory,
-        factory=factory,
-        serializer=serializer,
-    )
-
-
-@dataclass_transform(kw_only_default=True, field_specifiers=(field,))
-class PRecord(_PRecord): ...
-
-
-__all__ = ["PRecord", "field"]