Python datetime: como trabalhar com datas e horários em Python

Trabalhar com datas e horários parece simples até você lidar com formatos, fusos horários, horário de verão ou timestamps vindos de vários sistemas — e aí não dá mais para guardar tempo como strings ou inteiros crus. O módulo datetime do Python existe para ajudar você a orquestrar todas essas partes de forma previsível.

Este guia apresenta as classes centrais, como criar e trabalhar com objetos datetime, como fazer contas, formatar e fazer parsing de valores, lidar com fusos horários e mais. Cada seção constrói sobre a anterior, para você evoluir de operações básicas até padrões mais avançados.

Classes principais do módulo datetime do Python

Antes de algo específico, vale entender como o Python modela datas e horários conceitualmente. O módulo datetime usa um conjunto pequeno de classes, cada uma focada em uma parte do problema. Saber o papel de cada classe deixa o restante do fluxo muito mais simples.

date

Quando você só precisa de uma data de calendário sem se preocupar com hora do dia ou fuso horário, a classe date é a escolha certa. Ela representa ano, mês e dia com atributos familiares.

Aqui estão os atributos:

• year

• month

• day

E os métodos:

• today()

• fromisoformat()

• replace()

• isoformat()

• weekday()

• isoweekday()

from datetime import date
d = date(2025, 3, 1)
print(d)

Esse código cria uma data de calendário simples. Se você informar uma combinação inválida (como February 30), o Python lança um ValueError.

time

Algumas tarefas só se importam com o horário do dia, por exemplo, um lembrete que roda às 14:30. A classe time é útil porque armazena horas, minutos, segundos e (se necessário), microssegundos ou dados de fuso.

Os atributos são: hour, minute, second, microsecond, tzinfo

Os métodos são: replace(), isoformat()

from datetime import time
t = time(14, 30, 15)
print(t)

Isto cria um horário de relógio sem uma data associada. Valores inválidos (como hour=27) vão gerar erro.

datetime

A maioria dos cenários reais combina data e hora, e é aí que datetime entra. É a classe mais versátil do módulo e a que você mais vai usar para registro, processamento e coordenação de eventos.

Os atributos são (além de todos os anteriores): tzinfo

E os métodos são now(), utcnow(), fromisoformat(), strptime(), strftime(), astimezone(). Ela também dá suporte a aritmética com timedelta, que vou detalhar a seguir.

from datetime import datetime
dt = datetime(2025, 3, 1, 14, 30)
print(dt)

Isso produz um timestamp completo, com data e hora.

timedelta

Sempre que você precisa medir tempo decorrido ou deslocar um timestamp para frente ou para trás, timedelta é a escolha certa. Ele representa uma duração, não um momento específico.

Os atributos são: days, seconds, microseconds. É muito usado para offsets, diferenças de tempo e lógica de agendamento.

from datetime import timedelta
delta = timedelta(days=7, hours=3)
print(delta)

Isso representa uma duração de comprimento fixo. Fica especialmente útil ao somar ou subtrair de um datetime.

tzinfo

tzinfo define a interface de fusos horários do Python. Você não cria instâncias diretamente, mas o sistema de datetime as usa sempre que você anexa ou converte fusos.

timezone

timezone é uma implementação de tzinfo para deslocamentos UTC fixos como UTC ou UTC+1. É útil para casos simples em que regras de horário de verão não importam.

Criando e acessando objetos datetime no Python

Depois de conhecer as classes, o próximo passo é aprender a criar instâncias. O Python oferece várias abordagens dependendo da origem dos dados: entrada manual, hora do sistema, timestamps ou texto.

Usando construtores de classe

Construtores dão controle total sobre os valores criados. Muitas vezes é a forma mais explícita e menos sujeita a erro de construir objetos de data, hora ou datetime.

from datetime import date
d = date(2025, 3, 1)
print(d)

Isto cria uma data de calendário diretamente. Valores inválidos geram erro na hora, ajudando a pegar enganos cedo.

from datetime import time
t = time(14, 30, 15)
print(t)

Isto produz um valor de hora do dia. Use quando você não precisa da data associada.

from datetime import datetime
dt = datetime(2025, 3, 1, 14, 30)
print(dt)

Isto cria um timestamp completo. Adicionar um argumento tzinfo o torna ciente de fuso horário.

Criando a partir de timestamps

Timestamps Unix aparecem em logs, APIs e sistemas operacionais. O Python os converte facilmente para objetos datetime legíveis.

datetime.fromtimestamp(1700000000)
datetime.utcfromtimestamp(1700000000)

