chronoparse

Natural language date/time parser for Python. Zero dependencies.

Install

python -m pip install -e .

From source:

git clone https://github.com/nripankadas07/chronoparse.git
cd chronoparse
pip install -e .[dev]

Usage

from datetime import datetime
from chronoparse import parse

# Keywords
parse("now")
parse("today")
parse("tomorrow")
parse("yesterday")

# Relative offsets
parse("in 3 days")
parse("2 hours ago")
parse("in five weeks")
parse("in a minute")

# Weekdays
parse("next friday")
parse("last monday")

# Calendar units
parse("next week")
parse("last month")
parse("in 3 months")
parse("2 years ago")

# Combined with time of day
parse("today at 5pm")
parse("tomorrow at 09:30")

# ISO-like strings
parse("2024-03-15")
parse("2024-03-15 14:30:45")

# Deterministic parsing with an explicit reference
parse("tomorrow", now=datetime(2026, 4, 7, 12, 0))
# -> datetime.datetime(2026, 4, 8, 0, 0)

Invalid input raises ChronoParseError (a subclass of ValueError):

from chronoparse import ChronoParseError, parse

try:
    parse("definitely not a date")
except ChronoParseError as exc:
    print(f"couldn't parse: {exc}")

API Reference

parse(text: str, now: datetime | None = None) -> datetime

Parse a natural language date/time expression and return a datetime.

• text — the expression to parse. Case-insensitive. Leading/trailing whitespace is ignored.
• now — reference datetime used when resolving relative expressions. Defaults to datetime.now(). Passing an explicit reference makes parsing deterministic and testable.

Returns a datetime. Raises ChronoParseError if the expression cannot be interpreted.

Supported forms:

Form	Example
Keywords	now, today, tomorrow, yesterday
Relative future	in 3 days, in a minute, in ten seconds
Relative past	2 hours ago, five weeks ago
Weekday	friday, next friday, last mon
Calendar unit	next week, last month, next year
With time	today at 5pm, tomorrow at 14:30
ISO date	2024-03-15, 2024-03-15 14:30:45

ChronoParseError

Raised when the input string cannot be parsed. Subclass of ValueError.

Running Tests

pip install -e .[dev]
pytest

With coverage:

pytest --cov=src/chronoparse --cov-report=term-missing

License

MIT — see LICENSE.