Python datetime — utcnow() DST Bug That Shifts Dates

Date and time handling is one of those areas where every language has footguns, and Python is no exception. The datetime module's API is comprehensive but has some confusing names (datetime.datetime vs datetime.date), the timezone story requires an extra library until Python 3.9, and the difference between naive and aware datetimes trips up everyone at least once.

This guide covers the practical patterns for working with dates and times in Python, including the timezone-aware patterns you should use in production.

What datetime Module Actually Does — and Why utcnow() Is Dangerous

Python's datetime module provides classes for manipulating dates and times, but its core mechanic is deceptively simple: it represents moments as either naive (no timezone) or aware (with timezone). The module's datetime class stores year, month, day, hour, minute, second, microsecond, and an optional tzinfo object. The critical distinction is that naive datetimes lack any timezone context — they are just wall-clock times, not absolute points on the timeline.

In practice, the module's key property is that arithmetic on naive datetimes treats them as if they are in a single, unspecified timezone. This means subtracting two naive datetimes from different timezones yields a wrong timedelta. The module's utcnow() method returns a naive datetime representing the current UTC time — it strips the timezone info. This is the root of the DST bug: when you store or compare utcnow() results, you lose the UTC context, and any subsequent conversion to a local timezone (e.g., via astimezone) will apply the local DST rules incorrectly, potentially shifting the date by an hour.

Use the datetime module when you need to record timestamps, schedule events, or compute durations. But never use utcnow() in production systems that cross timezone boundaries or handle daylight saving time. Instead, use datetime.now(timezone.utc) to get an aware UTC datetime. This matters because a one-hour shift can cause missed deadlines, incorrect billing cycles, or data corruption in distributed systems.

Creating and Formatting Dates

Creating datetime objects is straightforward but the gotcha is in the naming: datetime.datetime vs datetime.date vs datetime.time. When you call datetime.now() you get a naive local datetime — no timezone, ambiguous. Always prefer datetime.now(timezone.utc) for production code unless you have a specific reason to be naive. strftime is your friend for formatting. The directive letters are confusing at first, but the table is in the docs. The most common mistake is using %m for minutes (should be %M) and %H for hours (24-hour) when you meant %I for 12-hour.

from datetime import date, time, datetime, timedelta

# Current date and time
today     = date.today()
now       = datetime.now()  # local time, naive (no timezone)

print(today)          # 2026-03-17
print(now)            # 2026-03-17 11:30:45.123456

# Create specific dates
birthday  = date(1990, 6, 15)
meeting   = datetime(2026, 3, 20, 14, 30, 0)

# Format with strftime
print(meeting.strftime('%A, %B %d %Y at %H:%M'))
# Thursday, March 20 2026 at 14:30

print(meeting.strftime('%d/%m/%Y'))  # 20/03/2026
print(meeting.isoformat())           # 2026-03-20T14:30:00

# Parse a string with strptime
parsed = datetime.strptime('20/03/2026 14:30', '%d/%m/%Y %H:%M')
print(parsed)  # 2026-03-20 14:30:00

timedelta — Date Arithmetic

timedelta is a duration between two datetimes. You can add or subtract days, seconds, microseconds, milliseconds, minutes, hours, weeks. That's it — no months or years. That's intentional because months and years have variable lengths. If you need to add a month, you must use dateutil.relativedelta or manually adjust. Performance-wise, timedelta arithmetic is O(1) — it's just integer arithmetic under the hood. But be careful when subtracting datetimes that have different timezones: the result is a timedelta, but it's computed in UTC, so the magnitude may surprise you.

from datetime import datetime, timedelta

now = datetime(2026, 3, 17, 12, 0, 0)

# Add and subtract durations
tomorrow   = now + timedelta(days=1)
last_week  = now - timedelta(weeks=1)
in_90_days = now + timedelta(days=90)

print(tomorrow)    # 2026-03-18 12:00:00
print(last_week)   # 2026-03-10 12:00:00
print(in_90_days)  # 2026-06-15 12:00:00

# Difference between two datetimes
deadline = datetime(2026, 4, 1, 0, 0, 0)
delta    = deadline - now
print(f"{delta.days} days, {delta.seconds // 3600} hours until deadline")