O primeiro interpreta o timestamp no horário local; o segundo interpreta em UTC.

Métodos de classe para valores atuais

Quando você precisa do horário ou data atuais, o Python oferece atalhos simples. Eles são essenciais para logging, rastreamento de eventos e pipelines em tempo real.

from datetime import datetime, date, timezone
print(date.today())
print(datetime.now())
print(datetime.now(tz=timezone.utc))  # Python 3.12+ preferido

Eles retornam o horário do sistema atual no fuso local ou em UTC, conforme a sua necessidade.

datetime.fromtimestamp(1700000000)
datetime.utcfromtimestamp(1700000000)

Esses convertem timestamps de época em objetos datetime. São muito comuns ao processar valores de APIs ou bancos de dados.

Fazendo parsing a partir de strings

Conjuntos de dados do mundo real costumam armazenar timestamps como texto. O Python oferece ferramentas confiáveis para converter essas strings em valores estruturados.

strptime()
from datetime import datetime
dt = datetime.strptime("2025-03-01 14:30", "%Y-%m-%d %H:%M")
print(dt)

strptime() faz o parsing de uma string usando um padrão de formato. Se a string não bater exatamente, o Python lança ValueError.

from datetime import datetime
dt = datetime.strptime("not-a-date", "%Y-%m-%d")

Isto falharia porque a entrada não corresponde ao padrão esperado.

fromisoformat()
datetime.fromisoformat("2025-03-01T14:30:00")

Strings ISO 8601 são fáceis de interpretar porque a estrutura é padronizada. É geralmente a maneira mais simples de carregar timestamps de APIs ou pipelines modernos.

Fazendo aritmética com datas

Depois de criar timestamps, o passo seguinte é trabalhar com eles. Você pode calcular durações, deslocar datas ou comparar intervalos.

Timedelta para cálculos temporais

timedelta modela períodos de duração fixa como “5 horas” ou “2 semanas”. Esses períodos são úteis para agendamentos, logging e contagens regressivas simples.

from datetime import datetime, timedelta
dt = datetime(2025, 3, 1, 14, 30)
new_dt = dt + timedelta(days=5)
print(new_dt)

Este exemplo desloca o timestamp em cinco dias para frente.

start = datetime(2025, 3, 1, 9, 0)
end = datetime(2025, 3, 1, 14, 30)
duration = end - start
print(duration.total_seconds())

Aqui, subtrair dois datetimes gera um timedelta, que você pode converter em segundos, dias ou horas.

Duração fixa vs. aritmética ciente do calendário

Nem todas as unidades de tempo são iguais. Meses variam em duração, anos podem ter dia extra e o fim do mês pode ser imprevisível. Para esses cenários, timedelta não basta.

dateutil.relativedelta lida com aritmética “ciente do calendário”:

from dateutil.relativedelta import relativedelta
from datetime import date
d = date(2025, 1, 31)
print(d + relativedelta(months=1))

Isto lida corretamente com o caso do inexistente “31 de fevereiro”, ajustando a data de forma apropriada.

Formatando e fazendo parsing de datas

Formatação de datetime está em todo lugar: APIs exigem formatos específicos, usuários preferem textos legíveis e logs dependem de strings consistentes de timestamp. O Python suporta tanto formatação flexível quanto representações padronizadas.

Formatação de strings com strftime

strftime() permite transformar objetos datetime em strings formatadas usando códigos predefinidos.

from datetime import datetime
dt = datetime(2025, 3, 1, 14, 30)
print(dt.strftime("%A, %B %d, %Y at %H:%M"))

Isso imprime uma string legível com o dia da semana e o nome completo do mês.

dt.strftime("%Y-%m-%dT%H:%M:%S")

Isso produz uma string no estilo ISO adequada para armazenamento de dados ou APIs.

Parsing de strings com strptime

from datetime import datetime
dt = datetime.strptime("2025-03-01 14:30", "%Y-%m-%d %H:%M")
print(dt)

Isso converte texto em um objeto datetime. Qualquer divergência entre string e padrão gera erro.

Trabalhando com ISO 8601 e RFC 3339

ISO 8601 resolve a ambiguidade de muitos formatos regionais de data. O Python oferece suporte nativo:

from datetime import datetime
dt = datetime.fromisoformat("2025-03-01T14:30:00")
print(dt.isoformat())

Este é o formato mais seguro para troca de dados entre sistemas, APIs ou bancos de dados.

Lidando com fusos horários

