pendulum / arrow

pendulum e arrow melhoram a ergonomia do datetime - análise de strings flexíveis, deltas fluentes, conversão de fuso horário e diferenças legíveis por humanos. O zoneinfo do Python 3.9+ cobre muitas necessidades, mas essas bibliotecas ainda brilham em CLIs, relatórios e bases de código legadas.

Receita

import pendulum
 
now = pendulum.now("UTC")
tomorrow = now.add(days=1)
parsed = pendulum.parse("2026-07-09 14:30", tz="America/Chicago")
print(parsed.in_timezone("Europe/London").to_iso8601_string())

Quando usar:

• Analisar strings de data inconsistentes de exportações CSV ou APIs de terceiros
• Exibir tempo relativo ("2 horas atrás") em ferramentas de administração
• Agendar relatórios em horário local com consciência do horário de verão
• Scripts rápidos onde o boilerplate do zoneinfo parece pesado

Exemplo de Trabalho

from __future__ import annotations
 
import pendulum
 
 
def next_billing_run(anchor: str, tz: str = "UTC") -> pendulum.DateTime:
    """Retorna a próxima execução mensal às 02:00 local no dia de ancoragem."""
    base = pendulum.parse(anchor, tz=tz)
    run = base.replace(hour=2, minute=0, second=0, microsecond=0)
    now = pendulum.now(tz)
    while run <= now:
        run = run.add(months=1)
    return run.in_timezone("UTC")
 
 
def format_relative(dt: pendulum.DateTime) -> str:
    return dt.diff_for_humans()
 
 
if __name__ == "__main__":
    utc_run = next_billing_run("2026-01-15", tz="America/New_York")
    print(utc_run.to_iso8601_string())
    print(format_relative(pendulum.now("UTC").subtract(hours=3)))

O que isso demonstra:

• pendulum.parse aceita strings estilo ISO com tz explícito
• add(months=1) lida com casos extremos de fim de mês melhor do que timedelta manual
• Âncora de faturamento calculada em tz local, armazenada/exportada como UTC
• diff_for_humans para mensagens voltadas para o operador

Mergulho Profundo

Como Funciona

• pendulum - Subclasse de datetime; instâncias são em grande parte compatíveis com APIs stdlib.
• arrow - API fluente semelhante; arrow.get() analisa muitos formatos; shift() adiciona unidades de calendário.
• Fusos Horários - Ambos usam o banco de dados tz IANA (pendulum inclui tzdata no Windows).
• Sobreposição stdlib - Python 3.14 datetime + zoneinfo + dateutil.parser cobre a análise para pipelines ISO estritos.

pendulum vs arrow vs stdlib

Notas Python

from datetime import datetime
from zoneinfo import ZoneInfo
 
# Equivalente stdlib para limite de armazenamento
utc = datetime.now(ZoneInfo("UTC"))
local = utc.astimezone(ZoneInfo("America/Chicago"))

Armadilhas

• Datetimes ingênuos em bancos de dados - Bugs de horário de verão e horários locais ambíguos. Correção: TIMESTAMPTZ + armazenamento UTC.
• Análise sem fuso horário - "2026-07-09" significa instantes diferentes globalmente. Correção: exigir deslocamento ou tz da organização padrão explicitamente.
• Misturar pendulum e stdlib sem perceber - Algumas APIs esperam apenas datetime. Correção: .naive() ou converter via .in_timezone("UTC") para stdlib.
• Análise dependente de localidade - "09/07/2026" é ambíguo (EUA vs UE). Correção: impor ISO 8601 nas fronteiras da API.
• Usar .timestamp() em valores ingênuos - Época errada em servidores que não estão em UTC. Correção: anexar tz antes da matemática de timestamp.
• Bibliotecas pesadas para uma chamada de formato - Custo de importação em inicializações a frio do Lambda. Correção: fromisoformat da biblioteca padrão apenas para ISO estrito.

Alternativas

FAQs

Relacionados

• datetime, zoneinfo & Time - base da biblioteca padrão
• Validação de Dados - campos de data em pipelines
• pydantic-settings - configuração com tipos de data
• openpyxl / python-docx / reportlab - datas em planilhas

Versões da Stack: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 em manutenção), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.