# Days since epoch — useful for calculations
from datetime import date
today = date.today()
d = today - date(2000, 1, 1)
print(f"Days since Y2K: {d.days}")

Timezones — Naive vs Aware

A naive datetime has no timezone information — it is ambiguous. An aware datetime has a timezone attached. Always use aware datetimes when storing, comparing, or transmitting times. The old way (pytz) is replaced by zoneinfo in Python 3.9+. zoneinfo uses the IANA timezone database (the 'tz' database) which handles DST transitions and historical changes correctly. The biggest mistake: using replace() to change the timezone. replace(tzinfo=...) does not convert the time — it just stamps a new timezone label. Use astimezone() to convert.

from datetime import datetime, timezone, timedelta

# Aware datetime — UTC
utc_now = datetime.now(timezone.utc)
print(utc_now)            # 2026-03-17 11:30:45.123456+00:00
print(utc_now.isoformat()) # 2026-03-17T11:30:45.123456+00:00

# Convert to a different timezone
ut_plus5 = timezone(timedelta(hours=5))
ist_time  = utc_now.astimezone(ut_plus5)
print(ist_time)  # 2026-03-17 16:30:45.123456+05:00

# Python 3.9+ — use zoneinfo for named timezones
from zoneinfo import ZoneInfo
london = utc_now.astimezone(ZoneInfo('Europe/London'))
print(london)  # handles BST/GMT automatically

# Never compare naive and aware datetimes
naive = datetime(2026, 3, 17, 12, 0)
try:
    print(naive < utc_now)
except TypeError as e:
    print(f"Cannot compare: {e}")

Parsing Dates and Handling Errors

Parsing is where most production issues start. strptime is strict — even a trailing space or wrong case for %B ('March' vs 'MARCH') raises ValueError. fromisoformat is more forgiving for ISO 8601 strings. For real-world messy input, consider dateutil.parser which is lenient but slower. Always wrap parsing in try/except. Log the raw input and the format you expected — without that log, debugging takes twice as long.

from datetime import datetime, date

# Robust parsing with try/except
def parse_date(s, fmt='%Y-%m-%d'):
    try:
        return datetime.strptime(s, fmt)
    except ValueError as e:
        print(f"Failed to parse '{s}' with format '{fmt}': {e}")
        return None

# Using fromisoformat for ISO strings
iso_str = '2026-03-17T14:30:00+00:00'
dt = datetime.fromisoformat(iso_str)
print(dt)  # 2026-03-17 14:30:00+00:00

# Common mistake: missing leading zero
# '2026-3-17' fails with '%Y-%m-%d'
print(parse_date('2026-3-17', '%Y-%m-%d'))  # None

# dateutil.parser for flexible parsing (third-party)
# pip install python-dateutil
from dateutil import parser as dparser
print(dparser.parse('March 17, 2026 2:30pm'))  # 2026-03-17 14:30:00

Epoch Timestamps and Conversion

Timestamps (seconds since Unix epoch) are common in APIs and databases. Python's datetime.timestamp() converts an aware datetime to a float. For naive datetimes, it assumes local time — another footgun. Use datetime.fromtimestamp(ts, tz=timezone.utc) to convert back to an aware UTC datetime. Note that datetime.utcfromtimestamp() is deprecated (since 3.12) because it returns a naive datetime. Use fromtimestamp with tz=timezone.utc instead.

from datetime import datetime, timezone

# Aware UTC to timestamp
utc_now = datetime.now(timezone.utc)
ts = utc_now.timestamp()
print(ts)  # e.g., 1779172245.123456

# Timestamp back to aware datetime
back = datetime.fromtimestamp(ts, tz=timezone.utc)
print(back)  # 2026-03-17 11:30:45.123456+00:00

# WARNING: deprecated way (returns naive)
# naive_utc = datetime.utcfromtimestamp(ts)  # DON'T

# Common in APIs: Unix timestamp in milliseconds
ms_ts = 1779172245123
back_from_ms = datetime.fromtimestamp(ms_ts / 1000, tz=timezone.utc)
print(back_from_ms)

