zoneinfo en Python: zonas horarias

Trabajar con fechas parece sencillo hasta que una aplicación atiende usuarios de varios países, convierte horarios de reuniones, almacena eventos en UTC o atraviesa cambios de horario de verano. Un desplazamiento fijo como -03:00 no representa todas las reglas históricas y futuras de una región. El módulo zoneinfo en Python resuelve este problema conectando objetos datetime con la base de datos de zonas horarias de IANA.

En esta guía aprenderás a crear fechas conscientes de zona, convertir horarios con astimezone(), tratar instantes ambiguos mediante fold, instalar tzdata, validar claves, almacenar fechas correctamente y evitar errores frecuentes. El artículo complementa nuestras guías sobre listas en Python, collections, descriptors, rendimiento en Python y diccionarios.

Qué ofrece zoneinfo

zoneinfo forma parte de la biblioteca estándar desde Python 3.9. Implementa datetime.tzinfo usando las reglas de IANA Time Zone Database. En lugar de depender únicamente de desplazamientos fijos, permite usar claves como America/Sao_Paulo, Europe/Madrid, America/New_York y Asia/Tokyo.

from datetime import datetime
from zoneinfo import ZoneInfo

ahora_sp = datetime.now(ZoneInfo("America/Sao_Paulo"))
print(ahora_sp)
print(ahora_sp.tzname())

El resultado es un datetime aware: conoce su zona y su desplazamiento respecto a UTC, lo que permite conversiones y cálculos más seguros.

Fechas ingenuas y conscientes

Un datetime ingenuo no tiene tzinfo. Puede representar hora local, UTC u otra referencia, pero el objeto no indica cuál interpretación es correcta.

from datetime import datetime

ingenua = datetime(2026, 7, 29, 9, 0)
print(ingenua.tzinfo)  # None

Una fecha consciente incluye información de zona:

from datetime import datetime
from zoneinfo import ZoneInfo

consciente = datetime(
    2026, 7, 29, 9, 0,
    tzinfo=ZoneInfo("America/Sao_Paulo"),
)
print(consciente.utcoffset())

En sistemas reales, define explícitamente el significado de cada marca temporal. Mezclar valores ingenuos y conscientes puede generar excepciones, ordenamientos incorrectos y tareas ejecutadas en el momento equivocado.

Crear objetos ZoneInfo

La clase principal recibe una clave IANA:

from zoneinfo import ZoneInfo

sao_paulo = ZoneInfo("America/Sao_Paulo")
madri = ZoneInfo("Europe/Madrid")
tokio = ZoneInfo("Asia/Tokyo")

Las claves distinguen mayúsculas y minúsculas y deben coincidir con una zona disponible. Evita abreviaturas como EST, CST o BRT, porque pueden ser ambiguas y no contienen todas las reglas de transición.

Convertir con astimezone()

Un diseño confiable almacena el instante en UTC y lo convierte en la frontera de la aplicación según la zona preferida del usuario.

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

instante_utc = datetime(2026, 7, 29, 12, 0, tzinfo=timezone.utc)

sp = instante_utc.astimezone(ZoneInfo("America/Sao_Paulo"))
madri = instante_utc.astimezone(ZoneInfo("Europe/Madrid"))
tokio = instante_utc.astimezone(ZoneInfo("Asia/Tokyo"))

print(sp)
print(madri)
print(tokio)

Los tres objetos representan el mismo instante. Solo cambian la presentación local, el desplazamiento y las reglas de horario de verano.

replace(tzinfo=…) no convierte

Un error habitual consiste en usar replace(tzinfo=...) para convertir una fecha que ya tiene significado. Ese método añade o sustituye metadatos; no ajusta hora y minuto para conservar el instante.

valor = datetime(2026, 7, 29, 9, 0)
localizado = valor.replace(tzinfo=ZoneInfo("America/Sao_Paulo"))

Este uso es correcto únicamente cuando sabes que el valor ingenuo ya significa las 09:00 en São Paulo. Para transformar un instante consciente entre zonas, utiliza astimezone().

