How to manage Timezones and DateTime serialization

Configure application-wide timezones, convert datetimes, and serialize timezone-aware outputs using ZDateTime.

ZCore provides timezone management built on Python's zoneinfo standard library, ensuring consistent UTC storage in databases and formatted timezone-aware outputs for API consumers.

1. Configure the Application Timezone

Set your desired IANA timezone in .env:

# .env
TIMEZONE="America/New_York"
AUTO_CONVERT_TIMEZONE=True

Or declare it in your Settings subclass:

# config.py
from zcore.config import Settings

class AppSettings(Settings):
    TIMEZONE: str = "Europe/London"
    AUTO_CONVERT_TIMEZONE: bool = True

2. Using Timezone Utilities in Code

Import timezone helpers directly from zcore or zcore.utils.timezone:

from zcore.utils.timezone import now, utc_now, to_app_timezone, format_iso_with_app_timezone

# Get current datetime in configured application timezone
local_time = now()

# Get current datetime in UTC
utc_time = utc_now()

# Convert a database datetime (naive or aware) to the application timezone
converted_time = to_app_timezone(task.created_at)

# Format datetime as ISO 8601 string with application timezone offset
iso_string = format_iso_with_app_timezone(task.created_at)

3. Automatic Response Formatting with `ZDateTime`

Use the ZDateTime type annotation in your Pydantic schemas. When the schema is serialized to JSON, it is automatically converted and formatted to the application's timezone:

# schemas.py
import uuid
from datetime import datetime
from zcore import Zchema
from zcore.utils.timezone import ZDateTime

class TaskResponse(Zchema):
    __model__ = "tasks"

    id: uuid.UUID
    title: str
    created_at: ZDateTime
    updated_at: ZDateTime | None = None

Timezone Fallback: If an invalid or unrecognized timezone string is configured, get_app_timezone() logs a warning and automatically falls back to UTC.

How to manage Timezones and DateTime serialization

1. Configure the Application Timezone

2. Using Timezone Utilities in Code

3. Automatic Response Formatting with ZDateTime

On this page

3. Automatic Response Formatting with `ZDateTime`