Python Tutorial: Datetime Module - How to work with Dates, Times, Timedeltas, and Timezones

Python’s datetime module is the backbone for working with dates, times, time deltas, and time zones—but the biggest practical hurdle is knowing when to use “naive” versus “aware” datetimes. Naive datetimes lack enough information to resolve time zones or daylight saving time, making them simpler to manipulate but risky for anything that depends on real-world offsets. Aware datetimes carry time zone (and DST) context, preventing silent mistakes when converting between regions.

The tutorial starts with the basics: importing the module and creating a date using year, month, and day. It highlights a common pitfall—passing leading zeros for integers like 07 triggers a syntax error, so single-digit months and days must be provided as plain integers. From there, it demonstrates convenience constructors such as date.today() for the current local date, plus attribute accessors like year, month, and day. It also compares weekday() and isoweekday(), noting the different numbering schemes: weekday uses Monday=0 through Sunday=6, while ISO weekday uses Monday=1 through Sunday=7.

Time deltas then take center stage as the difference between two dates or times. A timedelta representing seven days can be added to a date to compute “one week from now,” or subtracted to compute “one week ago.” The tutorial also draws a crucial type distinction: adding or subtracting a timedelta from a date yields another date, while subtracting one date from another yields a timedelta. That distinction is used to calculate time until a birthday by subtracting the current date from a fixed birthday date, then extracting results via timedelta.days and timedelta.total_seconds() (to get a seconds-based measure rather than just whole days).

For time-of-day handling, datetime.time focuses on hours, minutes, seconds, and microseconds, while datetime.datetime combines both date and time. The tutorial shows how to access components (like dt.date() and dt.time()) and how to shift datetimes by adding timedelta objects. It further compares constructors like datetime.today(), datetime.now(), and datetime.utcnow(), clarifying that “UTC” in the method name doesn’t automatically make the object time zone aware—TZ info still matters.

Time zones are handled with the third-party pytz package, installed via pip, because Python’s documentation recommends it for using the time zone database. The workflow emphasizes best practice: build time zone aware datetimes in UTC (using tzinfo=pytz.UTC), then convert to other zones with astimezone(pytz.timezone(...)). The tutorial demonstrates converting from UTC to US Mountain time using the correct pytz zone string (e.g., us_Mountain) and explains how to discover valid zone names by iterating over pytz.all_timezones.

Finally, it addresses the conversion problem that naive datetimes can’t be directly converted with astimezone—pytz raises an error when tzinfo is missing. The fix is to “attach” time zone context using localize(): create a naive local datetime, then localize it with the appropriate pytz time zone (like us_Mountain) to make it aware before converting to US Eastern time. The tutorial closes with practical formatting tools: ISO output via isoformat(), custom string formatting using strftime format codes, and parsing strings back into datetimes with strptime (via datetime.strptime).