luplo.core.timeparse

Lightweight time-range parser shared by CLI and MCP idea search.

Accepts: - "" (empty) → None - ISO datetime: 2026-04-01 or 2026-04-01T12:00:00+00:00 - Relative: Nd / Nw (last N days / weeks) - Anchors: this_week / this_month / this_quarter —

since-only. Anchors return the start of the named period, which is the desired semantic for --since (“everything from then to now”) but garbage for --until (“everything before this period started”). When mode='until' we reject anchors with a clear error.

Naive datetimes get UTC. Garbage input raises ValueError carrying the list of accepted dialects so callers can surface a friendly message.

Functions

parse_since(→ datetime.datetime | None)

Parse the time-range dialect; return None for empty input.

Module Contents

luplo.core.timeparse.parse_since(value: str | None, *, mode: Literal['since', 'until'] = 'since') → datetime.datetime | None

Parse the time-range dialect; return None for empty input.

mode='since' (default) accepts every dialect including anchors, which return the start of the named period. mode='until' rejects anchors because “before the start of this month” almost always filters out the entire current period — likely not what the caller meant.

Raises:

ValueError – when the input is non-empty but not a recognised form, or when mode='until' and an anchor is supplied. The message names the supported dialects so callers can forward it without further wrapping.