Aritmética y horario de verano

La documentación oficial de zoneinfo explica que los objetos ZoneInfo participan en la aritmética de datetime y ajustan el desplazamiento al cruzar transiciones de horario de verano.

from datetime import datetime, timedelta
from zoneinfo import ZoneInfo

los_angeles = ZoneInfo("America/Los_Angeles")
antes = datetime(2020, 10, 31, 12, tzinfo=los_angeles)
despues = antes + timedelta(days=1)

print(antes, antes.tzname())
print(despues, despues.tzname())

La hora civil sigue siendo mediodía, pero el desplazamiento puede cambiar. “Mañana a las 12” no siempre equivale a “dentro de exactamente 24 horas”.

Horas ambiguas y fold

Cuando el reloj retrocede, una misma hora local puede ocurrir dos veces. El atributo fold distingue ambas apariciones. El valor predeterminado 0 usa el desplazamiento anterior a la transición, mientras 1 selecciona el posterior.

from datetime import datetime
from zoneinfo import ZoneInfo

zona = ZoneInfo("America/Los_Angeles")
primera = datetime(2020, 11, 1, 1, 30, tzinfo=zona, fold=0)
segunda = primera.replace(fold=1)

print(primera, primera.utcoffset())
print(segunda, segunda.utcoffset())

Al convertir desde UTC con astimezone(), Python establece fold correctamente. La dificultad aparece cuando un usuario introduce directamente una hora local dentro de una franja ambigua.

Horas locales inexistentes

Durante la transición opuesta, el reloj avanza y algunas horas locales nunca ocurren. Una región puede saltar de 01:59 a 03:00. Crear directamente una fecha para las 02:30 no garantiza una validación automática.

Los sistemas de agenda críticos deben validar mediante ida y vuelta: asociar la zona, convertir a UTC, volver a la zona original y comparar los componentes locales. También puede definirse una política explícita para mover el evento al siguiente horario válido.

UTC como representación interna

Una arquitectura sólida suele almacenar instantes en UTC y guardar la clave de zona por separado cuando también importa la intención local.

evento = {
    "inicio_utc": "2026-07-29T12:00:00Z",
    "timezone": "America/Sao_Paulo",
}

Guardar solo “09:00” pierde el instante. Guardar únicamente UTC puede perder la intención de calendario. Una reunión recurrente quizá deba mantenerse a las 09:00 locales incluso cuando cambie el desplazamiento. El modelo debe distinguir un instante absoluto de una regla civil recurrente.

Serialización ISO 8601

datetime.isoformat() incluye el desplazamiento actual, pero no conserva necesariamente la clave IANA.

texto = ahora_sp.isoformat()
print(texto)

El desplazamiento -03:00 por sí solo no codifica todas las reglas de America/Sao_Paulo. Guarda también la clave cuando futuras conversiones dependan de la zona original.

Origen de los datos de zona

El módulo no incorpora toda la base IANA directamente en el código de Python. Primero busca archivos del sistema mediante TZPATH. Si no encuentra datos, intenta usar el paquete oficial tzdata.

Muchos sistemas Unix ya incluyen la base. Windows normalmente no ofrece una base IANA en las mismas rutas, por lo que los proyectos multiplataforma deberían declarar:

python -m pip install tzdata

Convertir tzdata en una dependencia explícita reduce diferencias entre desarrollo, CI, contenedores y producción.

Tratar ZoneInfoNotFoundError

Una clave inválida o una base ausente produce ZoneInfoNotFoundError, subclase de KeyError.

from zoneinfo import ZoneInfo, ZoneInfoNotFoundError

try:
    zona = ZoneInfo("America/Ciudad_Desconocida")
except ZoneInfoNotFoundError:
    print("Zona horaria no disponible")

No aceptes cualquier texto sin validación. Prefiere una lista controlada de zonas soportadas y distingue los errores de entrada de los fallos de configuración del servidor.

Listar zonas disponibles

available_timezones() devuelve las claves canónicas encontradas en las fuentes activas.

