Entendendo o Módulo Datetime do Python
Aprenda a trabalhar com datas e horas em Python usando o módulo datetime: date, time, datetime, timedelta, strftime, strptime e fusos horários.
Python não possui um tipo de dado nativo dedicado para datas. Em vez disso, o módulo datetime da biblioteca padrão oferece um conjunto completo de ferramentas para criar, manipular, formatar e analisar datas e horas. Este capítulo cobre todas as classes principais — date, time, datetime, timedelta e timezone — e apresenta padrões práticos que você usará com frequência.
Importando o Módulo
O módulo datetime faz parte da biblioteca padrão e não requer instalação. Você pode importá-lo de duas formas comuns:
# Import the module and qualify every name
import datetime
today = datetime.date.today()
# Import specific classes directly
from datetime import date, time, datetime, timedelta, timezone
today = date.today()O estilo from datetime import ... é mais curto na prática e é usado ao longo deste capítulo.
A Classe date
date representa uma data do calendário (ano, mês, dia) sem componente de horário.
Criando Objetos date
Acessando Atributos de date
Ao ter um objeto date, você pode ler seu ano, mês e dia como atributos inteiros, e verificar em qual dia da semana ele cai:
from datetime import date
d = date(2024, 6, 15)
print(d.year) # 2024
print(d.month) # 6
print(d.day) # 15
# weekday(): Monday = 0, Sunday = 6
print(d.weekday()) # 5 (Saturday)
# isoweekday(): Monday = 1, Sunday = 7
print(d.isoweekday()) # 6 (Saturday)A Classe time
time representa um horário do dia (hora, minuto, segundo, microssegundo) independente de qualquer data específica.
from datetime import time
# time(hour, minute, second) — all arguments optional, default to 0
t = time(14, 30, 0)
print(t) # 14:30:00
print(t.hour) # 14
print(t.minute) # 30
print(t.second) # 0A classe time é mais útil quando você precisa armazenar ou comparar horários sem se preocupar com a data, por exemplo, "me lembre às 09:00 todos os dias."
A Classe datetime
datetime é a classe mais usada. Ela combina uma data completa com um horário em um único objeto e é o que você utilizará na maioria dos programas reais.
Obtendo a Data e Hora Atuais
from datetime import datetime
# Local system time (naive — no time zone)
now = datetime.now()
print(now) # e.g. 2024-06-15 14:30:45.123456
# UTC time
utc_now = datetime.utcnow()
print(utc_now) # e.g. 2024-06-15 18:30:45.123456Criando Objetos datetime
from datetime import datetime, date, time
# Constructor: datetime(year, month, day, hour=0, minute=0, second=0)
dt = datetime(2024, 6, 15, 14, 30, 45)
print(dt) # 2024-06-15 14:30:45
# From an ISO 8601 string
dt2 = datetime.fromisoformat("2024-06-15T14:30:45")
print(dt2) # 2024-06-15 14:30:45
# Combine a date and a time object
combined = datetime.combine(date(2024, 6, 15), time(14, 30, 0))
print(combined) # 2024-06-15 14:30:00Acessando Atributos de datetime
datetime expõe todos os atributos de date e time:
from datetime import datetime
dt = datetime(2024, 6, 15, 14, 30, 45)
print(dt.year) # 2024
print(dt.month) # 6
print(dt.day) # 15
print(dt.hour) # 14
print(dt.minute) # 30
print(dt.second) # 45
# Extract just the date or time part
print(dt.date()) # 2024-06-15
print(dt.time()) # 14:30:45A Classe timedelta
timedelta representa uma duração — a diferença entre dois momentos no tempo. Você a utiliza para adicionar ou subtrair intervalos de tempo de objetos date e datetime.
Criando e Usando timedelta
from datetime import date, timedelta
today = date(2024, 6, 15)
# Add 30 days
future = today + timedelta(days=30)
print(future) # 2024-07-15
# Subtract 7 days
last_week = today - timedelta(weeks=1)
print(last_week) # 2024-06-08
# timedelta can express days, seconds, and microseconds
# Convenience arguments: days, seconds, microseconds, milliseconds, minutes, hours, weeks
delta = timedelta(hours=2, minutes=30)
print(delta) # 2:30:00Calculando a Diferença Entre Duas Datas
Subtrair um date ou datetime de outro retorna um timedelta:
from datetime import date
start = date(2024, 1, 1)
end = date(2024, 6, 15)
diff = end - start
print(diff) # 166 days, 0:00:00
print(diff.days) # 166Esta é a forma padrão de calcular quantos dias há entre duas datas. Use .total_seconds() em um timedelta se precisar do intervalo em segundos.
Formatando Datas e Horas (strftime)
strftime ("string format time") converte um objeto date ou datetime em uma string legível por humanos. Você passa uma string de formato que contém diretivas iniciadas com %.
from datetime import datetime
dt = datetime(2024, 6, 15, 14, 30, 45)
print(dt.strftime("%Y-%m-%d")) # 2024-06-15
print(dt.strftime("%d/%m/%Y")) # 15/06/2024
print(dt.strftime("%A, %B %d, %Y")) # Saturday, June 15, 2024
print(dt.strftime("%I:%M %p")) # 02:30 PM
print(dt.strftime("%Y-%m-%d %H:%M:%S")) # 2024-06-15 14:30:45Diretivas Comuns do strftime
| Diretiva | Significado | Exemplo |
|---|---|---|
%Y | Ano com 4 dígitos | 2024 |
%y | Ano com 2 dígitos | 24 |
%m | Mês como número com zero à esquerda | 06 |
%B | Nome completo do mês | June |
%b | Nome abreviado do mês | Jun |
%d | Dia do mês com zero à esquerda | 15 |
%A | Nome completo do dia da semana | Saturday |
%a | Nome abreviado do dia da semana | Sat |
%H | Hora (relógio de 24 horas) | 14 |
%I | Hora (relógio de 12 horas) | 02 |
%M | Minuto | 30 |
%S | Segundo | 45 |
%p | AM ou PM | PM |
%j | Dia do ano | 167 |
%W | Número da semana no ano | 24 |
Analisando Datas e Horas (strptime)
strptime ("string parse time") é o inverso de strftime: converte uma string em um objeto datetime. Você deve fornecer uma string de formato que corresponda à entrada.
Um erro comum: strptime sempre retorna um datetime, mesmo quando a string contém apenas uma data. Chame .date() no resultado se precisar de um objeto date simples.
Formato ISO 8601
O padrão ISO 8601 (YYYY-MM-DDTHH:MM:SS) é a forma mais portável de trocar valores de data e hora. Python possui auxiliares nativos para ele:
from datetime import datetime
dt = datetime(2024, 6, 15, 14, 30, 45)
# Produce ISO 8601 string
print(dt.isoformat()) # 2024-06-15T14:30:45
# Parse ISO 8601 string (Python 3.7+)
dt2 = datetime.fromisoformat("2024-06-15T14:30:45")
print(dt2) # 2024-06-15 14:30:45Trabalhando com Timestamps
Um timestamp Unix é o número de segundos decorridos desde 1 de janeiro de 1970 00:00:00 UTC. Python pode converter entre timestamps e objetos datetime:
Fusos Horários
Por padrão, datetime.now() retorna um datetime ingênuo (naive) — sem informações de fuso horário. Anexar um objeto tzinfo o torna ciente (aware). Datetimes cientes são essenciais quando seu programa lida com usuários em múltiplos fusos horários ou armazena timestamps em um banco de dados.
Usando o timezone Integrado
datetime.timezone fornece timezone.utc e permite criar fusos com offset fixo:
from datetime import datetime, timezone, timedelta
# Create an aware UTC datetime
utc_dt = datetime(2024, 6, 15, 14, 30, 45, tzinfo=timezone.utc)
print(utc_dt) # 2024-06-15 14:30:45+00:00
# Create a fixed +5:30 (India Standard Time) offset
ist_offset = timezone(timedelta(hours=5, minutes=30))
ist_dt = utc_dt.astimezone(ist_offset)
print(ist_dt) # 2024-06-15 20:00:45+05:30Usando zoneinfo (Python 3.9+)
Para fusos horários IANA reais, como America/New_York ou Asia/Tokyo, use o módulo integrado zoneinfo (Python 3.9+). Ele lida automaticamente com o horário de verão.
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
# UTC aware datetime
utc_dt = datetime(2024, 6, 15, 14, 30, 45, tzinfo=timezone.utc)
# Convert to Eastern Time (handles DST automatically)
eastern = ZoneInfo("America/New_York")
eastern_dt = utc_dt.astimezone(eastern)
print(eastern_dt) # 2024-06-15 10:30:45-04:00
# Convert to Tokyo time
tokyo = ZoneInfo("Asia/Tokyo")
tokyo_dt = utc_dt.astimezone(tokyo)
print(tokyo_dt) # 2024-06-15 23:30:45+09:00No Python 3.8 e anteriores, instale a biblioteca de terceiros pytz para suporte a fusos IANA.
Substituindo Componentes
replace() retorna um novo objeto com campos específicos alterados. O original nunca é modificado.
from datetime import datetime
dt = datetime(2024, 6, 15, 14, 30, 45)
# Change only the year
dt2 = dt.replace(year=2025)
print(dt2) # 2025-06-15 14:30:45
# Change hour and minute
dt3 = dt.replace(hour=9, minute=0, second=0)
print(dt3) # 2024-06-15 09:00:00Comparando Datas e Horas
Objetos date e datetime suportam todos os operadores de comparação padrão:
from datetime import date
d1 = date(2024, 1, 1)
d2 = date(2024, 6, 15)
print(d1 < d2) # True
print(d1 == d2) # False
# Find the earliest date
earliest = min(d1, d2)
print(earliest) # 2024-01-01Compare apenas datetimes cientes com cientes e ingênuos com ingênuos — misturá-los gera um TypeError.
Juntando Tudo
Aqui está um exemplo prático que combina vários conceitos: calcula quantos dias restam até um prazo futuro e formata ambas as datas para exibição.
from datetime import date
deadline = date(2024, 12, 31)
today = date(2024, 6, 15)
days_left = (deadline - today).days
print(f"Today: {today.strftime('%B %d, %Y')}") # June 15, 2024
print(f"Deadline: {deadline.strftime('%B %d, %Y')}") # December 31, 2024
print(f"Days remaining: {days_left}") # 199Referência Rápida
| Tarefa | Código |
|---|---|
| Data de hoje | date.today() |
| Data e hora atuais | datetime.now() |
| Data específica | date(2024, 6, 15) |
| Data a partir de string | datetime.strptime(s, fmt) |
| Data para string | dt.strftime(fmt) |
| Formato ISO | dt.isoformat() / datetime.fromisoformat(s) |
| Adicionar/subtrair dias | d + timedelta(days=N) |
| Dias entre datas | (d2 - d1).days |
| Converter fuso horário | dt.astimezone(ZoneInfo("Zone/Name")) |