datetime — Manipulación de valores de fecha y hora

Propósito:El módulo datetime incluye funciones y clases para hacer análisis, formateo y aritmética de fecha y hora.

datetime contiene funciones y clases para trabajar con fechas y horas, por separado y en conjunto.

Horas

Los valores de tiempo se representan con la clase time. Una instancia time tiene atributos para hour, minute, second, y microsecond y también incluye información de zona horaria.

datetime_time.py
import datetime

t = datetime.time(1, 2, 3)
print(t)
print('hour       :', t.hour)
print('minute     :', t.minute)
print('second     :', t.second)
print('microsecond:', t.microsecond)
print('tzinfo     :', t.tzinfo)

Los argumentos para inicializar una instancia time son opcionales, pero es poco probable que el valor predeterminado de 0 sea correcto.

$ python3 datetime_time.py

01:02:03
hour       : 1
minute     : 2
second     : 3
microsecond: 0
tzinfo     : None

Una instancia time solo tiene valores de tiempo, y no una fecha asociada con el tiempo.

datetime_time_minmax.py
import datetime

print('Earliest  :', datetime.time.min)
print('Latest    :', datetime.time.max)
print('Resolution:', datetime.time.resolution)

Los atributos de clase min y max reflejan el rango válido de de horas en un solo día.

$ python3 datetime_time_minmax.py

Earliest  : 00:00:00
Latest    : 23:59:59.999999
Resolution: 0:00:00.000001

La resolución para time está limitada a micro segundos completos.

datetime_time_resolution.py
import datetime

for m in [1, 0, 0.1, 0.6]:
    try:
        print('{:02.1f} :'.format(m),
              datetime.time(0, 0, 0, microsecond=m))
    except TypeError as err:
        print('ERROR:', err)

Los valores de coma flotante para microsegundos provocan un TypeError.

$ python3 datetime_time_resolution.py

1.0 : 00:00:00.000001
0.0 : 00:00:00
ERROR: integer argument expected, got float
ERROR: integer argument expected, got float

Fechas

Los valores de la fecha del calendario se representan con la clase date. Las instancias tienen atributos para year, month, y day. Es fácil crear una fecha que represente la fecha actual usando el método de clase today().

datetime_date.py
import datetime

today = datetime.date.today()
print(today)
print('ctime  :', today.ctime())
tt = today.timetuple()
print('tuple  : tm_year  =', tt.tm_year)
print('         tm_mon   =', tt.tm_mon)
print('         tm_mday  =', tt.tm_mday)
print('         tm_hour  =', tt.tm_hour)
print('         tm_min   =', tt.tm_min)
print('         tm_sec   =', tt.tm_sec)
print('         tm_wday  =', tt.tm_wday)
print('         tm_yday  =', tt.tm_yday)
print('         tm_isdst =', tt.tm_isdst)
print('ordinal:', today.toordinal())
print('Year   :', today.year)
print('Mon    :', today.month)
print('Day    :', today.day)

Este ejemplo imprime la fecha actual en varios formatos:

$ python3 datetime_date.py

2017-07-30
ctime  : Sun Jul 30 00:00:00 2017
tuple  : tm_year  = 2017
         tm_mon   = 7
         tm_mday  = 30
         tm_hour  = 0
         tm_min   = 0
         tm_sec   = 0
         tm_wday  = 6
         tm_yday  = 211
         tm_isdst = -1
ordinal: 736540
Year   : 2017
Mon    : 7
Day    : 30

También hay métodos de clase para crear instancias de marcas de tiempo POSIX o números enteros que representan valores de fecha del calendario gregoriano, donde el 1 de enero del año 1 es 1 y cada día subsecuente incrementa el valor en 1.

datetime_date_fromordinal.py
import datetime
import time

o = 733114
print('o               :', o)
print('fromordinal(o)  :', datetime.date.fromordinal(o))

t = time.time()
print('t               :', t)
print('fromtimestamp(t):', datetime.date.fromtimestamp(t))

