pyfect-dev 0.1.0__py3-none-any.whl

pyfect/crypto.py

@@ -0,0 +1,257 @@
+"""Cryptographically secure random values and message digests as a service
+(Effect's ``Crypto``)::
+
+    c = yield from Crypto()
+    token = yield from c.random_bytes(32)
+    uuid = yield from c.random_uuid_v7()
+    digest = yield from c.digest("SHA-256", b"hello")
+
+``make(random_bytes=, digest=)`` builds a service from the two primitives;
+every other operation (numbers, shuffles, UUIDv4 / UUIDv7, ULIDs) is
+derived from ``random_bytes``, as in Effect. ``layer`` is the host's
+(``os.urandom`` and ``hashlib``); ``platform.layer`` includes it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import os
+from collections.abc import Callable, Iterable
+from typing import Literal, overload
+
+from pyfect._core import Effect
+from pyfect._isaac import between_of
+from pyfect.clock import clock_with, now_millis_unsafe
+from pyfect.context import Tag
+from pyfect.effect import fail, succeed, sync, try_
+from pyfect.layer import Layer
+from pyfect.layer import succeed as layer_succeed
+from pyfect.platform_error import PlatformError, bad_argument, system_error
+
+type DigestAlgorithm = Literal["SHA-1", "SHA-256", "SHA-384", "SHA-512"]
+"""SHA-1 is there for existing protocols; do not use it for new designs."""
+
+type UuidFormat = Literal["hex", "bytes"]
+
+_MAX_SAFE = 2**53 - 1
+_MAX_TIMESTAMP = 2**48 - 1
+
+
+class CryptoService:
+    """Effect's ``Crypto``; build one with ``make``."""
+
+    __slots__ = ("_digest", "_random_bytes")
+
+    def __init__(
+        self,
+        random_bytes: Callable[[int], bytes],
+        digest: Callable[[DigestAlgorithm, bytes], Effect[bytes, PlatformError]],
+    ) -> None:
+        self._random_bytes = random_bytes
+        self._digest = digest
+
+    def _uint53(self, data: bytes) -> int:
+        return int.from_bytes(bytes([data[0] & 0x1F]) + data[1:7])
+
+    def next_double_unsafe(self) -> float:
+        """A random float in ``[0, 1)`` from 53 random bits."""
+        return self._uint53(self._random_bytes(7)) / 2**53
+
+    def next_int_unsafe(self) -> int:
+        """A random integer between ``-(2**53 - 1)`` and ``2**53 - 1``,
+        both inclusive, each equally likely."""
+        while True:
+            data = self._random_bytes(7)
+            value = self._uint53(data)
+            if data[0] & 0x20 == 0:
+                return value - _MAX_SAFE
+            if value < _MAX_SAFE:
+                return value + 1
+
+    def random_bytes(self, size: int) -> Effect[bytes, PlatformError]:
+        """``size`` secure random bytes; fails for a size below 0 or past
+        ``2**53 - 1``."""
+        if not 0 <= size <= _MAX_SAFE:
+            return fail(
+                bad_argument(
+                    module="Crypto",
+                    method="random_bytes",
+                    description="size must be a non-negative safe integer",
+                )
+            )
+        return sync(lambda: self._random_bytes(size))
+
+    def digest(self, algorithm: DigestAlgorithm, data: bytes) -> Effect[bytes, PlatformError]:
+        """The ``algorithm`` digest of ``data``."""
+        return self._digest(algorithm, data)
+
+    @property
+    def random(self) -> Effect[float]:
+        """A secure random float in ``[0, 1)``."""
+        return sync(self.next_double_unsafe)
+
+    @property
+    def random_boolean(self) -> Effect[bool]:
+        return sync(lambda: self.next_double_unsafe() > 0.5)
+
+    @property
+    def random_int(self) -> Effect[int]:
+        """A secure random integer between ``-(2**53 - 1)`` and ``2**53 - 1``."""
+        return sync(self.next_int_unsafe)
+
+    def random_between(self, low: float, high: float) -> Effect[float]:
+        """A secure random float in ``[low, high)``."""
+        return sync(lambda: between_of(low, high, self.next_double_unsafe()))
+
+    def random_int_between(
+        self, low: float, high: float, *, half_open: bool = False
+    ) -> Effect[int]:
+        """A secure random integer from ``ceil(low)`` to ``floor(high)``,
+        inclusive unless ``half_open``."""
+        low_int, high_int = math.ceil(low), math.floor(high)
+        span = high_int - low_int + (0 if half_open else 1)
+        return sync(lambda: math.floor(self.next_double_unsafe() * span) + low_int)
+
+    def random_shuffle[A](self, elements: Iterable[A]) -> Effect[list[A]]:
+        """A securely shuffled copy of ``elements``."""
+
+        def go() -> list[A]:
+            buffer = list(elements)
+            for i in range(len(buffer) - 1, 0, -1):
+                j = min(i, math.floor(self.next_double_unsafe() * (i + 1)))
+                buffer[i], buffer[j] = buffer[j], buffer[i]
+            return buffer
+
+        return sync(go)
+
+    @overload
+    def random_uuid_v4(self, *, format: Literal["hex"] = "hex") -> Effect[str, PlatformError]: ...
+    @overload
+    def random_uuid_v4(self, *, format: Literal["bytes"]) -> Effect[bytes, PlatformError]: ...
+    def random_uuid_v4(self, *, format: UuidFormat = "hex") -> Effect[str | bytes, PlatformError]:
+        """A UUIDv4: the lowercase hyphenated string (36 characters), or its
+        16 bytes with ``format="bytes"``."""
+        return sync(lambda: _formatted(uuid_v4_bytes(self._random_bytes(16)), format))
+
+    @overload
+    def random_uuid_v7(self, *, format: Literal["hex"] = "hex") -> Effect[str, PlatformError]: ...
+    @overload
+    def random_uuid_v7(self, *, format: Literal["bytes"]) -> Effect[bytes, PlatformError]: ...
+    def random_uuid_v7(self, *, format: UuidFormat = "hex") -> Effect[str | bytes, PlatformError]:
+        """A UUIDv7 holding the ``Clock``'s time in milliseconds."""
+        return clock_with(
+            lambda clock: succeed(
+                _formatted(uuid_v7_bytes(now_millis_unsafe(clock), self._random_bytes(16)), format)
+            )
+        )
+
+    @property
+    def random_ulid(self) -> Effect[str, PlatformError]:
+        """A ULID: 26 Crockford base32 characters, the ``Clock``'s time in
+        milliseconds (clamped to 48 bits) then 80 random bits."""
+        return clock_with(
+            lambda clock: succeed(ulid_string(now_millis_unsafe(clock), self._random_bytes(10)))
+        )
+
+
+class Crypto(Tag[CryptoService]):
+    """Secure random values and digests."""
+
+
+def make(
+    *,
+    random_bytes: Callable[[int], bytes],
+    digest: Callable[[DigestAlgorithm, bytes], Effect[bytes, PlatformError]],
+) -> CryptoService:
+    """A ``Crypto`` from a source of secure random bytes and a digest."""
+    return CryptoService(random_bytes, digest)
+
+
+# --- UUIDs and ULIDs (Effect's internal/uuid.ts and internal/ulid.ts) -------------
+
+
+def uuid_string(data: bytes) -> str:
+    """16 bytes as a lowercase hyphenated UUID."""
+    text = data.hex()
+    return f"{text[:8]}-{text[8:12]}-{text[12:16]}-{text[16:20]}-{text[20:32]}"
+
+
+def uuid_v4_bytes(data: bytes) -> bytes:
+    """``data`` (16 random bytes) with the version 4 and variant bits set."""
+    out = bytearray(data)
+    out[6] = (out[6] & 0x0F) | 0x40
+    out[8] = (out[8] & 0x3F) | 0x80
+    return bytes(out)
+
+
+def uuid_v7_bytes(timestamp_millis: int, data: bytes) -> bytes:
+    """``data`` (16 random bytes) with the timestamp (clamped to 48 bits) in
+    the first six and the version 7 and variant bits set."""
+    timestamp = min(max(0, timestamp_millis), _MAX_TIMESTAMP)
+    out = bytearray(data)
+    out[:6] = timestamp.to_bytes(6)
+    out[6] = (out[6] & 0x0F) | 0x70
+    out[8] = (out[8] & 0x3F) | 0x80
+    return bytes(out)
+
+
+_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+
+def ulid_string(timestamp_millis: int, data: bytes) -> str:
+    """A ULID from a millisecond timestamp (clamped to 48 bits) and 10
+    random bytes."""
+    timestamp = min(max(0, timestamp_millis), _MAX_TIMESTAMP)
+    head = "".join(_BASE32[(timestamp >> shift) & 0x1F] for shift in range(45, -1, -5))
+    bits = int.from_bytes(data)
+    tail = "".join(_BASE32[(bits >> shift) & 0x1F] for shift in range(75, -1, -5))
+    return head + tail
+
+
+def _formatted(data: bytes, format: UuidFormat) -> str | bytes:
+    return data if format == "bytes" else uuid_string(data)
+
+
+# --- the host's service -------------------------------------------------------------
+
+_HASHLIB_NAMES: dict[DigestAlgorithm, str] = {
+    "SHA-1": "sha1",
+    "SHA-256": "sha256",
+    "SHA-384": "sha384",
+    "SHA-512": "sha512",
+}
+
+
+def _host_digest(algorithm: DigestAlgorithm, data: bytes) -> Effect[bytes, PlatformError]:
+    return try_(
+        lambda: hashlib.new(_HASHLIB_NAMES[algorithm], data).digest(),
+        lambda cause: system_error(
+            "Unknown",
+            module="Crypto",
+            method="digest",
+            description="Could not compute digest",
+            cause=cause,
+        ),
+    )
+
+
+live: CryptoService = make(random_bytes=os.urandom, digest=_host_digest)
+"""The host's ``Crypto``: ``os.urandom`` and ``hashlib``."""
+
+layer: Layer[Crypto] = layer_succeed(Crypto, live)
+
+__all__ = [
+    "Crypto",
+    "CryptoService",
+    "DigestAlgorithm",
+    "PlatformError",
+    "UuidFormat",
+    "layer",
+    "live",
+    "make",
+    "ulid_string",
+    "uuid_string",
+    "uuid_v4_bytes",
+    "uuid_v7_bytes",
+]