The datetime Class Hierarchy — Stop Treating It Like a String

Most devs reach for datetime.datetime when they just need a date, or a time. That's cargo-cult coding. The datetime module gives you four primary classes, and each exists for a reason. Ignoring them costs you readability and invites bugs.

datetime.date stores year, month, day. That's it. Use it for birthdays, billing cycles, anything timezone-agnostic. datetime.time holds hour, minute, second, microsecond — no date baggage. Perfect for recurring schedules or logging timestamps where the date lives elsewhere.

datetime.datetime combines both. It's the jack-of-all-trades, but master of none. Before you reach for it, ask: "Do I actually need the whole thing?" If not, use the narrower type. Your future self debugging a date-only field at 3 AM will thank you.

datetime.timedelta is the math engine. It represents duration, not a point in time. People mess this up constantly — they try to add two datetime objects, or subtract a timedelta from a timedelta. Wrong. timedelta only works with other timedeltas or datetime objects. Know your types.

The rule: pick the smallest class that models your data. It makes intent explicit and catches errors at compile time.

// io.thecodeforge — python tutorial

// Don't import everything — import what you need
from datetime import date, time, datetime, timedelta

// Wrong: mixing types for no reason
birthday = datetime(1990, 4, 15, 0, 0)  # time is meaningless here

// Right: use date when time is irrelevant
birthday = date(1990, 4, 15)

// Wrong: storing time with arbitrary date
trigger = datetime(2000, 1, 1, 14, 30, 0)  # '2000-01-01' is noise

// Right: use time for time-only data
trigger = time(14, 30, 0)

// Wrong: mixing timedelta math
today = date.today()
# tomorrow = today + 1  # TypeError: unsupported operand

// Right: use timedelta for arithmetic
tomorrow = today + timedelta(days=1)
print(f"Today: {today}, Tomorrow: {tomorrow}")

The Timezone Abyss — Why naive datetime is a bug waiting to surface

Six months from now, your datetime object will betray you. Every naive datetime — one without a tzinfo attached — is a ticking time bomb. They look fine in your local dev environment. Then your app goes to production, hits servers in three timezones, and suddenly 'midnight' means three different things.

Here's the hard truth: Python's default datetime is naive. It pretends timezones don't exist. The module has tzinfo, an abstract base class, but forces you to implement it yourself. Python 3.2 gave us timezone for fixed offsets. Python 3.9 gave us zoneinfo for the IANA database. Stop using pytz. Start using zoneinfo.

When you call datetime.now(), you get a naive local time. That's fine for a stopwatch. It's a disaster for anything that crosses timezone boundaries. The fix: always attach tzinfo. Use datetime.now(tz=zoneinfo.ZoneInfo('UTC')) or your local timezone. If you parse a string, call .replace(tzinfo=...) or .astimezone() immediately.

The litmus test: if two servers in different timezones would interpret your datetime differently, you have a bug. The only safe zone is UTC for storage, and convert at the presentation layer.

// io.thecodeforge — python tutorial

from datetime import datetime, timezone, timedelta
from zoneinfo import ZoneInfo  # Python 3.9+

// The Wrong Way — no timezone, lies to everyone
nail_coffin = datetime(2024, 12, 31, 23, 59, 59)
print(f"Naive: {nail_coffin}")  # Who knows what this means?

// The Right Way — zoneinfo, explicit
# Simulating a server in Tokyo
tokyo = ZoneInfo("Asia/Tokyo")
new_year_tokyo = datetime(2024, 12, 31, 23, 59, 59, tzinfo=tokyo)
# Convert to UTC for storage
new_year_utc = new_year_tokyo.astimezone(timezone.utc)
print(f"Tokyo: {new_year_tokyo}")
print(f"UTC:   {new_year_utc}")

// Production rule: store UTC, present local
print(f"New Year hit at {new_year_utc} UTC")

Timedelta Arithmetic — The Hidden Pitfalls in Production

