datetime, zoneinfo y hora

Almacena instantes en UTC con datetime consciente de la zona horaria. Convierte para mostrar con zoneinfo (tzdata en Windows a través del paquete tzdata). Usa timedelta para duraciones, no solo segundos enteros.

Receta

from datetime import datetime, timezone
from zoneinfo import ZoneInfo
 
utc_now = datetime.now(timezone.utc)
local = utc_now.astimezone(ZoneInfo("America/New_York"))
print(utc_now.isoformat(), local.isoformat())

Cuándo usar esto:

• Sellos de tiempo de API (siempre ISO-8601 UTC)
• Formato de visualización local del usuario
• Programación a través de límites de horario de verano (DST)
• Medición del tiempo transcurrido (monotonic para rendimiento)
• Análisis de cadenas ISO de JSON

Ejemplo funcional

from datetime import datetime, timedelta, timezone
from zoneinfo import ZoneInfo
 
def next_billing(from_utc: datetime, days: int) -> datetime:
    if from_utc.tzinfo is None:
        raise ValueError("se requiere datetime consciente")
    return from_utc + timedelta(days=days)
 
def format_for_user(instant_utc: datetime, tz_name: str) -> str:
    tz = ZoneInfo(tz_name)
    return instant_utc.astimezone(tz).strftime("%Y-%m-%d %H:%M %Z")
 
start = datetime(2026, 7, 9, 12, 0, tzinfo=timezone.utc)
due = next_billing(start, 30)
print(format_for_user(due, "Europe/Berlin"))

Lo que esto demuestra:

• Rechaza datetimes ingenuos en funciones de dominio
• La aritmética con timedelta preserva la conciencia de zona horaria
• Nombres IANA de ZoneInfo para DST correcto
• strftime solo para visualización: almacena ISO en los datos

Análisis detallado

Consciente vs. Ingenuo

Medición de rendimiento

• time.perf_counter() para benchmarks
• No datetime.now para duraciones

Errores comunes

• Comparaciones ingenuas de now() - Errores de DST. Solución: datetime.now(timezone.utc).
• Entero de época en todas partes - Pierde contexto de subsegundo y zona horaria. Solución: datetime en modelos, época en el límite si es necesario.
• zoneinfo faltante en Windows - Instala tzdata de PyPI. Solución: Documentar en el despliegue.
• Análisis de horas locales ambiguas - Doblez de DST. Solución: Almacena UTC; convierte solo al mostrar.
• strftime %Z engañoso - Las abreviaturas son ambiguas. Solución: Incluye el desplazamiento %z en las APIs.

Alternativas

Preguntas frecuentes

Relacionado

• json y Serialización - ISO en JSON
• Descripción general de la biblioteca estándar - mapa
• hashlib, secrets y uuid - ids basados en tiempo (precaución con uuid1)
• Mejores prácticas de la biblioteca estándar - reglas de tiempo

Versiones de la pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.