pyfect/date_time/__init__.py

@@ -0,0 +1,77 @@
+"""Effect's DateTime over the standard library: a date-time is an aware
+``datetime``, a named zone a ``ZoneInfo``, a fixed offset a
+``datetime.timezone``. Naive datetimes are rejected with ``ValueError``.
+
+What the standard library already does well stays there
+(``astimezone``, ``replace``, ``isoformat``, ``timestamp``, comparison).
+This module adds the current time from ``Clock``, the
+``CurrentTimeZone`` service, elapsed-vs-calendar arithmetic (``add``),
+``start_of`` / ``end_of`` / ``nearest``, DST disambiguation
+(``make_zoned``) and RFC 9557 zoned strings."""
+
+from pyfect.date_time._calendar import Unit, add, end_of, nearest, start_of, subtract
+from pyfect.date_time._current import (
+    CurrentTimeZone,
+    is_future,
+    is_past,
+    layer_current_zone,
+    layer_current_zone_local,
+    layer_current_zone_named,
+    layer_current_zone_offset,
+    now,
+    now_in_current_zone,
+    set_zone_current,
+    with_current_zone,
+    with_current_zone_local,
+    with_current_zone_named,
+    with_current_zone_offset,
+    zone_named_effect,
+)
+from pyfect.date_time._iso import (
+    format_iso,
+    format_iso_zoned,
+    make_zoned_from_string,
+    zone_to_string,
+)
+from pyfect.date_time._zones import (
+    Disambiguation,
+    make_zoned,
+    zone_from_string,
+    zone_local,
+    zone_named,
+    zone_offset,
+)
+
+__all__ = [
+    "CurrentTimeZone",
+    "Disambiguation",
+    "Unit",
+    "add",
+    "end_of",
+    "format_iso",
+    "format_iso_zoned",
+    "is_future",
+    "is_past",
+    "layer_current_zone",
+    "layer_current_zone_local",
+    "layer_current_zone_named",
+    "layer_current_zone_offset",
+    "make_zoned",
+    "make_zoned_from_string",
+    "nearest",
+    "now",
+    "now_in_current_zone",
+    "set_zone_current",
+    "start_of",
+    "subtract",
+    "with_current_zone",
+    "with_current_zone_local",
+    "with_current_zone_named",
+    "with_current_zone_offset",
+    "zone_from_string",
+    "zone_local",
+    "zone_named",
+    "zone_named_effect",
+    "zone_offset",
+    "zone_to_string",
+]