from zoneinfo import available_timezones

zonas = available_timezones()
print("America/Sao_Paulo" in zonas)

La función puede abrir muchos archivos y recalcula el conjunto en cada llamada. Evita ejecutarla en cada petición. Además, las claves IANA son identificadores técnicos; una interfaz debería asociarlas con nombres traducidos y ciudades comprensibles.

Caché de ZoneInfo

El constructor principal mantiene una caché. Las llamadas repetidas con la misma clave normalmente devuelven la misma instancia:

a = ZoneInfo("Europe/Paris")
b = ZoneInfo("Europe/Paris")
print(a is b)  # True

Esto reduce trabajo y estabiliza la identidad. ZoneInfo.no_cache() y ZoneInfo.clear_cache() existen, pero pueden cambiar la semántica de fechas ya creadas. Resérvalos para pruebas controladas o infraestructura especializada.

Probar código con zonas horarias

Incluye casos próximos a transiciones, no solo fechas ordinarias. Prueba conversiones UTC-local, local-UTC, horas ambiguas, horas inexistentes, claves inválidas y entornos sin datos de zona.

def convertir_para_usuario(instante_utc, clave):
    if instante_utc.tzinfo is None:
        raise ValueError("El instante debe ser consciente")
    return instante_utc.astimezone(ZoneInfo(clave))

Utiliza instantes fijos en las pruebas. Depender directamente de datetime.now() hace que los fallos cambien con el reloj y sean difíciles de reproducir.

Programaciones recurrentes

Dos reglas aparentemente iguales pueden diferir: ejecutar cada 24 horas exactas o ejecutar todos los días a las 09:00 en la zona del usuario. Las transiciones de horario de verano pueden separar ambos resultados.

Para recurrencia civil, guarda fecha local, hora local y clave IANA, y calcula cada aparición con las reglas vigentes. Para intervalos absolutos, trabaja en UTC. Documenta la interpretación en nombres de campos, funciones y APIs.

Uso en APIs y bases de datos

Cuando una API recibe una fecha, exige un desplazamiento o una clave de zona separada. Rechaza valores desnudos y ambiguos. En la base de datos, usa tipos que preserven el instante y normaliza comparaciones a UTC. Convierte únicamente para mostrar al usuario.

La aplicación también debe controlar actualizaciones de la base IANA. Los gobiernos pueden cambiar reglas y una nueva versión de tzdata puede modificar eventos futuros. Actualiza dependencias, repite pruebas y registra versiones en procesos regulados.

Errores frecuentes

• Usar abreviaturas ambiguas en lugar de claves IANA.
• Confundir replace(tzinfo=...) con una conversión.
• Comparar fechas ingenuas y conscientes.
• Guardar solo el desplazamiento y perder la zona original.
• Sumar 24 horas cuando la regla significa “misma hora local mañana”.
• Ignorar fold durante horas repetidas.
• Suponer que todo servidor tiene datos IANA.
• Llamar a available_timezones() en cada petición.

Buenas prácticas

• Usa UTC para instantes internos y claves IANA para presentación y recurrencia.
• Declara tzdata en aplicaciones multiplataforma.
• Convierte con astimezone().
• Valida las zonas permitidas.
• Prueba límites de transición y horas ambiguas.
• Conserva la intención local cuando el producto lo necesite.
• Actualiza periódicamente los datos de zona.
• Consulta también la documentación oficial de datetime.

Conclusión

El módulo zoneinfo en Python representa zonas horarias reales sin necesitar una biblioteca externa para la lógica principal. Conecta las reglas IANA con datetime, aplica transiciones históricas, convierte instantes de forma segura y admite horas repetidas mediante fold.

El reto principal consiste en modelar la intención. Los instantes únicos deben normalizarse a UTC; los compromisos ligados al reloj local deben conservar su clave IANA. Con validación, tzdata, pruebas centradas en transiciones y uso correcto de astimezone(), la aplicación evita reuniones desplazadas, tareas ejecutadas fuera de hora y marcas temporales imposibles de interpretar.