nl2time 0.1.0__tar.gz

nl2time-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+*.egg-info/

nl2time-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nl2time contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nl2time-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: nl2time
+Version: 0.1.0
+Summary: Deterministic temporal-expression IR engine — Python port of the nl2time natural language ⇄ date/time library
+Project-URL: Homepage, https://github.com/AndyFooBlah/nl2time
+Project-URL: Repository, https://github.com/AndyFooBlah/nl2time
+Project-URL: Changelog, https://github.com/AndyFooBlah/nl2time/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/AndyFooBlah/nl2time/issues
+Author: Andrew Brook
+License-Expression: MIT
+License-File: LICENSE
+Keywords: datetime,llm,natural-language,parser,temporal,timezone
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: whenever>=0.8
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nl2time (Python)
+
+Deterministic resolution of temporal-expression IR — the Python port of
+[nl2time](https://github.com/AndyFooBlah/nl2time), a bidirectional natural
+language ⇄ date/time library built around a JSON intermediate representation
+(`TimeExpr`).
+
+**Scope of this release: the language-neutral core.** IR validation,
+`TimeContext` (reference instant, IANA timezone, locale-derived week/date
+policy, ambiguity knobs), and the full deterministic engine `resolve()` —
+every operator including calendar snapping, DST-correct offsets, holidays
+(computed Easter), business-day spans, and ordered ambiguity candidates.
+Natural-language *parsing* and *rendering* are not yet ported; today the
+expected producers of IR are the JS parser, an LLM emitting schema-constrained
+IR, or your own code. Time model: [whenever](https://pypi.org/project/whenever/)
+(Temporal-inspired).
+
+```python
+from nl2time import TimeContext, resolve
+
+ctx = TimeContext.make({
+    "now": "2026-07-20T17:00:00Z",
+    "timeZone": "America/Los_Angeles",
+    "locale": "en-US",
+})
+
+# "last week" as IR (e.g. produced by the JS parser or an LLM):
+expr = {
+    "op": "snap",
+    "base": {"op": "offset", "base": {"op": "now"}, "amount": -1, "unit": "week"},
+    "unit": "week",
+}
+resolve(expr, ctx)["candidates"][0]
+# {"kind": "interval", "start": Instant("2026-07-12 07:00:00Z"),
+#  "end": Instant("2026-07-19 07:00:00Z"), "grain": "week"}
+# (values are `whenever.Instant`; candidates are ordered, ambiguity is data)
+```
+
+## Parity guarantee
+
+This engine reproduces the JS reference **bit-exactly** — instants, grains,
+and candidate order — across all 2,760 machine-generated engine-parity
+fixtures derived from the project's six-language conformance corpora, enforced
+in CI on every commit. Spec: [ir-spec.md](https://github.com/AndyFooBlah/nl2time/blob/main/docs/ir-spec.md);
+strategy: [porting.md](https://github.com/AndyFooBlah/nl2time/blob/main/docs/porting.md);
+test-data provenance: [corpus/ATTRIBUTIONS.md](https://github.com/AndyFooBlah/nl2time/blob/main/corpus/ATTRIBUTIONS.md).
+
+MIT.

nl2time-0.1.0/README.md

@@ -0,0 +1,48 @@
+# nl2time (Python)
+
+Deterministic resolution of temporal-expression IR — the Python port of
+[nl2time](https://github.com/AndyFooBlah/nl2time), a bidirectional natural
+language ⇄ date/time library built around a JSON intermediate representation
+(`TimeExpr`).
+
+**Scope of this release: the language-neutral core.** IR validation,
+`TimeContext` (reference instant, IANA timezone, locale-derived week/date
+policy, ambiguity knobs), and the full deterministic engine `resolve()` —
+every operator including calendar snapping, DST-correct offsets, holidays
+(computed Easter), business-day spans, and ordered ambiguity candidates.
+Natural-language *parsing* and *rendering* are not yet ported; today the
+expected producers of IR are the JS parser, an LLM emitting schema-constrained
+IR, or your own code. Time model: [whenever](https://pypi.org/project/whenever/)
+(Temporal-inspired).
+
+```python
+from nl2time import TimeContext, resolve
+
+ctx = TimeContext.make({
+    "now": "2026-07-20T17:00:00Z",
+    "timeZone": "America/Los_Angeles",
+    "locale": "en-US",
+})
+
+# "last week" as IR (e.g. produced by the JS parser or an LLM):
+expr = {
+    "op": "snap",
+    "base": {"op": "offset", "base": {"op": "now"}, "amount": -1, "unit": "week"},
+    "unit": "week",
+}
+resolve(expr, ctx)["candidates"][0]
+# {"kind": "interval", "start": Instant("2026-07-12 07:00:00Z"),
+#  "end": Instant("2026-07-19 07:00:00Z"), "grain": "week"}
+# (values are `whenever.Instant`; candidates are ordered, ambiguity is data)
+```
+
+## Parity guarantee
+
+This engine reproduces the JS reference **bit-exactly** — instants, grains,
+and candidate order — across all 2,760 machine-generated engine-parity
+fixtures derived from the project's six-language conformance corpora, enforced
+in CI on every commit. Spec: [ir-spec.md](https://github.com/AndyFooBlah/nl2time/blob/main/docs/ir-spec.md);
+strategy: [porting.md](https://github.com/AndyFooBlah/nl2time/blob/main/docs/porting.md);
+test-data provenance: [corpus/ATTRIBUTIONS.md](https://github.com/AndyFooBlah/nl2time/blob/main/corpus/ATTRIBUTIONS.md).
+
+MIT.

nl2time-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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"