Timedelta looks simple: add some days, subtract some seconds. But arithmetic with timedeltas has edge cases that will burn you in production. The cardinal sin: adding 30 days to a date and assuming you get the same day next month. You get February 30th, which doesn't exist, and Python silently clips it to February 28th. That's a billing bug. That's a subscription expiration bug.

If you need month-relative arithmetic, don't use timedelta. Use dateutil.relativedelta. It handles month boundaries correctly: add 1 month to January 31st gives February 28th (or 29th in leap years). Timedelta only handles absolute time deltas — days, seconds, microseconds. It doesn't know about months, because months are variable-length.

Another killer: adding timedelta to a naive datetime that crosses a DST boundary. The hour disappears or repeats. Fixed-offset timezones (like timezone.utc) are safe. But if your datetime is naive and your server's local timezone observes DST, timedelta arithmetic is a silent corruption.

The safe pattern: convert to UTC, do arithmetic, then convert back. Or use zoneinfo's aware datetimes. And for anything involving months, ignore timedelta and use dateutil.relativedelta. Your stakeholders won't forgive a 30-day-off billing cycle.

// io.thecodeforge — python tutorial

from datetime import datetime, timedelta
from dateutil.relativedelta import relativedelta  # pip install python-dateutil

// WRONG: adding 30 days to Jan 31 gives Feb 28/29 (silent clip)
start = datetime(2024, 1, 31)
bill_date = start + timedelta(days=30)
print(f"Wrong bill: {start} + 30 days = {bill_date}")  # Expect March 2? No.

// RIGHT: use relativedelta for month arithmetic
correct_bill = start + relativedelta(months=1)
print(f"Correct bill: {start} + 1 month = {correct_bill}")

// DST trap example
from zoneinfo import ZoneInfo
eastern = ZoneInfo("America/New_York")
dst_start = datetime(2024, 3, 10, 1, 30, tzinfo=eastern)  # 2 AM skips to 3 AM
two_hours_later = dst_start + timedelta(hours=2)
print(f"DST jump: {dst_start} + 2h = {two_hours_later}")  # 3:30 AM, not 4:30 AM

How Computers Count Time — and Why Your Epoch Logic Breaks at 03:14:08 UTC

Computers don't count dates; they count seconds since midnight January 1, 1970, UTC. That's the Unix epoch. Every datetime library, database timestamp, and file system metadata ultimately resolves to an integer or float of these seconds. Call time.time() and you get a float. Call datetime.now().timestamp() and you get another float. If the values disagree by a fraction of a second, welcome to floating-point rounding hell.

The real trap? Your production system will run past 2038 when the 32-bit signed integer overflows. Go check your embedded devices, payment terminals, and CI/CD runners. Most Python deployments are 64-bit, so you're safe. But ask yourself: does your logging pipeline store timestamps as 32-bit Unix timestamps? If you're shipping logs to an older SIEM, you're about to have a very bad January 2038.

Stop treating epoch timestamps as opaque numbers. They're not magic. They're seconds. Parse them with datetime.fromtimestamp() and validate the range. If you see a timestamp of 0 or 1, someone sent you the epoch. That's not "zero" — that's January 1, 1970. And your bug tracker is about to get a lot of angry tickets.

// io.thecodeforge — python tutorial

import time
from datetime import datetime, timezone

# Current epoch seconds as float
now_float = time.time()
print(f"time.time(): {now_float}")

# Convert to aware datetime
dt = datetime.fromtimestamp(now_float, tz=timezone.utc)
print(f"UTC datetime: {dt}")

# The 2038 overflow grenade — 32-bit max int
epoch_2038 = 2_147_483_647  # Last valid 32-bit signed second
overflow = epoch_2038 + 1
print(f"32-bit max: {datetime.fromtimestamp(epoch_2038, tz=timezone.utc)}")
print(f"Overflow: {datetime.fromtimestamp(overflow, tz=timezone.utc)}")

How Standard Dates Are Reported — and Why ISO 8601 Saves Migraines at 3 AM

Dates arrive in your codebase like raccoons at a dumpster: no format consistency, no timezone hint, and someone's always complaining. The industry standard is ISO 8601: 2024-03-19T18:13:54Z. The 'Z' means Zulu time, i.e., UTC. Python's datetime.fromisoformat() can parse it if you mask the 'Z' with +00:00. Or use datetime.strptime() with the right format string. Either way, pick one standard and enforce it at the API boundary.

