Guía completa de Python datetime | Uso de fechas, horas y zonas horarias con ejemplos prácticos

1. Introducción

Uno de los módulos imprescindibles para manejar fechas y horas en Python es datetime . Al usar este módulo, es posible realizar diversas operaciones, como obtener la hora actual, convertir formatos de fecha y hora, y calcular tiempos.

Sin embargo, para los principiantes en Python, el manejo de datetime puede sentirse un poco difícil. Por ejemplo:

• “Quiero obtener la fecha o hora actual, pero ¿qué función debo usar?”
• “¡No entiendo cómo procesar la hora considerando la zona horaria!”
• “¿Cómo calculo fechas?”

En este artículo, explicaremos de manera clara desde lo básico hasta lo avanzado del módulo datetime de Python. Para que incluso los principiantes puedan entenderlo sin problemas, incluiremos ejemplos de código en la explicación, así que por favor úsenlo como referencia.

2. ¿Qué es el módulo datetime? Entendamos los conceptos básicos

2.1 Resumen del módulo datetime

Python tiene como biblioteca estándar el módulo datetime, que permite manipular fechas y horas de manera sencilla. El módulo datetime incluye clases principales como las siguientes.

De estas, la más utilizada es la clase datetime.

2.2 Cómo importar el módulo datetime

Para usar el módulo datetime de Python, primero es necesario importarlo. Al usar import datetime de la siguiente manera, se puede importar todo el módulo.

import datetime

# Obtener la fecha y hora actual
now = datetime.datetime.now()
print(now)

Además, es posible importar solo clases específicas.

from datetime import datetime

# Obtener la fecha y hora actual
now = datetime.now()
print(now)

Al importar en la forma from datetime import datetime, en el código no es necesario escribir datetime de manera duplicada como en datetime.datetime.now(), lo que lo hace más simple.

3. Cómo obtener la hora actual y la fecha de hoy en Python (diferencia entre now y today)

3.1 Cómo obtener la fecha y hora actual

En Python, para obtener la fecha y hora actual, se utiliza datetime.now().

from datetime import datetime

now = datetime.now()
print("Fecha y hora actual:", now)

Al ejecutar este código, se obtiene una salida como la siguiente.

Fecha y hora actual: 2025-02-01 12:34:56.789012

Este formato es de la forma YYYY-MM-DD HH:MM:SS.ssssss e incluye fecha, hora y microsegundos.

3.2 Cómo obtener la fecha de hoy

Si solo se desea obtener la fecha de hoy, se utiliza date.today().

from datetime import date

today = date.today()
print("Fecha de hoy:", today)

Ejemplo de salida:

Fecha de hoy: 2025-02-01

3.3 Diferencia entre now() y today()

Se recomienda usarlos según el propósito.

4. Conversión de formato de fecha y hora (cadena ⇔ datetime)

Al manejar fechas o horas, la conversión de formato es extremadamente importante. En Python, se puede convertir mutuamente entre fecha/hora y cadenas usando strftime() y strptime().

4.1 Convertir objeto datetime a cadena (strftime)

Si desea convertir la fecha/hora a una cadena en un formato específico, use strftime().

from datetime import datetime

now = datetime.now()
formatted_date = now.strftime("%Y-%m-%d %H:%M:%S")
print("Fecha con formato:", formatted_date)

Salida:

Fecha con formato: 2025-02-01 12:34:56

4.2 Convertir cadena a objeto datetime (strptime)

Para convertir desde una cadena a datetime, use strptime().

from datetime import datetime

date_str = "2025-02-01 12:34:56"
dt = datetime.strptime(date_str, "%Y-%m-%d %H:%M:%S")
print("Objeto datetime después de la conversión:", dt)

Salida:

Objeto datetime después de la conversión: 2025-02-01 12:34:56

5. Cómo sumar y restar fechas en Python (Uso de timedelta)

En Python, mediante el uso de la clase timedelta, es posible realizar fácilmente las adiciones y sustracciones de fechas o horas.

5.1 Lo básico de la clase timedelta

from datetime import datetime, timedelta

# Obtener la fecha y hora actual
now = datetime.now()

# Obtener la fecha 7 días después
future_date = now + timedelta(days=7)
print("Fecha 7 días después:", future_date)

# Obtener la fecha 3 días antes
past_date = now - timedelta(days=3)
print("Fecha 3 días antes:", past_date)

5.2 Suma y resta en unidades de tiempo

from datetime import datetime, timedelta

now = datetime.now()

# La hora 1 hora después
one_hour_later = now + timedelta(hours=1)
print("La hora 1 hora después:", one_hour_later)

# La hora 30 minutos antes
thirty_minutes_ago = now - timedelta(minutes=30)
print("La hora 30 minutos antes:", thirty_minutes_ago)

5.3 Calcular la diferencia entre dos fechas

from datetime import datetime