Este ejemplo ilustra los diferentes tipos de valores utilizados por fromordinal()` y fromtimestamp().

$ python3 datetime_date_fromordinal.py

o               : 733114
fromordinal(o)  : 2008-03-13
t               : 1501432275.190121
fromtimestamp(t): 2017-07-30

Al igual que con time, el rango de valores de fecha soportados puede ser determinado usando los atributos min y max.

datetime_date_minmax.py
import datetime

print('Earliest  :', datetime.date.min)
print('Latest    :', datetime.date.max)
print('Resolution:', datetime.date.resolution)

La resolución de las fechas es días enteros.

$ python3 datetime_date_minmax.py

Earliest  : 0001-01-01
Latest    : 9999-12-31
Resolution: 1 day, 0:00:00

Otra forma de crear nuevas instancias date usa el método replace() de una date existente.

datetime_date_replace.py
import datetime

d1 = datetime.date(2008, 3, 29)
print('d1:', d1.ctime())

d2 = d1.replace(year=2009)
print('d2:', d2.ctime())

Este ejemplo cambia el año, dejando el día y el mes sin modificar.

$ python3 datetime_date_replace.py

d1: Sat Mar 29 00:00:00 2008
d2: Sun Mar 29 00:00:00 2009

timedeltas

Fechas futuras y pasadas pueden calcularse usando aritmética básica en dos objetos datetime, o combinando datetime con un timedelta. Restar fechas produce un timedelta, y un timedelta se puede agregar o restar de una fecha para producir otra fecha. Los valores internos para un timedelta son almacenados en días, segundos y microsegundos.

datetime_timedelta.py
import datetime

print('microseconds:', datetime.timedelta(microseconds=1))
print('milliseconds:', datetime.timedelta(milliseconds=1))
print('seconds     :', datetime.timedelta(seconds=1))
print('minutes     :', datetime.timedelta(minutes=1))
print('hours       :', datetime.timedelta(hours=1))
print('days        :', datetime.timedelta(days=1))
print('weeks       :', datetime.timedelta(weeks=1))

Valores de nivel intermedio pasados al constructor se convierten en días, segundos y microsegundos.

$ python3 datetime_timedelta.py

microseconds: 0:00:00.000001
milliseconds: 0:00:00.001000
seconds     : 0:00:01
minutes     : 0:01:00
hours       : 1:00:00
days        : 1 day, 0:00:00
weeks       : 7 days, 0:00:00

La duración completa de un timedelta se puede recuperar como un número de segundos usando total_seconds().

datetime_timedelta_total_seconds.py
import datetime

for delta in [datetime.timedelta(microseconds=1),
              datetime.timedelta(milliseconds=1),
              datetime.timedelta(seconds=1),
              datetime.timedelta(minutes=1),
              datetime.timedelta(hours=1),
              datetime.timedelta(days=1),
              datetime.timedelta(weeks=1),
              ]:
    print('{:15} = {:8} seconds'.format(
        str(delta), delta.total_seconds())
    )

El valor de retorno es un número de coma flotante, para acomodar duraciones de sub-segundo.

$ python3 datetime_timedelta_total_seconds.py

0:00:00.000001  =    1e-06 seconds
0:00:00.001000  =    0.001 seconds
0:00:01         =      1.0 seconds
0:01:00         =     60.0 seconds
1:00:00         =   3600.0 seconds
1 day, 0:00:00  =  86400.0 seconds
7 days, 0:00:00 = 604800.0 seconds

Aritmética de Fecha

La matemática fecha usa los operadores aritméticos estándar.

datetime_date_math.py
import datetime

today = datetime.date.today()
print('Today    :', today)

one_day = datetime.timedelta(days=1)
print('One day  :', one_day)

yesterday = today - one_day
print('Yesterday:', yesterday)

tomorrow = today + one_day
print('Tomorrow :', tomorrow)

print()
print('tomorrow - yesterday:', tomorrow - yesterday)
print('yesterday - tomorrow:', yesterday - tomorrow)

Este ejemplo con objetos de fecha ilustra el uso de objetos timedelta para calcular nuevas fechas y restar instancias de fecha par producir timedeltas (incluido un valor delta negativo).

$ python3 datetime_date_math.py

Today    : 2017-07-30
One day  : 1 day, 0:00:00
Yesterday: 2017-07-29
Tomorrow : 2017-07-31

tomorrow - yesterday: 2 days, 0:00:00
yesterday - tomorrow: -2 days, 0:00:00

Un objeto timedelta también admite aritmética con enteros, números de coma flotante y otras instancias timedelta.

datetime_timedelta_math.py
import datetime

one_day = datetime.timedelta(days=1)
print('1 day    :', one_day)
print('5 days   :', one_day * 5)
print('1.5 days :', one_day * 1.5)
print('1/4 day  :', one_day / 4)

# assume an hour for lunch
work_day = datetime.timedelta(hours=7)
meeting_length = datetime.timedelta(hours=1)
print('meetings per day :', work_day / meeting_length)

En este ejemplo, se computan varios múltiplos de un solo día, con el timedelta resultante conteniendo el número apropiado de días u horas. El último ejemplo demuestra cómo calcular valores combinando dos objetos timedelta. En este caso, el resultado es un número de coma flotante.

$ python3 datetime_timedelta_math.py

1 day    : 1 day, 0:00:00
5 days   : 5 days, 0:00:00
1.5 days : 1 day, 12:00:00
1/4 day  : 6:00:00
meetings per day : 7.0

Comparando valores

Los valores de fecha y hora se pueden comparar utilizando los operador estándar de comparación para determinar cuál es anterior o posterior.

datetime_comparing.py
import datetime
import time

print('Times:')
t1 = datetime.time(12, 55, 0)
print('  t1:', t1)
t2 = datetime.time(13, 5, 0)
print('  t2:', t2)
print('  t1 < t2:', t1 < t2)

print()
print('Dates:')
d1 = datetime.date.today()
print('  d1:', d1)
d2 = datetime.date.today() + datetime.timedelta(days=1)
print('  d2:', d2)
print('  d1 > d2:', d1 > d2)

Todos los operadores de comparación son compatibles.

$ python3 datetime_comparing.py

Times:
  t1: 12:55:00
  t2: 13:05:00
  t1 < t2: True

Dates:
  d1: 2017-07-30
  d2: 2017-07-31
  d1 > d2: False

Combinando fechas y horas

Usa la clase datetime para mantener los valores que consisten en componentes fechas y componentes de tiempo. Al igual que con date, hay varios métodos de clase convenientes para crear instancias datetime de otros valores comunes.

datetime_datetime.py
import datetime

print('Now    :', datetime.datetime.now())
print('Today  :', datetime.datetime.today())
print('UTC Now:', datetime.datetime.utcnow())
print()

FIELDS = [
    'year', 'month', 'day',
    'hour', 'minute', 'second',
    'microsecond',
]

d = datetime.datetime.now()
for attr in FIELDS:
    print('{:15}: {}'.format(attr, getattr(d, attr)))

Como era de esperar, la instancia datetime tiene todos los atributos de un objeto date y un objeto time.

$ python3 datetime_datetime.py

Now    : 2017-07-30 12:31:15.519675
Today  : 2017-07-30 12:31:15.519706
UTC Now: 2017-07-30 16:31:15.519715

year           : 2017
month          : 7
day            : 30
hour           : 12
minute         : 31
second         : 15
microsecond    : 519852

Al igual que con date, datetime proporciona métodos de clase conveniente para crear nuevas instancias. También incluye fromordinal() y fromtimestamp().

datetime_datetime_combine.py
import datetime

t = datetime.time(1, 2, 3)
print('t :', t)

d = datetime.date.today()
print('d :', d)

dt = datetime.datetime.combine(d, t)
print('dt:', dt)

combine() crea instancias datetime de una instancia date y una instancia time.

$ python3 datetime_datetime_combine.py

t : 01:02:03
d : 2017-07-30
dt: 2017-07-30 01:02:03

Formateando y analizando

La representación de cadena pre determinada de un objeto datetime usa el formato ISO-8601 (YYYY-MM-DDTHH:MM:SS.mmmmmm). Se puede generar formatos alternativosse usando strftime().

datetime_datetime_strptime.py
import datetime

format = "%a %b %d %H:%M:%S %Y"

today = datetime.datetime.today()
print('ISO     :', today)

s = today.strftime(format)
print('strftime:', s)

d = datetime.datetime.strptime(s, format)
print('strptime:', d.strftime(format))

Usa datetime.strptime() para convertir cadenas formateadas a instancias de datetime.

$ python3 datetime_datetime_strptime.py

ISO     : 2017-07-30 12:31:15.601198
strftime: Sun Jul 30 12:31:15 2017
strptime: Sun Jul 30 12:31:15 2017

Los mismos códigos de formateo se pueden usar con el mini-lenguaje de formateo de cadenas de Python colocándolos después de la : en la especificación de campo de la cadena de formato.

datetime_format.py
import datetime

today = datetime.datetime.today()
print('ISO     :', today)
print('format(): {:%a %b %d %H:%M:%S %Y}'.format(today))

Cada código de formato de fecha y hora debe tener el prefijo ``% `` y los dos puntos siguientes se tratan como caracteres literales para incluir en la salida.

$ python3 datetime_format.py

ISO     : 2017-07-30 12:31:15.666149
format(): Sun Jul 30 12:31:15 2017

La siguiente tabla muestra todos los códigos de formato para las 5:00PM del 13 de enero de 2016 en la zona horaria de US/Eastern.

strptime/strftime códigos de formato
Símbolo Significado Ejemplo
%a Día de la semana abreviado 'Wed'
%A Nombre completo del día de la semana 'Wednesday'
%w Número del día de la semana – 0 (Domingo) al 6 (Sábado) '3'
%d Día del mes (rellenado con cero) '13'
%b Nombre del mes abreviado 'Jan'
%B Nombre completo del mes 'January'
%m Mes del año '01'
%y Año sin siglo '16'
%Y Año con siglo '2016'
%H Hora del reloj de 24 horas '17'
%I Hora del reloj de 12 horas '05'
%p AM/PM 'PM'
%M Minutos '00'
%S Segundos '00'
%f Microsegundos '000000'
%z Desplazamiento UTC para objetos con reconocimiento de zona horaria '-0500'
%Z Nombre de la zona horaria 'EST'
%j Día del año '013'
%W Semana del año '02'
%c Representación de fecha y hora para el lugar presente 'Wed Jan 13 17:00:00 2016'
%x Representación de fecha para el lugar presente '01/13/16'
%X Representación de hora para el lugar presente '17:00:00'
%% Un caractér % literal '%'

Zonas horarias

Dentro de datetime, las zonas horarias están representadas por subclases de tzinfo. Como tzinfo es una clase base abstracta, aplicaciones necesitan definir una subclase y proporcionar implementaciones para algunos métodos para hacerla útil.

datetime incluye una implementación algo ingenua en la clase timezone que usa un desplazamiento fijo de UTC, y lo hace no admite diferentes valores de desplazamiento en diferentes días del año, como dónde se aplica el horario de verano, o donde el desplazamiento de UTC ha cambiado con el tiempo.

datetime_timezone.py
import datetime

min6 = datetime.timezone(datetime.timedelta(hours=-6))
plus6 = datetime.timezone(datetime.timedelta(hours=6))
d = datetime.datetime.now(min6)

print(min6, ':', d)
print(datetime.timezone.utc, ':',
      d.astimezone(datetime.timezone.utc))
print(plus6, ':', d.astimezone(plus6))

# convert to the current system timezone
d_system = d.astimezone()
print(d_system.tzinfo, '      :', d_system)

Para convertir un valor de fecha y hora de una zona horaria a otra, usa astimezone(). En el ejemplo anterior, dos zonas horarias separadas 6 horas a cada lado de UTC se muestran, y la instancia utc de datetime.timezone también se usa como referencia. La última línea del resultado muestra el valor en la zona horaria del sistema, adquirida por invocando astimezone() sin argumento.

$ python3 datetime_timezone.py

UTC-06:00 : 2017-07-30 10:31:15.734286-06:00
UTC+00:00 : 2017-07-30 16:31:15.734286+00:00
UTC+06:00 : 2017-07-30 22:31:15.734286+06:00
EDT       : 2017-07-30 12:31:15.734286-04:00

Nota

El módulo de terceros pytz es una mejor implementación para las zonas horarias. Es compatible con zonas horarias con nombre, y la base de datos de desplazamiento se mantiene actualizada a medida que los cambios se realizan por los cuerpos políticos en todo el mundo.

Ver también