nl2time 0.1.0__py3-none-any.whl

nl2time/__init__.py

@@ -0,0 +1,24 @@
+"""nl2time: natural language <-> dates/times, language-neutral IR core.
+
+Python port of the JS reference (see docs/porting.md in the repository).
+v0: IR types + structural validator, TimeContext, and the deterministic
+engine `resolve()`. Parsers and describe() land in later phases.
+"""
+
+from . import errors
+from .context import TimeContext
+from .engine import MAX_CANDIDATES, resolve, resolve_one, value_to_json
+from .ir import IR_VERSION, validate_expr
+
+__all__ = [
+    "IR_VERSION",
+    "MAX_CANDIDATES",
+    "TimeContext",
+    "errors",
+    "resolve",
+    "resolve_one",
+    "validate_expr",
+    "value_to_json",
+]
+
+__version__ = "0.0.1"

nl2time/clock.py

@@ -0,0 +1,167 @@
+"""The clock seam: every `whenever` usage in nl2time flows through this module.
+
+Python counterpart of src/clock/index.ts (which wraps Temporal):
+Temporal.Instant -> whenever.Instant, Temporal.ZonedDateTime ->
+whenever.ZonedDateTime. Semantics mirrored:
+
+- calendar units (day and coarser) add/subtract preserving wall-clock time
+  across DST, with Temporal-'compatible' disambiguation;
+- hour/minute/second arithmetic is exact (absolute time);
+- month/year arithmetic clamps day-of-month (Jan 31 + 1 month = Feb 28/29).
+
+No other module may import `whenever` directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from whenever import Date, Instant, ZonedDateTime
+
+WEEKDAY_NUM: dict[str, int] = {
+    "mon": 1,
+    "tue": 2,
+    "wed": 3,
+    "thu": 4,
+    "fri": 5,
+    "sat": 6,
+    "sun": 7,
+}
+
+
+def weekday_number(w: str) -> int:
+    return WEEKDAY_NUM[w]
+
+
+@dataclass(frozen=True)
+class ZInterval:
+    """Half-open zoned interval [start, end) carrying its granularity."""
+
+    start: ZonedDateTime
+    end: ZonedDateTime
+    grain: str
+
+
+def system_now() -> Instant:
+    return Instant.now()
+
+
+def system_time_zone() -> str:
+    return ZonedDateTime.now_in_system_tz().tz
+
+
+def parse_instant(s: str) -> Instant:
+    return Instant.parse_iso(s)
+
+
+def format_instant(i: Instant) -> str:
+    """Temporal.Instant.toString()-compatible: `Z` suffix, trailing zeros trimmed."""
+    return i.format_iso()
+
+
+def to_zoned(instant: Instant, time_zone: str) -> ZonedDateTime:
+    return instant.to_tz(time_zone)
+
+
+def point_interval(z: ZonedDateTime) -> ZInterval:
+    """Point interval at z (grain 'instant')."""
+    return ZInterval(z, z, "instant")
+
+
+def start_of_day(z: ZonedDateTime) -> ZonedDateTime:
+    return z.start_of("day")
+
+
+def with_fields(
+    z: ZonedDateTime,
+    *,
+    year: int | None = None,
+    month: int | None = None,
+    day: int | None = None,
+) -> ZonedDateTime:
+    """Temporal `.with({year?, month?, day?})` with 'constrain' overflow.
+
+    whenever's replace() raises on out-of-range days; Temporal clamps
+    (e.g. `.with({month: 2, day: 31})` on Jan 15 -> Feb 28). Clamp manually.
+    """
+    y = year if year is not None else z.year
+    m = month if month is not None else z.month
+    d = day if day is not None else z.day
+    d = min(d, Date(y, m, 1).days_in_month())
+    return z.replace(year=y, month=m, day=d, disambiguate="compatible")
+
+
+def add_calendar(z: ZonedDateTime, **units: int) -> ZonedDateTime:
+    """Calendar-aware add with Temporal-'compatible' disambiguation."""
+    return z.add(**units, disambiguate="compatible")
+
+
+def floor_to(z: ZonedDateTime, unit: str, week_start: str) -> ZonedDateTime:
+    if unit == "second":
+        return z.round("second", mode="floor")
+    if unit == "minute":
+        return z.round("minute", mode="floor")
+    if unit == "hour":
+        return z.round("hour", mode="floor")
+    if unit == "day":
+        return z.start_of("day")
+    if unit == "week":
+        target = WEEKDAY_NUM[week_start]
+        # day_of_week is ISO (mon=1..sun=7); step back to the week-start day.
+        delta = (z.date().day_of_week().value - target + 7) % 7
+        return z.start_of("day").subtract(days=delta, disambiguate="compatible")
+    if unit == "month":
+        return with_fields(z, day=1).start_of("day")
+    if unit == "quarter":
+        q_start_month = (z.month - 1) // 3 * 3 + 1
+        return with_fields(z, month=q_start_month, day=1).start_of("day")
+    if unit == "year":
+        return with_fields(z, month=1, day=1).start_of("day")
+    raise ValueError(f"unknown unit {unit!r}")
+
+
+def add_units(z: ZonedDateTime, unit: str, n: int) -> ZonedDateTime:
+    """Calendar-aware unit addition (day+ preserves wall clock; h/m/s exact)."""
+    if unit == "second":
+        return z.add(seconds=n)
+    if unit == "minute":
+        return z.add(minutes=n)
+    if unit == "hour":
+        return z.add(hours=n)
+    if unit == "day":
+        return add_calendar(z, days=n)
+    if unit == "week":
+        return add_calendar(z, weeks=n)
+    if unit == "month":
+        return add_calendar(z, months=n)
+    if unit == "quarter":
+        return add_calendar(z, months=3 * n)
+    if unit == "year":
+        return add_calendar(z, years=n)
+    raise ValueError(f"unknown unit {unit!r}")
+
+
+def containing_unit(z: ZonedDateTime, unit: str, week_start: str) -> ZInterval:
+    """The containing unit interval of z: floor, extend one unit."""
+    start = floor_to(z, unit, week_start)
+    return ZInterval(start, add_units(start, unit, 1), unit)
+
+
+def calendar_days_between(from_z: ZonedDateTime, to_z: ZonedDateTime) -> int:
+    """Whole calendar days between two zoned datetimes (calendar difference)."""
+    return int(from_z.start_of("day").date().until(to_z.start_of("day").date(), total="days"))
+
+
+def compare(a: ZonedDateTime, b: ZonedDateTime) -> int:
+    """Instant-order comparison (Temporal.ZonedDateTime.compare)."""
+    x = a.timestamp_nanos()
+    y = b.timestamp_nanos()
+    return -1 if x < y else (1 if x > y else 0)
+
+
+def epoch_millis(z: ZonedDateTime) -> int:
+    return z.timestamp_millis()
+
+
+def add_milliseconds(z: ZonedDateTime, ms: int) -> ZonedDateTime:
+    return z.add(milliseconds=ms)

nl2time/context.py

@@ -0,0 +1,116 @@
+"""TimeContext: all resolution policy flows through here (port of src/context.ts).
+
+Options use the same camelCase names as the JS reference and the corpus wire
+format (`timeZone`, `weekStart`, ...); attributes are snake_case.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from whenever import Instant, ZonedDateTime
+
+from .clock import parse_instant, system_now, system_time_zone, to_zoned
+from .data import DayPeriodRule, first_day_for_region
+from .errors import ConfigError
+
+_MDY_REGIONS = frozenset(["US", "PH", "UM", "VI", "GU", "AS", "PR"])
+_YMD_REGIONS = frozenset(["CN", "JP", "KR", "TW", "HU", "MN", "LT"])
+
+_WEEKDAYS = frozenset(["mon", "tue", "wed", "thu", "fri", "sat", "sun"])
+
+
+def _parse_locale(locale: str) -> tuple[str, str | None]:
+    """Split a BCP-47 tag without Intl: language = first subtag; region = the
+    first 2-letter-alpha or 3-digit subtag after it (script subtags skipped)."""
+    parts = locale.replace("_", "-").split("-")
+    language = parts[0].lower()
+    if not language or not language.isascii() or not language.isalpha():
+        raise ConfigError(f"invalid locale: {locale}")
+    region: str | None = None
+    for sub in parts[1:]:
+        if (len(sub) == 2 and sub.isascii() and sub.isalpha()) or (
+            len(sub) == 3 and sub.isdigit()
+        ):
+            region = sub.upper()
+            break
+    return language, region
+
+
+def _normalize_day_periods(rules: list[dict[str, Any]]) -> list[DayPeriodRule]:
+    """Accept wire-format rules ({period, from, before}) or internal from_."""
+    out: list[DayPeriodRule] = []
+    for r in rules:
+        out.append(
+            {
+                "period": r["period"],
+                "from_": r["from_"] if "from_" in r else r["from"],
+                "before": r["before"],
+            }
+        )
+    return out
+
+
+class TimeContext:
+    def __init__(
+        self,
+        *,
+        now: Instant | str | None = None,
+        timeZone: str | None = None,
+        locale: str | None = None,
+        weekStart: str | None = None,
+        dateOrder: str | None = None,
+        bias: str | None = None,
+        nextWeekday: str | None = None,
+        partialPeriod: str | None = None,
+        dayPeriods: list[dict[str, Any]] | None = None,
+    ) -> None:
+        raw_now = now if now is not None else system_now()
+        try:
+            self.now: Instant = (
+                parse_instant(raw_now) if isinstance(raw_now, str) else raw_now
+            )
+        except Exception as e:  # noqa: BLE001 - mirror JS ConfigError wrapping
+            raise ConfigError(f"invalid now: {e}") from e
+        self.time_zone: str = timeZone if timeZone is not None else system_time_zone()
+        self.locale: str = locale if locale is not None else "en-US"
+
+        self.language, self.region = _parse_locale(self.locale)
+
+        if weekStart is not None and weekStart not in _WEEKDAYS:
+            raise ConfigError(f"invalid weekStart: {weekStart}")
+        self.week_start: str = (
+            weekStart if weekStart is not None else first_day_for_region(self.region)
+        )
+        if dateOrder is not None:
+            self.date_order = dateOrder
+        elif self.region in _MDY_REGIONS:
+            self.date_order = "MDY"
+        elif self.region in _YMD_REGIONS:
+            self.date_order = "YMD"
+        else:
+            self.date_order = "DMY"
+        self.bias: str = bias if bias is not None else "none"
+        self.next_weekday: str = nextWeekday if nextWeekday is not None else "nearest"
+        self.partial_period: str = (
+            partialPeriod if partialPeriod is not None else "include"
+        )
+        self.day_periods: list[DayPeriodRule] | None = (
+            _normalize_day_periods(dayPeriods) if dayPeriods is not None else None
+        )
+
+        # Validate the timezone eagerly so failures surface at construction.
+        try:
+            to_zoned(self.now, self.time_zone)
+        except Exception as e:  # noqa: BLE001
+            raise ConfigError(f"invalid timeZone: {self.time_zone}") from e
+
+    @classmethod
+    def make(cls, opts: dict[str, Any] | None = None, /, **kwargs: Any) -> "TimeContext":
+        merged = {**(opts or {}), **kwargs}
+        return cls(**merged)
+
+    @property
+    def zoned_now(self) -> ZonedDateTime:
+        """The reference instant projected into the context timezone."""
+        return to_zoned(self.now, self.time_zone)

