Immunize Timezone Naive Datetime

timezone-naive-datetime

Always construct datetimes as offset-aware in UTC. Mixing naive and aware datetimes in a comparison or subtraction raises:

TypeError: can't compare offset-naive and offset-aware datetimes

Datetimes that arrive from outside the process — JSON expires_at fields, JWT exp claims, database TIMESTAMPTZ columns, RFC 3339 strings parsed with fromisoformat — are aware. Datetimes you create inside the process must match.

Example

Wrong — datetime.now() returns a naive datetime; the comparison crashes:

from datetime import datetime

def is_token_expired(expiry: datetime) -> bool:
    return datetime.now() > expiry

Right — pass timezone.utc so the local datetime is aware:

from datetime import datetime, timezone

def is_token_expired(expiry: datetime) -> bool:
    return datetime.now(timezone.utc) > expiry

Don't reach for datetime.utcnow()

datetime.utcnow() returns a naive datetime whose value happens to be in UTC — it carries no tzinfo. Comparing it with an aware datetime raises the same TypeError, and the function is deprecated as of Python 3.12. Use datetime.now(timezone.utc) instead.

Parsing aware datetimes

When reading external timestamps:

• ISO 8601 with Z or +00:00: datetime.fromisoformat(s.replace("Z", "+00:00"))
• POSIX timestamps: datetime.fromtimestamp(ts, tz=timezone.utc)
• Database driver: prefer TIMESTAMPTZ over TIMESTAMP and let the

driver return aware values.

Immunity note

The verification asserts that the fixture's expiry check accepts an aware datetime without crashing. The repro raises TypeError; the fix returns the boolean the consumer expects. The interface is unchanged.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: viditkbhatnagar
• Source: viditkbhatnagar/immunize
• License: Apache-2.0
• Homepage: https://pypi.org/project/immunize/

Install and usage instructions live in the source repository linked above.