Manipular fechas y horas en Python

En este post vamos a ver el módulo datetime de la librería estándar de Python. Esta librería proporciona clases para trabajar con fechas y horas y realizarles distintos tipos de operaciones. En concreto, dentro de datetime encontramos las siguientes tres clases principales:

• date: para representar fechas.
• time: para representar horas.
• datetime: para representar combinaciones de fecha y hora.

Para utilizar estas clases en nuestro código, primero tenemos que importarlas mediante el siguiente comando:

import datetime

En el resto del artículo vamos a ver qué podemos hacer con estas tres clases, cómo realizar operaciones aritméticas entre ellas, y cómo darles formato con los métodos strftime() y strptime().

Clase date

Como su nombre indica, una instancia de la clase date representa una fecha en el calendario Gregoriano.

Constructor y propiedades

Para crear un objeto date en una fecha determinada, hemos de introducir los valores numéricos de la fecha en el constructor de la clase. En el siguiente ejemplo vemos cómo crear una instancia de date que representa la fecha de 22 de julio de 2021:

>>> fecha = datetime.date(2021, 7, 22)

Como se muestra en el ejemplo, el constructor toma los parámetros de año, mes y día en este mismo orden. Cuando tenemos un objeto date, podemos acceder a estos tres parámetros referenciándolos por su nombre en inglés:

>>> fecha.year
2021
>>> fecha.month
7
>>> fecha.day
22

Además, al crear una fecha hemos de tener en cuenta que los meses y los días que indiquemos tienen que ser válidos. Es decir, no podemos crear una fecha con el mes 13 o un día que se salga del rango de días del mes especificado, ya que en estos casos obtenemos un error del tipo ValueError.

>>> datetime.date(2021, 13, 22)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: month must be in 1..12
>>> datetime.date(2021, 8, 32)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: day is out of range for month

Métodos útiles

La clase date tiene distintos métodos entre los cuales destacan los siguientes.

• date.today(): para obtener la fecha de hoy.

>>> fecha = datetime.date.today()
>>> print(fecha)
2021-07-22

• date.isoweekday(): retorna un entero entre 1 y 7 que representa el día de la semana de la fecha, siendo 1 lunes y 7 domingo. El siguiente ejemplo nos muestra que el día 22 de julio de 2021 cayó en jueves.

>>> fecha = datetime.date(2021, 7, 22)
>>> fecha.isoweekday()
4

• date.replace(): cambia el año, mes y/o día de una fecha según especifiquemos respectivamente con los parámetros year, month y day. En el siguiente ejemplo vemos cómo remplazar el mes a una fecha determinada.

>>> fecha = datetime.date(2021, 7, 22)
>>> fecha = fecha.replace(month=8)
>>> print(fecha)
2021-08-22

Clase time

Un objeto time representa una hora en particular que no está ligada a ningún día específico.

Constructor y propiedades

Crear una objeto time es similar a lo que ya hemos visto con la clase date. Es decir, tenemos que especificar las horas, minutos, segundos y microsegundos que tiene nuestra hora. Si no especificamos alguno de estos parámetros se asume que su valor es 0. Además, hemos de tener en cuenta que las horas son en formato 24 horas. De este modo, para crear un objeto time que represente las nueve y cuarto de la noche lo haríamos así:

>>> hora = datetime.time(21, 15)

Si queremos acceder individualmente a los parámetros de un objeto time, podemos hacer referencia a cada uno de ellos por su nombre en inglés tal y como se muestra a continuación. Siguiendo con la explicación anterior, vemos como a los segundos y los microsegundos se les ha asignado valor 0 ya que en nuestro ejemplo no les hemos especificado un valor.

>>> hora.hour
21
>>> hora.minute
15
>>> hora.second
0
>>> hora.microsecond
0

Además, como hemos visto que sucede con date, los valores que especificamos en el constructor tienen que ser válidos. De este modo, la hora tiene que estar comprendida entre 0 y 23, los minutos entre 0 y 59, etc.

Métodos útiles

Algunos de los métodos más comunes que se usan con time son los siguientes.

• time.isoformat(): retorna un string que representa la hora en formato ISO 8601.

>>> hora = datetime.time(21, 15)
>>> hora.isoformat()
'21:15:00'

• time.replace(): remplaza las horas, minutos, segundos o microsegundos según especifiquemos con los nombres de estos cuatro parámetros en inglés. En el siguiente ejemplo se muestra como cambiar los minutos a una objeto time.

>>> hora = datetime.time(21, 15)
>>> hora = hora.replace(minute=30)
>>> print(hora)
21:30:00

Añadir que para obtener la hora actual no podemos utilizar la clase time, en lugar de ello tenemos que usar métodos now() y time() de la clase datetime, la cual vamos ver a continuación.

Clase datetime

La clase datetime combina la información de las dos clases anteriores, es decir, representa una fecha del calendario Gregoriano con una hora asociada. Notar que esta clase tiene el mismo nombre que su módulo, así que para referenciarla con un nombre más corto podemos importarla de la siguiente forma:

from datetime import datetime

Constructor y propiedades

Instanciar un objeto datetime es similar a instanciar objetos date y time, es decir tenemos que especificar los valores de mayor a menor unidad de tiempo: año, mes, día, etc. En el siguiente ejemplo se muestra cómo crear un objeto datetime que representa el 22 de julio de 2021 a las nueve y cuarto de la noche.