Web apps get dates from HTTP headers, JSON payloads, and form submissions — each with different conventions. HTTP dates are RFC 2822 (Tue, 19 Mar 2024 18:13:54 GMT). JSON often sends 2024-03-19T18:13:54.000Z. Someone on your team will pass 03/19/2024 and break your log parser in production. Do not guess. Explicitly parse with strptime() and catch ValueError. Log the raw string when parsing fails — you'll thank yourself at 3 AM.

The senior move: normalize all incoming dates to ISO 8601 at the system boundary. Your database stores timestamps as UTC. Your logs go out in ISO 8601. Your frontend formats for the user's locale. If your backend ever outputs "2024-03-19 6:13 PM" to an API, an engineer in Frankfurt will write a strongly worded email about your cultural insensitivity.

// io.thecodeforge — python tutorial

from datetime import datetime

def parse_iso_8601(raw: str) -> datetime:
    """Parse ISO 8601 date, handling 'Z' suffix."""
    try:
        if raw.endswith('Z'):
            raw = raw[:-1] + '+00:00'
        return datetime.fromisoformat(raw)
    except ValueError as err:
        print(f"FAILED: {raw!r} -> {err}")
        raise

def parse_http_date(raw: str) -> datetime:
    """Parse RFC 2822 date from HTTP headers."""
    try:
        return datetime.strptime(
            raw, '%a, %d %b %Y %H:%M:%S %Z'
        )
    except ValueError as err:
        print(f"HTTP FAILED: {raw!r} -> {err}")
        raise

# Test both
print(parse_iso_8601("2024-03-19T18:13:54.000Z"))
print(parse_http_date("Tue, 19 Mar 2024 18:13:54 GMT"))

Constants — The Hidden Time Anchors in datetime

The datetime module provides constants that save you from hardcoding magic values. These include datetime.MINYEAR (1) and datetime.MAXYEAR (9999), which define the valid range for date objects. More importantly, datetime.timezone.utc returns a fixed timezone instance representing UTC — crucial for constructing aware datetimes without importing pytz or dateutil. Using datetime.timezone.utc instead of pytz.UTC avoids library dependencies and leverages Python's built-in timezone handling. Always reference datetime.timezone.utc when creating UTC-aware timestamps; it eliminates the ambiguity of naive datetimes and prevents the year-10000 bug in archival systems. These constants enforce boundary checks and timezone consistency without guesswork.

// io.thecodeforge — python tutorial

from datetime import datetime, timezone

# SAFE: use built-in UTC constant
utc_now = datetime.now(timezone.utc)
print(f"UTC now: {utc_now}")

# Validate year range
if utc_now.year < datetime.MINYEAR or utc_now.year > datetime.MAXYEAR:
    raise ValueError("Year out of valid range")

# Output:
# UTC now: 2025-04-08 14:30:00.123456+00:00

Examples of Usage: timedelta — More Than Just Add Days

Timedelta represents a duration (difference between two datetimes) and supports arithmetic with datetime, date, and other timedelta objects. Key operations: add/subtract days, seconds, microseconds, milliseconds, minutes, hours, and weeks. It also supports multiplication by integers and floor division. Common production patterns: calculating expiry dates (e.g., datetime.now(timezone.utc) + timedelta(days=30)), measuring execution time (end - start), and adjusting timestamps across timezone boundaries. Beware: timedelta does NOT handle months or years — those vary in length. For monthly intervals, use dateutil.relativedelta. Timedelta arithmetic preserves timezone awareness if both operands are aware. Example: duration = timedelta(hours=2, minutes=15).

// io.thecodeforge — python tutorial

from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)
expiry = now + timedelta(days=30, hours=6)
print(f"Expires: {expiry}")

duration = timedelta(hours=2, minutes=15)
if expiry - now > duration:
    print("Session still valid")

# Output:
# Expires: 2025-05-08 20:30:00.123456+00:00
# Session still valid

Examples of Usage: date — When You Only Need the Calendar

