awesome-python/website/data/category_intros/date-and-time.md

Handle time zones with the built-in zoneinfo. Parsing date strings and adding months is where a Python date library earns its install: python-dateutil.

How to choose:

• Time zones by IANA name, like Europe/Paris: zoneinfo
• Parsing date strings, adding months, and recurring dates: python-dateutil
• Dates as people write them, like "3 days ago", in many languages: dateparser
• An easier datetime API whose objects are still datetimes: pendulum
• Exact and local times as separate types, with DST-safe math: whenever

zoneinfo brings the IANA time zone database to Python, and the datetime docs say its usage is recommended. Attach a ZoneInfo to a datetime through the constructor, replace(), or astimezone(). Some systems, Windows among them, have no IANA database, so if your code runs across platforms, declare a dependency on tzdata.

python-dateutil adds extensions to the standard datetime module; install it as python-dateutil and import it as dateutil. Its parser reads most known formats and returns a datetime even for an ambiguous date. For input like 01/05/09, set dayfirst or yearfirst to match your data. For calendar math, relativedelta takes plural arguments that add and singular ones that replace: months=+1 moves a month ahead, and day=1 jumps to the first. rrule builds recurring dates from iCalendar rules.

dateparser reads relative dates like "two weeks ago" and absolute ones in more than 200 language locales. Its docs say it stands out for scraped pages, logs, and other data from mixed sources, and for letting users type dates in their own words. Call dateparser.parse(), and pass languages when you know them, so it skips language detection. When you parse many dates from one source, use DateDataParser, which remembers the languages it has found.

pendulum's classes are drop-in replacements for the native ones, since they inherit from datetime. Every instance is time zone aware and in UTC by default. Its docs call aware datetimes the preferred and recommended way to use it. For tests, install pendulum[test] and travel in time.

whenever puts exact time and local time in separate types: an instant when only the moment matters, a zoned datetime when the local time matters too. Mixing up naive and aware becomes a type error, and DST is handled in all arithmetic. A standard datetime does no time zone adjustment when you add a timedelta to it. In production, turn whenever's DST warnings into errors with Python's standard warnings filter.

Decide whether you extend datetime or replace it. zoneinfo, python-dateutil, and dateparser all use standard datetime objects, so they work together. pendulum's objects are datetimes too, but code that checks the exact type, like sqlite3 and some database drivers, needs an adapter registered. whenever doesn't subclass datetime at all, so convert to and from standard datetimes where other code needs one.