# Definir dos fechas
date1 = datetime(2025, 2, 10)
date2 = datetime(2025, 2, 1)

# Calcular la diferencia
difference = date1 - date2
print("Diferencia de fechas:", difference)
print("Diferencia en días:", difference.days, "días")

6. Manejo de fechas y horas considerando la zona horaria (diferencias entre pytz y zoneinfo)

Al manejar fechas y horas en Python, es extremadamente importante considerar la zona horaria.

6.1 pytz Configuración de zona horaria usando pytz

from datetime import datetime
import pytz

# Especificación de la zona horaria
japan_tz = pytz.timezone('Asia/Tokyo')

# Obtener la hora UTC actual
utc_now = datetime.utcnow()

# Convertir a JST (Hora Estándar de Japón)
jst_now = utc_now.replace(tzinfo=pytz.utc).astimezone(japan_tz)
print("Hora de Japón (JST):", jst_now)

6.2 zoneinfo (Python 3.9 o posterior) Configuración de zona horaria usando zoneinfo

from datetime import datetime
from zoneinfo import ZoneInfo

# Obtener la hora actual en JST (Hora Estándar de Japón)
jst_now = datetime.now(ZoneInfo("Asia/Tokyo"))
print("Hora actual en JST:", jst_now)

Si está utilizando Python 3.9 o posterior, se recomienda utilizar zoneinfo.

7. Errores y sus soluciones

Al usar el módulo datetime de Python, especialmente los principiantes pueden encontrarse con varios errores comunes.

7.1 AttributeError: type object 'datetime.datetime' has no attribute 'timedelta'

from datetime import datetime

# Intentando usar timedelta pero error
now = datetime.now()
new_date = now + datetime.timedelta(days=7)

Solución:

from datetime import datetime, timedelta

now = datetime.now()
new_date = now + timedelta(days=7)
print(new_date)

7.2 TypeError: can't subtract offset-naive and offset-aware datetimes

from datetime import datetime
import pytz

dt_naive = datetime(2025, 2, 1, 12, 0)
dt_aware = datetime(2025, 2, 1, 12, 0, tzinfo=pytz.utc)

diff = dt_aware - dt_naive  # Error ocurre

Solución:

dt_aware = dt_naive.replace(tzinfo=pytz.utc)

8. Ejemplos prácticos

8.1 Cómo generar un rango de fechas

from datetime import datetime, timedelta

start_date = datetime(2025, 2, 1)
end_date = datetime(2025, 2, 7)

date_list = [start_date + timedelta(days=i) for i in range((end_date - start_date).days + 1)]

for date in date_list:
    print(date.strftime("%Y-%m-%d"))

8.2 Cálculo de fechas considerando días laborables (días laborables)

import pandas as pd

business_days = pd.bdate_range(start="2025-02-01", end="2025-02-10")

for day in business_days:
    print(day.date())

8.3 Conversión de sello de tiempo UNIX

from datetime import datetime

timestamp = 1735689600
dt = datetime.fromtimestamp(timestamp)
print("Datetime después de la conversión:", dt)

9. Preguntas frecuentes (FAQ)

9.1 datetime y time, ¿cuál es la diferencia?

9.2 strftime y strptime, ¿cuál es la diferencia?

from datetime import datetime

# datetime → cadena (strftime)
now = datetime(2025, 2, 1, 12, 0, 0)
formatted_str = now.strftime("%Y-%m-%d %H:%M:%S")
print("Convertido a cadena:", formatted_str)

# cadena → datetime (strptime)
date_str = "2025-02-01 12:00:00"
parsed_date = datetime.strptime(date_str, "%Y-%m-%d %H:%M:%S")
print("Convertido a datetime:", parsed_date)

9.3 ¿Cómo convertir un timestamp UNIX a datetime?

from datetime import datetime

timestamp = 1735689600
dt = datetime.fromtimestamp(timestamp)
print("datetime tras la conversión:", dt)

10. Resumen

10.1 Resumen de los puntos clave del artículo

• datetime es un módulo de la biblioteca estándar para manejar fechas y horas en Python.
• datetime.now() para obtener la fecha y hora actuales, date.today() para obtener solo la fecha actual.
• strftime() para datetime → cadena, strptime() para cadena → datetime .
• timedelta(days=7) para calcular la fecha una semana después.
• En Python 3.9 y posteriores se usa zoneinfo, en versiones anteriores se usa pytz .
• datetime objetos pueden compararse con >, < y == .

10.2 Documentación oficial y materiales de referencia

• Documentación oficial de Python (módulo datetime)
• Documentación de pytz
• zoneinfo (Python 3.9 en adelante)

10.3 Recomendemos la práctica del procesamiento de tiempo en Python

✅ Desarrollo de una aplicación de gestión de horarios
✅ Análisis de datos de registro
✅ Cálculo de horas en diferentes zonas horarias
✅ Implementación de una función de recordatorio automático

¡Gracias por leer hasta el final!