The date object stores year, month, and day — no time or timezone. Use it for birthdates, holidays, or any scenario where time is irrelevant. Key methods: date.today() returns current local date; date.fromtimestamp(ts) converts epoch seconds; date.fromisoformat('2025-04-08') parses ISO strings; date.replace(year=2026) creates modified copies. Comparison operators (<, >, ==) work directly on dates. Subtracting two dates yields a timedelta. Common mistake: using date objects where datetime is needed (e.g., logging timestamps). Production patterns: subscription renewal dates, flight schedules, fiscal-year boundaries. Always validate date ranges with datetime.MINYEAR and datetime.MAXYEAR.

// io.thecodeforge — python tutorial

from datetime import date

today = date.today()
renewal = date(today.year, 12, 31)  # year-end
days_left = renewal - today
print(f"Days to renewal: {days_left.days}")

parsed = date.fromisoformat('2025-12-25')
if parsed > today:
    print("Christmas is coming")

# Output:
# Days to renewal: 267
# Christmas is coming

Syntax — The Hidden Contracts in datetime Constructors

Every datetime constructor call is a contract with time. When you write datetime(2023, 10, 5), Python silently assumes midnight, no timezone, and no leap-second awareness. The syntax demands positional arguments in order: year, month, day, then optional hour, minute, second, microsecond, and tzinfo. Omitting tzinfo creates a naive object — a time bomb in distributed systems. The real trap: datetime(2023, 10, 5, 0, 0, 0) and datetime(2023, 10, 5) are identical, but the former misleads readers into thinking time is explicit. Always use keyword arguments for clarity: datetime(year=2023, month=10, day=5, tzinfo=timezone.utc). The date constructor accepts only year, month, day — omitting time completely. time accepts hour, minute, second, microsecond, and tzinfo. The timedelta constructor accepts days, seconds, microseconds, milliseconds, minutes, hours, and weeks — but only days and seconds are stored internally. This means timedelta(hours=25) becomes 1 day, 1 hour. Know the syntax defaults or your three-line script becomes a production incident.

// io.thecodeforge — python tutorial
from datetime import datetime, timedelta, timezone

# Contract: naivety hides bugs
d1 = datetime(2024, 3, 15)  # naive, midnight
d2 = datetime(year=2024, month=3, day=15, tzinfo=timezone.utc)  # explicit

# timedelta normalizes internally
t = timedelta(hours=25, minutes=30)
print(f"Days: {t.days}, seconds: {t.seconds}")  # Days: 1, seconds: 5400

# Never rely on implicit defaults in production
def scheduled_job():
    now = datetime.now(timezone.utc)
    # Always pass tzinfo — never datetime.now() alone
    return now

Technical Detail — The Internal Representation That Breaks Assumptions

Python's datetime object stores time as three integers: year, month, day, plus a time tuple (hour, minute, second, microsecond), and an optional tzinfo object. But the real internal model is a proleptic Gregorian calendar — it assumes the Gregorian calendar extends backward indefinitely, ignoring that different countries adopted it at different times. The timedelta stores only days (int) and seconds (int, 0-86399) and microseconds (int, 0-999999). When you add timedelta(hours=26), Python normalizes: 26 hours = 1 day + 2 hours, stored as days=1, seconds=7200. This normalization happens at construction, not arithmetic — meaning timedelta(days=1, seconds=7200) is identical to timedelta(hours=26). The date object stores year, month, day as int with valid ranges (year 1-9999, month 1-12, day 1-31). Timezone-aware datetimes store a reference to a tzinfo object — but tzinfo is an abstract base class. Python ships with timezone.utc and timezone(timedelta). For IANA timezones (e.g., 'America/New_York'), you must use zoneinfo (Python 3.9+) or pytz. The datetime.resolution attribute reveals the smallest representable difference: 1 microsecond. This matters when comparing timestamps from databases with nanosecond precision — you silently truncate.

// io.thecodeforge — python tutorial
from datetime import datetime, timedelta, timezone