pyfect/date_time/_calendar.py

@@ -0,0 +1,209 @@
+"""Calendar arithmetic on aware datetimes, as Effect's ``DateTime.add`` /
+``startOf`` / ``endOf`` / ``nearest``.
+
+Time units (hours and smaller) move the instant: ``add(dt, hours=24)`` is
+always 24 elapsed hours. Calendar units (days and larger) move the
+wall-clock time in ``dt``'s zone, then resolve it with
+``make_zoned(..., disambiguation="compatible")``. Plain ``dt +
+timedelta(hours=1)`` on a ``ZoneInfo`` datetime moves the wall clock
+instead, which is wrong for elapsed time across a DST change."""
+
+from __future__ import annotations
+
+import calendar
+from collections.abc import Callable
+from datetime import UTC, datetime, timedelta, tzinfo
+from decimal import Decimal
+from typing import Literal
+
+from pyfect.date_time._zones import make_zoned, zone_of
+
+_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
+_MICRO = timedelta(microseconds=1)
+
+type _DayUnit = Literal["day", "week", "month", "year"]
+type Unit = Literal["millisecond", "second", "minute", "hour"] | _DayUnit
+
+
+def add(
+    dt: datetime,
+    *,
+    years: int = 0,
+    months: int = 0,
+    weeks: int = 0,
+    days: int = 0,
+    hours: float = 0,
+    minutes: float = 0,
+    seconds: float = 0,
+    milliseconds: float = 0,
+    microseconds: float = 0,
+) -> datetime:
+    """``dt`` moved by the given units, keeping its zone. Months and years
+    clamp to the last day of the month (Jan 31 + 1 month = Feb 28/29).
+    Time units are added one at a time, smallest first, each sum cut to a
+    whole millisecond toward the epoch (Effect's ``setTime``)."""
+    zone = zone_of(dt, "dt")
+    epoch_millis = Decimal((dt - _EPOCH) // _MICRO) / 1_000
+    for amount, millis_per_unit in (
+        (microseconds, Decimal("0.001")),
+        (milliseconds, Decimal(1)),
+        (seconds, Decimal(1_000)),
+        (minutes, Decimal(60_000)),
+        (hours, Decimal(3_600_000)),
+    ):
+        if amount:
+            epoch_millis = _add_truncated(epoch_millis, amount, millis_per_unit)
+    shifted = (_EPOCH + timedelta(milliseconds=float(epoch_millis))).astimezone(zone)
+    if not (days or weeks or months or years):
+        return shifted
+
+    def move(wall: datetime) -> datetime:
+        wall += timedelta(days=days + 7 * weeks)
+        if months:
+            wall = _with_month(wall, wall.year * 12 + wall.month - 1 + months)
+        if years:
+            wall = _with_month(wall, (wall.year + years) * 12 + wall.month - 1)
+        return wall
+
+    return _on_wall_clock(shifted, zone, move)
+
+
+def subtract(
+    dt: datetime,
+    *,
+    years: int = 0,
+    months: int = 0,
+    weeks: int = 0,
+    days: int = 0,
+    hours: float = 0,
+    minutes: float = 0,
+    seconds: float = 0,
+    milliseconds: float = 0,
+    microseconds: float = 0,
+) -> datetime:
+    """``add`` with every unit negated."""
+    return add(
+        dt,
+        years=-years,
+        months=-months,
+        weeks=-weeks,
+        days=-days,
+        hours=-hours,
+        minutes=-minutes,
+        seconds=-seconds,
+        milliseconds=-milliseconds,
+        microseconds=-microseconds,
+    )
+
+
+def start_of(
+    dt: datetime, unit: Unit, *, week_starts_on: calendar.Day = calendar.SUNDAY
+) -> datetime:
+    """The first millisecond of ``dt``'s ``unit``, on its wall clock."""
+    return _on_wall_clock(dt, zone_of(dt, "dt"), lambda wall: _start(wall, unit, week_starts_on))
+
+
+def end_of(dt: datetime, unit: Unit, *, week_starts_on: calendar.Day = calendar.SUNDAY) -> datetime:
+    """The last millisecond of ``dt``'s ``unit``, on its wall clock
+    (``.999``)."""
+    return _on_wall_clock(dt, zone_of(dt, "dt"), lambda wall: _end(wall, unit, week_starts_on))
+
+
+def nearest(
+    dt: datetime, unit: Unit, *, week_starts_on: calendar.Day = calendar.SUNDAY
+) -> datetime:
+    """The start of ``dt``'s ``unit`` or of the next one, whichever is
+    closer on the wall clock; halfway rounds up."""
+    zone = zone_of(dt, "dt")
+
+    def round_wall(wall: datetime) -> datetime:
+        start = _start(wall, unit, week_starts_on)
+        after = _end(wall, unit, week_starts_on) + timedelta(milliseconds=1)
+        return start if wall - start < after - wall else after
+
+    return _on_wall_clock(dt, zone, round_wall)
+
+
+def _add_truncated(epoch_millis: Decimal, amount: float, millis_per_unit: Decimal) -> Decimal:
+    """``epoch_millis`` plus ``amount`` units, cut toward zero as
+    JavaScript's TimeClip cuts a time value. The float is read as the
+    decimal that prints it, so ``1.001`` seconds is 1,001ms."""
+    return Decimal(int(epoch_millis + Decimal(repr(amount)) * millis_per_unit))
+
+
+def _on_wall_clock(dt: datetime, zone: tzinfo, f: Callable[[datetime], datetime]) -> datetime:
+    """Apply ``f`` to ``dt``'s naive wall-clock time and resolve the result
+    in ``zone``."""
+    return make_zoned(f(dt.replace(tzinfo=None, fold=0)), zone)
+
+
+def _with_month(wall: datetime, month_index: int) -> datetime:
+    """``wall`` in month ``month_index`` (years * 12 + zero-based month),
+    with the day clamped to that month's length."""
+    year, month0 = divmod(month_index, 12)
+    last_day = calendar.monthrange(year, month0 + 1)[1]
+    return wall.replace(year=year, month=month0 + 1, day=min(wall.day, last_day))
+
+
+def _days_into_week(wall: datetime, week_starts_on: calendar.Day) -> int:
+    return (wall.weekday() - week_starts_on) % 7
+
+
+def _start(wall: datetime, unit: Unit, week_starts_on: calendar.Day) -> datetime:
+    match unit:
+        case "millisecond":
+            return wall.replace(microsecond=wall.microsecond // 1_000 * 1_000)
+        case "second":
+            return wall.replace(microsecond=0)
+        case "minute":
+            return wall.replace(second=0, microsecond=0)
+        case "hour":
+            return wall.replace(minute=0, second=0, microsecond=0)
+        case "day" | "week" | "month" | "year":
+            return _start_of_days(_midnight(wall), unit, week_starts_on)
+
+
+def _start_of_days(midnight: datetime, unit: _DayUnit, week_starts_on: calendar.Day) -> datetime:
+    match unit:
+        case "day":
+            return midnight
+        case "week":
+            return midnight - timedelta(days=_days_into_week(midnight, week_starts_on))
+        case "month":
+            return midnight.replace(day=1)
+        case "year":
+            return midnight.replace(month=1, day=1)
+
+
+def _end(wall: datetime, unit: Unit, week_starts_on: calendar.Day) -> datetime:
+    match unit:
+        case "millisecond":
+            return wall.replace(microsecond=wall.microsecond // 1_000 * 1_000)
+        case "second":
+            return wall.replace(microsecond=999_000)
+        case "minute":
+            return wall.replace(second=59, microsecond=999_000)
+        case "hour":
+            return wall.replace(minute=59, second=59, microsecond=999_000)
+        case "day" | "week" | "month" | "year":
+            return _end_of_days(_last_moment(wall), unit, week_starts_on)
+
+
+def _end_of_days(last: datetime, unit: _DayUnit, week_starts_on: calendar.Day) -> datetime:
+    match unit:
+        case "day":
+            return last
+        case "week":
+            return last + timedelta(days=6 - _days_into_week(last, week_starts_on))
+        case "month":
+            return last.replace(day=calendar.monthrange(last.year, last.month)[1])
+        case "year":
+            return last.replace(month=12, day=31)
+
+
+def _midnight(wall: datetime) -> datetime:
+    return wall.replace(hour=0, minute=0, second=0, microsecond=0)
+
+
+def _last_moment(wall: datetime) -> datetime:
+    return wall.replace(hour=23, minute=59, second=59, microsecond=999_000)

pyfect/date_time/_current.py

@@ -0,0 +1,118 @@
+"""The effectful parts of DateTime: the current time from ``Clock`` and
+the ``CurrentTimeZone`` service."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta, tzinfo
+from typing import Never
+
+from pyfect._context_effects import _ProvideServiceEffect, provide_service_effect
+from pyfect._core import Effect
+from pyfect.clock import Clock
+from pyfect.context import Tag
+from pyfect.date_time._zones import zone_local, zone_named, zone_of, zone_offset
+from pyfect.duration import Duration, to_seconds
+from pyfect.effect import _ProvideService, fail, provide_service, succeed, suspend, sync
+from pyfect.errors import IllegalArgumentError
+from pyfect.layer import Layer
+from pyfect.layer import effect as layer_effect
+from pyfect.layer import succeed as layer_succeed
+from pyfect.layer import sync as layer_sync
+
+_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
+
+
+class CurrentTimeZone(Tag[tzinfo], key="effect/DateTime/CurrentTimeZone"):
+    """The zone ``now_in_current_zone`` and ``set_zone_current`` use."""
+
+
+def now() -> Effect[datetime]:
+    """The ``Clock``'s wall time as an aware UTC datetime (to the
+    millisecond, as Effect's)."""
+    return Clock().map(lambda c: _EPOCH + timedelta(milliseconds=c.now_nanos_unsafe() // 1_000_000))
+
+
+def now_in_current_zone() -> Effect[datetime, Never, CurrentTimeZone]:
+    """``now()`` in the ``CurrentTimeZone``."""
+    return now().flat_map(set_zone_current)
+
+
+def set_zone_current(dt: datetime) -> Effect[datetime, Never, CurrentTimeZone]:
+    """The same instant as ``dt``, in the ``CurrentTimeZone``."""
+    zone_of(dt, "dt")
+    return CurrentTimeZone().map(dt.astimezone)
+
+
+def is_future(dt: datetime) -> Effect[bool]:
+    """Whether ``dt`` is after the ``Clock``'s current time."""
+    zone_of(dt, "dt")
+    return now().map(lambda current: current < dt)
+
+
+def is_past(dt: datetime) -> Effect[bool]:
+    """Whether ``dt`` is before the ``Clock``'s current time."""
+    zone_of(dt, "dt")
+    return now().map(lambda current: current > dt)
+
+
+def zone_named_effect(zone_id: str) -> Effect[tzinfo, IllegalArgumentError]:
+    """The IANA zone ``zone_id``; fails with ``IllegalArgumentError`` if
+    there is none."""
+
+    def check() -> Effect[tzinfo, IllegalArgumentError]:
+        zone = zone_named(zone_id)
+        if zone is None:
+            return fail(IllegalArgumentError(f"Invalid time zone: {zone_id}"))
+        return succeed(zone)
+
+    return suspend(check)
+
+
+def _offset_zone(offset: Duration) -> tzinfo:
+    zone = zone_offset(timedelta(seconds=to_seconds(offset)))
+    if zone is None:
+        raise ValueError(f"a zone offset must be strictly within a day, got {offset!r}")
+    return zone
+
+
+def with_current_zone(zone: tzinfo) -> _ProvideService[tzinfo, CurrentTimeZone]:
+    """Provide ``zone`` as the ``CurrentTimeZone``. Use with ``.pipe``."""
+    return provide_service(CurrentTimeZone, zone)
+
+
+def with_current_zone_offset(offset: Duration) -> _ProvideService[tzinfo, CurrentTimeZone]:
+    """Provide the fixed offset ``offset`` from UTC as the
+    ``CurrentTimeZone``. Use with ``.pipe``."""
+    return with_current_zone(_offset_zone(offset))
+
+
+def with_current_zone_named(
+    zone_id: str,
+) -> _ProvideServiceEffect[CurrentTimeZone, IllegalArgumentError, Never]:
+    """Provide the IANA zone ``zone_id`` as the ``CurrentTimeZone``; the
+    effect fails with ``IllegalArgumentError`` if there is no such zone.
+    Use with ``.pipe``."""
+    return provide_service_effect(CurrentTimeZone, zone_named_effect(zone_id))
+
+
+def with_current_zone_local() -> _ProvideServiceEffect[CurrentTimeZone, Never, Never]:
+    """Provide the system's zone (read when the effect runs) as the
+    ``CurrentTimeZone``. Use with ``.pipe``."""
+    return provide_service_effect(CurrentTimeZone, sync(zone_local))
+
+
+def layer_current_zone(zone: tzinfo) -> Layer[CurrentTimeZone]:
+    return layer_succeed(CurrentTimeZone, zone)
+
+
+def layer_current_zone_offset(offset: Duration) -> Layer[CurrentTimeZone]:
+    return layer_succeed(CurrentTimeZone, _offset_zone(offset))
+
+
+def layer_current_zone_named(zone_id: str) -> Layer[CurrentTimeZone, IllegalArgumentError]:
+    return layer_effect(CurrentTimeZone, zone_named_effect(zone_id))
+
+
+def layer_current_zone_local() -> Layer[CurrentTimeZone]:
+    return layer_sync(CurrentTimeZone, zone_local)

pyfect/date_time/_epoch.py

@@ -0,0 +1,22 @@
+"""Epoch milliseconds, exactly: integer arithmetic on ``timedelta``, never
+``timestamp()`` or a division by 1000 (a float holds a far year's
+milliseconds only to about a microsecond)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from fractions import Fraction
+
+EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
+_MICROSECOND = timedelta(microseconds=1)
+
+
+def from_epoch_millis(millis: float) -> datetime:
+    """The UTC instant ``millis`` milliseconds after the epoch (to the
+    nearest microsecond). Raises ``OverflowError`` outside years 1 to 9999."""
+    return EPOCH + timedelta(milliseconds=millis)
+
+
+def to_epoch_millis(value: datetime) -> int:
+    """``value``'s milliseconds since the epoch, rounded half to even."""
+    return round(Fraction((value - EPOCH) // _MICROSECOND, 1000))