Fusos horários trazem alguns dos desafios mais difíceis em programação temporal. O Python ajuda diferenciando entre objetos datetime ingênuos (naive) e cientes de fuso (aware) e oferecendo ferramentas para lidar com zonas reais.

Objetos datetime ingênuos vs. cientes de fuso

Um datetime ingênuo não tem fuso horário:

from datetime import datetime
naive_dt = datetime(2025, 3, 1, 14, 30)
print(naive_dt.tzinfo)  # None

Um datetime ciente inclui um deslocamento de fuso:

from datetime import timezone, timedelta
aware_dt = naive_dt.replace(tzinfo=timezone(timedelta(hours=1)))
print(aware_dt)

Misturar valores ingênuos e cientes em comparações ou aritmética geralmente causa erros.

Usando o módulo zoneinfo

O módulo zoneinfo do Python dá acesso aos fusos IANA do mundo real:

from zoneinfo import ZoneInfo
from datetime import datetime
dt = datetime(2025, 3, 1, 14, 30, tzinfo=ZoneInfo("Europe/Paris"))
print(dt)

Converter fuso horário é simples:

dt.astimezone(ZoneInfo("America/New_York"))

Isso expressa o mesmo momento em um fuso local diferente.

Convertendo entre fusos horários

Você pode converter qualquer timestamp ciente de fuso para outra zona usando astimezone():

from zoneinfo import ZoneInfo
dt_ny = dt.astimezone(ZoneInfo("America/New_York"))
print(dt_ny)

Uma boa prática comum é armazenar timestamps em UTC e converter apenas quando necessário para exibição.

Comparando e filtrando datas

Comparações aparecem em quase todo fluxo. Pense em ordenar logs, filtrar eventos ou determinar se algo ocorreu antes ou depois de um limite.

from datetime import datetime
a = datetime(2025, 3, 1, 12, 0)
b = datetime(2025, 3, 1, 15, 0)
print(a < b)  # True

Comparações cientes de fuso consideram deslocamentos:

from datetime import datetime
from zoneinfo import ZoneInfo
dt1 = datetime(2025, 3, 1, 12, 0, tzinfo=ZoneInfo("Europe/London"))
dt2 = datetime(2025, 3, 1, 7, 0, tzinfo=ZoneInfo("America/New_York"))
print(dt1 == dt2)  # True — mesmo momento no tempo

Filtrar coleções funciona naturalmente:

dates = [
    datetime(2025, 3, 1, 10),
    datetime(2025, 2, 20, 9),
    datetime(2025, 3, 1, 8)
]
cutoff = datetime(2025, 3, 1)
filtered = [d for d in dates if d >= cutoff]
print(filtered)

Normalizar para UTC ajuda bastante ao trabalhar entre zonas.

Casos de uso mais avançados

Datetime aparece em muitos fluxos além do básico de parsing e aritmética. Aqui vão alguns padrões que você vai ver com frequência.

Timestamps Unix

Timestamps Unix medem os segundos desde 1º de janeiro de 1970 (UTC). São amplamente usados em programação de sistemas e APIs.

from datetime import datetime
dt = datetime.fromtimestamp(1700000000)
print(dt)

Milissegundos e microssegundos exigem escalonamento:

ts_ms = 1700000000000
dt_ms = datetime.fromtimestamp(ts_ms / 1000)

ts_us = 1700000000000000
dt_us = datetime.fromtimestamp(ts_us / 1_000_000)

Agendamento e timers

Bibliotecas como schedule dependem de valores datetime para decidir quando tarefas devem rodar. Seja para disparar funções a cada poucos segundos ou agendar um evento único mais tarde no dia, datetime é a base dessas comparações.

Padrões de análise de dados

Atributos de datetime são frequentemente extraídos para agrupamento e análise temporal:

dt = datetime(2025, 3, 1, 14, 30)
print(dt.year)
print(dt.isocalendar())

No pandas, o reamostramento por período é extremamente comum:

import pandas as pd
df = pd.DataFrame({
    "value": [10, 12, 15],
    "timestamp": pd.to_datetime([
        "2025-03-01",
        "2025-03-02",
        "2025-03-08"
    ])
}).set_index("timestamp")

print(df.resample("W").sum())

Conclusão

Para saber mais sobre datetime, assista a este vídeo do nosso curso Working with Dates and Times in Python de Max Shrom e Data Types for Data Science in Python de Jason Myers. 

Você também pode gostar do nosso tutorial Converting Strings to Dates as datetime Objects se precisar de uma ajuda extra ao converter strings.