# Internal storage: timedelta normalizes on creation
t = timedelta(hours=26, minutes=90)  # 26h + 1.5h = 27.5h = 1d 3.5h
print(f"Days: {t.days}, Seconds: {t.seconds}")  # 1 day + 12600 sec (3.5h)

# Resolution limit: microseconds
delta = timedelta(microseconds=1)
print(f"Resolution: {datetime.resolution}")  # 0:00:00.000001

# Proleptic Gregorian trap
d = datetime(year=1582, month=10, day=5)  # Valid in Python, never existed historically
print(d)  # 1582-10-05 00:00:00 (historical inaccuracy)

pendulum and arrow: Alternative DateTime Libraries

While Python's built-in datetime module is powerful, it has well-known pitfalls like the utcnow() DST bug and limited timezone support. Two popular third-party libraries, Pendulum and Arrow, aim to solve these issues with cleaner APIs and better defaults.

Pendulum is a drop-in replacement for datetime that provides immutable datetime instances, automatic timezone handling, and intuitive methods. For example, creating a UTC datetime is straightforward: pendulum.now('UTC') instead of datetime.utcnow(). Pendulum also supports human-readable diffs, timezone conversion, and formatting with a fluent interface.

```python import pendulum

# Safe UTC now (no DST bug) utc_now = pendulum.now('UTC') print(utc_now) # 2023-10-05T14:30:00+00:00

# Convert to another timezone nyc = utc_now.in_timezone('America/New_York') print(nyc) # 2023-10-05T10:30:00-04:00

# Human diff print(utc_now.diff_for_humans()) # '2 hours ago' ```

Arrow offers a similar philosophy with a simpler API. It provides a utcnow() method that returns an aware datetime (avoiding the naive datetime bug). Arrow also excels at parsing strings with its get() method, which intelligently detects formats.

```python import arrow

# Safe UTC now utc_now = arrow.utcnow() print(utc_now) # 2023-10-05T14:30:00+00:00

# Parse a date string dt = arrow.get('2023-10-05 14:30:00', 'YYYY-MM-DD HH:mm:ss') print(dt) # 2023-10-05T14:30:00+00:00

# Shift timezone nyc = utc_now.to('America/New_York') print(nyc) # 2023-10-05T10:30:00-04:00 ```

Both libraries handle DST transitions correctly and provide timezone-aware operations out of the box. They are especially useful in production systems where timezone bugs can cause data corruption or missed schedules. However, they add external dependencies, so evaluate whether the benefits outweigh the added complexity for your project.

import pendulum
import arrow

# Pendulum
utc_now_p = pendulum.now('UTC')
print(f"Pendulum UTC now: {utc_now_p}")

# Arrow
utc_now_a = arrow.utcnow()
print(f"Arrow UTC now: {utc_now_a}")

# Both produce aware datetimes, avoiding the utcnow() DST bug

timezone-Aware DateTime Handling Best Practices

Handling timezone-aware datetimes correctly is crucial to avoid the utcnow() DST bug and other timezone-related issues. Here are best practices for production systems:

1. Always use aware datetimes internally. Store datetimes in UTC and convert to local timezones only for display. This avoids ambiguity during DST transitions. Use datetime.now(timezone.utc) instead of datetime.utcnow().

```python from datetime import datetime, timezone

# Correct: aware UTC datetime utc_now = datetime.now(timezone.utc) print(utc_now) # 2023-10-05 14:30:00+00:00

# Wrong: naive datetime (subject to DST bug) naive_utc = datetime.utcnow() # Avoid! ```

2. Use zoneinfo (Python 3.9+) or pytz for timezone objects. zoneinfo is part of the standard library and uses the IANA timezone database. Convert between timezones using astimezone().

```python from zoneinfo import ZoneInfo

# Convert UTC to New York nyc_tz = ZoneInfo("America/New_York") nyc_time = utc_now.astimezone(nyc_tz) print(nyc_time) # 2023-10-05 10:30:00-04:00 ```

3. Store datetimes in UTC in databases. When retrieving, attach the UTC timezone before converting to local. This ensures consistency across servers and timezones.

4. Be careful with DST transitions. When doing arithmetic across DST boundaries, use zoneinfo which handles them correctly. Avoid naive timedelta arithmetic on local times.

