python-dateutil

Warnings

• gotcha parser.parse() silently guesses ambiguous dates like '04/05/2024' using dayfirst=False (MM/DD) by default. Non-US date strings will be parsed incorrectly unless dayfirst=True is set explicitly.
  Fix: Always pass dayfirst=True for DD/MM/YYYY input, or use isoparse() for unambiguous ISO 8601 strings.
• gotcha parser.parse() returns a timezone-naive datetime when no timezone is present in the input string, which can silently cause incorrect comparisons with aware datetimes.
  Fix: Check dt.tzinfo after parsing, or pass a default timezone via the tzinfos parameter, or use dateutil.tz.tzutc() to attach UTC explicitly.
• breaking Since 2.8.1 parse() raises dateutil.parser.ParserError (a ValueError subclass) instead of plain ValueError. Code catching ValueError still works, but catching only the base Exception may need updating.
  Fix: Catch ParserError for precision: from dateutil.parser import ParserError; except ParserError: ...
• gotcha fuzzy=True parsing can silently extract numbers from arbitrary strings as date components (e.g. parse('lbl2vec at 7pm', fuzzy=True) extracts '2' as a day). This makes fuzzy parsing unsafe for untrusted or unexpected input.
  Fix: Use fuzzy=False (default) or fuzzy_with_tokens=True and inspect the ignored tokens tuple to validate what was consumed.
• gotcha rrule dtstart is NOT included as the first occurrence unless it independently satisfies the recurrence rule — this diverges from RFC 2445 behavior.
  Fix: To include dtstart unconditionally, use rruleset and add dtstart with ruleset.rdate(dtstart).
• gotcha gettz() returns None silently when a timezone name cannot be resolved (e.g. on Windows without the tzdata package installed). Passing None as tzinfo produces a naive datetime without error.
  Fix: Always assert the result: tz = gettz('America/New_York'); assert tz is not None. Install tzdata package on Windows/Docker environments.
• deprecated The project still ships the six compatibility shim as a hard dependency. Fedora has flagged the project as effectively unmaintained upstream with possible unaddressed security issues. New greenfield projects should consider zoneinfo (Python 3.9+ stdlib) + dateutil only for relativedelta/rrule features.
  Fix: For pure timezone handling on Python 3.9+, prefer zoneinfo.ZoneInfo from the stdlib. For relativedelta on Python 3, evaluate whether stdlib timedelta suffices for your use case.

Install

• pip install python-dateutil pip

Imports

• parser.parse

  from dateutil import parser; parser.parse('2024-01-15')

  Always import the submodule explicitly for clarity. The top-level lazy-import shortcut (PEP 562, added in 2.9.0) only works on Python 3.7+.
• parser.isoparse

  from dateutil.parser import isoparse

  Use isoparse() for strict ISO 8601 strings instead of parse(); parse() is more permissive and may silently misinterpret ambiguous ISO strings.
• relativedelta

  from dateutil.relativedelta import relativedelta

  Wildcard import pulls in weekday constants (MO, TU, ...) that can shadow calendar/rrule symbols; prefer explicit import.
• rrule / DAILY / WEEKLY / MONTHLY / YEARLY

  from dateutil.rrule import rrule, DAILY, WEEKLY, MONTHLY, YEARLY, rruleset

  Frequency constants (DAILY, WEEKLY, etc.) must be imported from dateutil.rrule; they are not available at the top-level dateutil namespace.
• gettz

  from dateutil.tz import gettz, tzutc, tzlocal

  gettz() returns None (not an exception) when the timezone name is unrecognized — always check for None before using the result.
• ParserError

  from dateutil.parser import ParserError

  Since 2.8.1 parse() raises ParserError (a ValueError subclass) on failure. Catching only ValueError still works but catching ParserError is more precise.

Quickstart

Demonstrates flexible string parsing, isoparse, relativedelta month arithmetic, timezone handling with gettz, and explicit dayfirst flag for ambiguous dates.

from datetime import datetime
from dateutil import parser
from dateutil.relativedelta import relativedelta
from dateutil.tz import gettz, tzutc

# 1. Flexible string parsing
dt = parser.parse("March 15, 2024 3:30 PM")
print("Parsed:", dt)

# 2. ISO 8601 with timezone
dt_aware = parser.isoparse("2024-03-15T15:30:00+05:30")
print("ISO aware:", dt_aware)

# 3. Relative delta arithmetic (month-aware)
now = datetime(2024, 1, 31, tzinfo=tzutc())
one_month_later = now + relativedelta(months=1)
print("One month later:", one_month_later)  # 2024-02-29 (leap year)

# 4. Timezone-aware datetime
nyc = gettz("America/New_York")
if nyc is None:
    raise RuntimeError("Could not resolve timezone; install tzdata package")
dt_nyc = datetime(2024, 3, 15, 12, 0, tzinfo=nyc)
print("NYC time:", dt_nyc)

# 5. Ambiguous date: always set dayfirst/yearfirst explicitly
ambiguous = parser.parse("04/05/2024", dayfirst=False)  # May 4
print("MM/DD:", ambiguous.date())