nl2time/data.py

@@ -0,0 +1,73 @@
+"""Locale data tables: CLDR weekData slice and day-period boundary rules.
+
+Direct port of src/data/weekData.ts and src/data/dayPeriods.ts from the JS
+reference. Keep in sync; these are near-pure data.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+DEFAULT_FIRST_DAY = "mon"
+
+_SUN = frozenset([
+    "AG", "AS", "BD", "BR", "BS", "BT", "BW", "BZ", "CA", "CO", "DM", "DO", "ET",
+    "GT", "GU", "HK", "HN", "ID", "IL", "IN", "JM", "JP", "KE", "KH", "KR", "LA",
+    "MH", "MM", "MO", "MT", "MX", "MZ", "NI", "NP", "PA", "PE", "PH", "PK", "PR",
+    "PT", "PY", "SA", "SG", "SV", "TH", "TT", "TW", "UM", "US", "VE", "VI", "WS",
+    "YE", "ZA", "ZW",
+])
+
+_SAT = frozenset([
+    "AE", "AF", "BH", "DJ", "DZ", "EG", "IQ", "IR", "JO", "KW", "LY", "OM", "QA",
+    "SD", "SY",
+])
+
+_FRI = frozenset(["MV"])
+
+
+def first_day_for_region(region: str | None) -> str:
+    if not region:
+        return DEFAULT_FIRST_DAY
+    r = region.upper()
+    if r in _SUN:
+        return "sun"
+    if r in _SAT:
+        return "sat"
+    if r in _FRI:
+        return "fri"
+    return DEFAULT_FIRST_DAY
+
+
+class DayPeriodRule(TypedDict):
+    """Boundaries are [from, before) in local hours; may wrap midnight."""
+
+    period: str
+    from_: int  # start hour (inclusive); key name avoids the Python keyword
+    before: int  # end hour (exclusive); may be < from_ (wraps midnight)
+
+
+# CLDR flexible day-period rules, English set (v1 ships en only; other
+# languages fall back to these boundaries, mirroring the JS reference).
+EN_RULES: list[DayPeriodRule] = [
+    {"period": "morning", "from_": 6, "before": 12},
+    {"period": "afternoon", "from_": 12, "before": 18},
+    {"period": "evening", "from_": 18, "before": 21},
+    {"period": "night", "from_": 21, "before": 6},
+]
+
+
+def day_period_rules(language: str) -> list[DayPeriodRule]:
+    # Only 'en' data is bundled so far; other languages fall back (see JS ref).
+    del language
+    return EN_RULES
+
+
+def period_for_hour(language: str, hour: int) -> str:
+    for rule in day_period_rules(language):
+        if rule["from_"] < rule["before"]:
+            if rule["from_"] <= hour < rule["before"]:
+                return rule["period"]
+        elif hour >= rule["from_"] or hour < rule["before"]:
+            return rule["period"]
+    return "night"