dateparser

dateparser is a Python library for parsing dates and times out of human-readable text — absolute dates, relative expressions like “two weeks ago” or “tomorrow”, raw timestamps, and dates embedded inside longer strings — across more than 200 language locales with automatic language detection. A single dateparser.parse() call normalizes messy, inconsistently formatted date strings into standard Python datetime objects without the caller needing to know the source format or language ahead of time.

Built and maintained by Scrapinghub (Zyte) originally for web-scraping pipelines, it has grown into a general-purpose date-parsing dependency used well beyond scraping — anywhere multilingual or loosely formatted date text needs to become a reliable timestamp, including timezone-aware output, configurable date-order resolution, and a search_dates() function for pulling dates out of arbitrary text and even resolving fuzzy time spans like “past month” into concrete start/end datetimes.

What You Get

• Locale-aware parsing across 200+ languages with automatic language detection
• Support for absolute dates, relative expressions (“3 days ago”), and Unix timestamps in one API
• search_dates() for extracting every date substring from a longer block of text
• Time span detection that resolves phrases like “past month” into explicit start/end datetimes
• A settings dict for controlling date order, timezone handling, and incomplete-date resolution
• Optional non-Gregorian calendar support (Hijri, Jalali) via the calendars extra

Common Use Cases

• Normalizing dates scraped from HTML pages with inconsistent or localized formatting
• Parsing user-submitted date strings in multilingual web forms
• Extracting publication dates from news articles and RSS/content feeds
• Converting relative time expressions in chat or log messages into absolute timestamps

Under The Hood

Architecture Every call funnels through dateparser.parse() (dateparser/__init__.py) into a module-level DateDataParser singleton (dateparser/date.py), which orchestrates locale detection via LocaleDataLoader/custom_language_detection, dispatches to per-format parsers (_parse_absolute and _parse_nospaces in parser.py, freshness_date_parser.py for relative expressions) in the order set by settings.PARSERS, and finally normalizes timezone and day-of-month ambiguity through DateParser in date_parser.py. It’s a layered pipeline — sanitize, resolve locale, dispatch to the matching parser, normalize timezone — with dateparser/search built as a separate module on top of the same core for the search_dates() entry point, and locale/translation data loaded lazily and cached from dateparser_data/date_translation_data rather than compiled into the dispatch logic itself.

Tech Stack A pure Python 3.10+ package (setuptools build backend) with a deliberately small runtime dependency footprint — python-dateutil for relative-delta arithmetic, pytz for the timezone database, regex for Unicode-aware pattern matching beyond stdlib re, and tzlocal for local timezone detection — plus optional extras (convertdate/hijridate for non-Gregorian calendars, langdetect for language auto-detection). It ships a small companion CLI (dateparser_cli, entry point dateparser-download) for managing cached detection models, and is tested across a tox.ini matrix spanning Python 3.10 through 3.14 with separate GitHub Actions workflows for CI, PyPI publishing, performance benchmarking (Codspeed), and continuous fuzzing (OSS-Fuzz/CIFuzz).

Code Quality An extensive test suite covers the parser core, freshness/relative parsing, timezones, search, thread safety, and pickling using pytest with parameterized.expand for locale-by-locale cases, wired into CI with pytest-cov and Codecov reporting. Fuzz testing via OSS-Fuzz/atheris adds an unusually deep layer of quality assurance for a library this size. Linting and formatting are enforced through ruff (ruff --fix plus ruff-format) via pre-commit hooks integrated into the tox envlist. The main gap is static typing — no mypy configuration and largely untyped core modules (date.py, parser.py).

API Design dateparser optimizes for near-zero-boilerplate use: dateparser.parse("some date string") returns a datetime with no setup required, backed by a module-level default parser instance to avoid repeated initialization cost. Advanced control — date order, locale restriction, timezone behavior, strict parsing — is exposed through a single settings dict rather than a sprawling list of keyword arguments, keeping the common-case signature small while still reaching deep configurability; search_dates() mirrors the same ergonomics for text-extraction use cases. Documentation is strong, with dozens of runnable README examples and a full Read the Docs site, though the settings dict is stringly-typed rather than an enum/dataclass, and misconfiguration surfaces as a runtime SettingValidationError instead of being caught statically.