```python # Correct: arithmetic on UTC then convert utc_future = utc_now + timedelta(days=1) nyc_future = utc_future.astimezone(nyc_tz)

# Wrong: arithmetic on local time (may be ambiguous) nyc_wrong = nyc_time + timedelta(days=1) # May skip or repeat hour ```

5. Use ISO 8601 for serialization. The .isoformat() method on aware datetimes produces a string with timezone offset, which is unambiguous. Parse with datetime.fromisoformat() (Python 3.7+).

Following these practices eliminates the utcnow() DST bug and ensures reliable datetime handling across timezones.

from datetime import datetime, timezone, timedelta
from zoneinfo import ZoneInfo

# Best practice: use aware UTC datetime
utc_now = datetime.now(timezone.utc)
print(f"UTC now: {utc_now}")

# Convert to New York
nyc_tz = ZoneInfo("America/New_York")
nyc_time = utc_now.astimezone(nyc_tz)
print(f"NYC time: {nyc_time}")

# Arithmetic on UTC, then convert
utc_tomorrow = utc_now + timedelta(days=1)
nyc_tomorrow = utc_tomorrow.astimezone(nyc_tz)
print(f"NYC tomorrow: {nyc_tomorrow}")

# ISO 8601 serialization
iso_string = utc_now.isoformat()
print(f"ISO 8601: {iso_string}")
# Parse back
parsed = datetime.fromisoformat(iso_string)
print(f"Parsed: {parsed}")

dateutil: Advanced Date Parsing and Recurrence

The dateutil library extends Python's datetime capabilities with powerful parsing, recurrence rules, and timezone support. It is especially useful for handling complex date strings and generating recurring dates (e.g., 'every third Friday').

Parsing with dateutil.parser The parser.parse() function can interpret a wide variety of date formats without explicit format strings. This is ideal for user input or data from external sources.

```python from dateutil import parser

# Parse various formats date1 = parser.parse("2023-10-05") date2 = parser.parse("10/05/2023") date3 = parser.parse("October 5, 2023 2:30 PM") date4 = parser.parse("2023-10-05T14:30:00Z") print(date1, date2, date3, date4) # All return datetime objects (naive or aware depending on input) ```

Recurrence with dateutil.rrule The rrule module implements iCalendar RFC 5545 recurrence rules. You can generate sequences of dates like 'every month on the 15th' or 'every weekday'.

```python from dateutil.rrule import rrule, MONTHLY, WEEKLY, MO, FR from datetime import datetime

# Every month on the 15th, starting from now start = datetime.now() monthly_15th = list(rrule(MONTHLY, dtstart=start, bymonthday=15, count=5)) print(monthly_15th)

# Every Monday and Friday for 4 weeks weekdays = list(rrule(WEEKLY, dtstart=start, byweekday=(MO, FR), count=8)) print(weekdays) ```

Timezones with dateutil.tz dateutil provides tz.tzutc() and tz.gettz() for timezone objects, which can be used with standard datetime.

```python from dateutil import tz

# Create timezone-aware datetime utc_tz = tz.tzutc() nyc_tz = tz.gettz("America/New_York") dt_aware = datetime(2023, 10, 5, 14, 30, tzinfo=utc_tz) print(dt_aware.astimezone(nyc_tz)) ```

dateutil is a robust choice for applications that need flexible date parsing or recurring event generation. It is widely used in data science and web development.

from dateutil import parser, rrule, tz
from datetime import datetime

# Flexible parsing
print(parser.parse("2023-10-05"))
print(parser.parse("10/05/2023"))
print(parser.parse("October 5, 2023 2:30 PM"))

# Recurrence: every 1st and 15th of month
start = datetime(2023, 1, 1)
rule = rrule.rrule(rrule.MONTHLY, dtstart=start, bymonthday=[1, 15], count=6)
for dt in rule:
    print(dt.date())

# Timezone conversion
utc = tz.tzutc()
nyc = tz.gettz("America/New_York")
dt = datetime(2023, 10, 5, 14, 30, tzinfo=utc)
print(dt.astimezone(nyc))