python-dateutil

python-dateutil is the de facto standard library for anything Python’s built-in datetime module doesn’t handle out of the box. It adds fuzzy natural-language date parsing, calendar-correct relative date arithmetic, RFC 2445 (iCalendar) recurrence rules, and comprehensive timezone resolution against system and Olson tz data. First released in 2003 and now downloaded hundreds of millions of times a week, it underpins countless higher-level libraries (including pandas) that need robust date and time handling.

The package is organized into small, independently importable submodules — parser, relativedelta, rrule, tz, easter, and utils — so consumers pay only for what they use. A strict test suite (including Hypothesis-based property tests and warnings-as-errors CI) and years of careful deprecation handling have made it one of the most trusted low-level building blocks in the Python ecosystem.

What You Get

• parser.parse() for fuzzy, locale-tolerant parsing of almost any date/time string format into a native datetime
• relativedelta for calendar-correct arithmetic (e.g. adding a month without manual day-overflow handling)
• rrule implementing the full iCalendar (RFC 2445) recurrence-rule specification, including recurrence sets and string parsing
• tz module with tzfile, tzoffset, tzlocal, gettz(), and Windows registry-based timezone support backed by Olson tz data
• easter() for computing Easter Sunday under Western, Orthodox, or Julian algorithms
• isoparser for strict, fast ISO-8601 parsing when input format is known and controlled

Common Use Cases

• Parsing user-submitted or scraped date strings of unknown format into usable datetime objects
• Computing recurring schedules (billing cycles, reminders, recurring events) via rrule
• Calendar-aware date math such as “three months from today” or “the last weekday of this month”
• Resolving and converting between timezones reliably across Linux, macOS, and Windows
• Backing higher-level data and scheduling libraries that need dependable date/time primitives

Under The Hood

Architecture: dateutil is organized into clearly separated submodules under src/dateutil/ — parser/ (_parser.py holds the core tokenizer and parse() entry point, isoparser.py handles strict ISO-8601 parsing), tz/ (tz.py implements tzfile, tzoffset, tzlocal, tzwin, and gettz() resolution against system/Olson zoneinfo data, backed by _common.py’s shared ambiguity helpers), rrule.py (a single ~1700-line module implementing the iCalendar RFC 2445 recurrence engine), relativedelta.py (the relativedelta/weekday classes for calendar-aware arithmetic), and easter.py/utils.py for narrow utilities. Each submodule is lazily importable via a custom __getattr__ in __init__.py, so consumers pay import cost only for the piece they use.

Tech Stack: A pure-Python package targeting Python 2.7 and 3.3+, with a single runtime dependency on six for Py2/3 compatibility shims — evidence of its long legacy tail. Build tooling is classic setuptools plus setuptools_scm for version derivation from git tags, packaged from a src/ layout. CI spans GitHub Actions and AppVeyor for Windows coverage, with codecov tracking and pre-commit hooks for lint.

Code Quality: Testing is thorough — tests/ mirrors the module layout with dedicated suites for the parser, rrule, tz, relativedelta, easter, and isoparser modules, plus a property/ subdirectory using Hypothesis for property-based testing of parsing and recurrence edge cases. pytest is configured with filterwarnings = error, so any uncaught DeprecationWarning fails the suite — a strict signal of deliberate API stewardship. Deprecated private functions (_timelex, _tzparser, _resultbase) are explicitly wrapped to emit warnings rather than silently removed.

API Design: The public surface is small and memorable — parse(), relativedelta(), rrule(), and tz.gettz() — each usable independently with minimal boilerplate. The tradeoff is a slightly dated surface: parser.parse() accepts loosely-typed kwargs (dayfirst, yearfirst, fuzzy) rather than a structured config object, and the six dependency signals years of Python 2 compatibility baggage. Documentation is comprehensive — a full Sphinx site on Read the Docs plus docs/examples.rst and a dedicated exercises directory — keeping the learning curve shallow despite the API’s age.