>>> marca_temporal = datetime(2021, 7, 22, 21, 15)

Asimismo, podemos acceder a los atributos de un objeto datetime referenciando su nombre en inglés.

>>> marca_temporal.year
2021
>>> marca_temporal.hour
21

Métodos útiles

Los métodos comúnmente usados de la clase datetime son los siguientes.

• datetime.now(): para obtener la fecha y hora actuales.

>>> marca_temporal = datetime.now()
>>> print(marca_temporal)
2021-07-22 21:15:45.775099

• datetime.date(): obtener la fecha del objeto datetime.

>>> marca_temporal.date()
datetime.date(2021, 7, 22)

• datetime.time(): obtener la hora del objeto datetime. Con este método y el método now() podemos obtener la hora actual.

>>> marca_temporal.time()
datetime.time(21, 15, 45, 775099)

• datetime.replace(): es el método homónimo a los vistos en las clases date y time, cuya función es sustituir valores en un objeto datetime. Para referenciar a los valores que deseamos cambiar hemos de utilizar su nombre en inglés.

>>> marca_temporal = datetime(2021, 7, 22, 21, 15)
>>> marca_temporal = marca_temporal.replace(month=8, minute=30)
>>> marca_temporal
datetime.datetime(2021, 8, 22, 21, 30)

Calcular la diferencia entre dos fechas/horas

La diferencia entre dos fechas/horas tenemos que calcularla entre objetos del mismo tipo. Es decir, entre dos objetos date, time o datetime. En el siguiente ejemplo vamos a ver cómo obtener la diferencia entre objetos datetime, pero los mismos conceptos son aplicables a las otras dos clases de la librería datetime.

Para ver la diferencia de tiempo entre dos objetos datetime, simplemente hay que instanciarlos y restarlos directamente como se muestra a continuación:

>>> from datetime import datetime
>>> marca_temporal1 = datetime(2021, 7, 22, 21, 15)
>>> marca_temporal2 = datetime(2022, 1, 1)
>>> diferencia = marca_temporal2 - marca_temporal1
>>> diferencia
datetime.timedelta(days=162, seconds=9900)

En el ejemplo anterior vemos que al restar ambas marcas temporales obtenemos como resultado un objeto cuya clase es timedelta. Esta clase representa duraciones de tiempo, es decir la diferencia entre dos fechas o horas. Además, guarda la información de la duración temporal usando días, segundos y microsegundos. Podemos acceder directamente a estos valores del mismo modo que en el resto de clases de la librería, o alternativamente podemos usar el método total_seconds() para saber cuantos segundos comprende esa diferencia de tiempo que acabamos de calcular.

>>> diferencia.total_seconds()
14006700.0

Formatear fechas y horas

En esta sección vamos a ver dos métodos especiales de las clases date, time y datetime. Uno para representarlos en una cadena de caracteres (o string) formateado a nuestro gusto, y otro para crear instancias de estos objetos a partir de un string.

Método .strftime()

La fecha se representa de forma distinta en diferentes países. Por ejemplo en Estados Unidos se usa el formato mes/día/año, mientras que en Europa el formato utilizado es día/mes/año. Lo mismo sucede con las horas, en algunos lugares se usa el formato de 24h y en otros prefieren el formato de 12h. Para ello tenemos el método strftime(), el cual retorna un string con la fecha o hora representada en un formato definido por nosotros mismos.

El siguiente código Python muestra cómo formatear un objeto datetime con el método strftime() a partir de un string que representa nuestro formato deseado. Si quieres saber cómo crear ese string a medida, al final del artículo he añadido una tabla con los códigos que podemos utilizar. Señalar también que estos mismos conceptos son aplicables a los objetos date y time.

>>> x = datetime(2021, 7, 22, 21, 15)
>>> x = x.strftime("%A, %d of %B %Y at %I:%M %p")
>>> print(x)
Thursday, 22 of July 2021 at 09:15 PM

Por defecto, los resultados que obtenemos con el método strftime() son en inglés. Si queremos mostrar los resultados en español tenemos que especificarlo con la librería locale. El siguiente ejemplo muestra cómo hacerlo.

>>> import locale
>>> locale.setlocale(locale.LC_TIME, "es_ES")
'es_ES'

Una vez completado el paso anterior los resultados ya se muestran en español.

>>> x = datetime(2021, 7, 22, 21, 15)
>>> x = x.strftime("%A, %d de %B de %Y a las %I:%M %p")
>>> print(x)
jueves, 22 de julio de 2021 a las 09:15

Método .strptime()

Este método hace justo lo contrario que el método strftime(). Es decir, crea un objeto de tipo date, time o datetime a partir de dos strings: uno que representa los valores de fecha y/o tiempo que va a tener el objeto, y otro que especifica el formato del anterior.

>>> x = datetime.strptime("22/07/2021, 21:15", "%d/%m/%Y, %H:%M")
>>> x
datetime.datetime(2021, 7, 22, 21, 15)

Tabla de códigos de formato

A continuación te dejo un tabla con los distintos códigos que podemos utilizar para formatear el tiempo con los métodos strftime() y strptime().