dtrexp-py

Python implementation of DTRExp (read: "DTR Expression") — a compact string expression for date-time ranges and recurrence, evaluated by coverage rather than enumeration.

T0900:1800 E1:5          Mon–Fri, 09:00–18:00
E7#-1 M4                 last Sunday of April, every year
20200106/10D             every 10 days from 2020-01-06 (cron can't say this)
M!7                      every month except July

Scope: parsing, validation and coverage evaluation — the spec's core interface. Rendering, description and RRULE export are out of scope; the reference implementation has them.

Install

pip install dtrexp

Python 3.11+, stdlib only (zoneinfo for IANA zones).

Usage

from datetime import datetime, timezone
import dtrexp

dtr = dtrexp.parse("T0900:1800 E1:5")   # business hours, Mon–Fri

dtr.covers(datetime(2026, 7, 7, 10, 0, tzinfo=timezone.utc))
# —> True (UTC — the default)
dtr.covers(datetime(2026, 7, 7, 7, 30, tzinfo=timezone.utc), tz="Europe/Berlin")
# —> True (09:30 Berlin local time)

berlin = dtr.with_zone("Europe/Berlin")   # a copy; dtr is left as it is
berlin.covers(datetime(2026, 7, 7, 7, 30, tzinfo=timezone.utc))
# —> True (the bound zone)
berlin.covers(datetime(2026, 7, 7, 7, 30, tzinfo=timezone.utc), tz="UTC")
# —> False (a tz passed to the call wins)

Note that you parse once (at write/config time) and evaluate many; Expression objects are meant to be shared, not changed (with_zone returns a copy rather than changing the one you have), and covers is a single calendar-field extraction followed by integer comparisons (no occurrence iteration). The zone is an evaluation parameter, never part of the expression. covers also accepts an ISO 8601 string for the instant.

• covers(instant, tz=None): tz is an IANA zone name; None means the bound zone, else "UTC". A tz passed to the call, "UTC" included, wins over the bound zone. An unknown zone raises ZoneInfoNotFoundError.
• with_zone(tz): a copy whose evaluation defaults to tz, readable as zone (None when unbound). The copy's text and warnings are the original's. The zone is checked at once: an unknown zone raises ZoneInfoNotFoundError, an empty name ValueError, and a non-str (None included) TypeError; binding never falls back to UTC or the host's zone.

Which to use: bind the zone with with_zone() when it belongs to what the expression describes (a store's hours, a venue's schedule), and pass tz per call when it belongs to whoever is asking (a rule shown to each user in their own zone). A bound copy shares its text with the original, so a cache of parsed expressions keys on text and zone together.

Errors and Warnings

Both carry a position; the 0-based character offset into the source:

dtrexp.parse("Y*/3")
# raises DTRExpSyntaxError: "anchorless stride — an explicit start is required (at 1)"
# error.position —> 1

res = dtrexp.validate("D30 M2")   # never raises
res.valid                         # True — it parses
res.warnings                      # (DTRExpWarning(message="unsatisfiable …", position=0),)

• parse(text) raises DTRExpSyntaxError (a ValueError) on invalid input; position points at the offending character and is appended to the rendered message.
• validate(text) never raises; typo-shaped input comes back as data. Returns a frozen ValidationResult with valid bool, errors (parsing stops at the first syntax error, so at most one) and warnings.
• Warnings are the spec's §9.1 unsatisfiability lint: expressions that parse but can never match. They are DTRExpWarning objects (message str, position int | None); str(warning) is the message. Expression.warnings and validate(text).warnings carry the same content.

Conformance & Quality

• The test suite is driven by the shared vectors.json from the spec repo (draft 2.8): every coverage, rejection, warning and quiet vector, including the calendar traps (Feb 29 across 2000/2024/2100, W53 existence, DST gap/overlap in Europe/Berlin). See VECTORS.md for how the suite works.
• 100% line + branch coverage, enforced (uv run poe cover); mutation-tested with mutmut (uv run poe mutation).
• Zero dependencies.

Related Projects

• dtrexp (spec): the DTRExp specification (grammar, semantics, conformance vectors) this package implements.
• dtrexp-js: the reference implementation; adds intersect, next, describe, toRRule and canonicalization.
• dtrexp-go · dtrexp-swift · dtrexp-rs · dtrexp-java: the other ports; same core interface.
• dtrexp-wasm: the Rust core compiled to WebAssembly for JS hosts.

License

© 2026, Onur Yıldırım. MIT License.