Configuração de Ambiente e Instalação

Resolução de Conflitos de Dependências

A instalação padrão via pip pode falhar devido a incompatibilidades de versão entre as dependências base, especificamente pytz e python-dateutil. O Delorean exige versões recentes dessas bibliotecas para funcionar corretamente.

# Atualizando as dependências base antes da instalação
import subprocess

subprocess.run(["pip", "install", "--upgrade", "pytz", "python-dateutil"])
subprocess.run(["pip", "install", "delorean==1.0.0"])

# Verificando as versões instaladas no ambiente
import delorean

print(f"Versão Delorean: {delorean.__version__}")
print(f"Versão pytz: {delorean.pytz.__version__}")
print(f"Versão dateutil: {delorean.dateutil.__version__}")

Compilação a Partir do Código-Fonte

Ao instalar diretamente do repositório, erros de compilação podem ocorrer se as ferramentas de desenvolvimento do Python e o compilador C não estiverem presentes no sistema operacional.

# Instalação de dependências de compilação no Ubuntu/Debian
# sudo apt-get install python3-dev gcc

# Instalação de dependências de compilação no CentOS/RHEL
# sudo yum install python3-devel gcc

# Clonagem e instalação manual
import subprocess

subprocess.run(["git", "clone", "https://github.com/coleifer/delorean.git"])
subprocess.run(["python", "setup.py", "install"], cwd="delorean")

Processamento de Fusos Horários

Exceção de Fuso Horário Inválido

A criação de instâncias do Delorean com strings de fuso horário incorretas ou não padronizadas levanta a exceção DeloreanInvalidTimezone. É fundamental utilizar a nomenclatura padrão do banco de dados IANA.

from delorean import Delorean
import pytz

# Exemplo de erro por digitação incorreta
try:
    tempo_invalido = Delorean(timezone="America/Sao_Paulo_Invalido")
except Exception as erro:
    print(f"Falha: {erro}")

# Listando fusos horários válidos para consulta
fusos_validos = pytz.all_timezones
print(f"Total de fusos disponíveis: {len(fusos_validos)}")

Armadilhas na Comparação de Fusos

Comparar objetos do Delorean de fusos horários difeerntes pode gerar resultados contraintuitivos, pois a biblioteca normaliza os objetos para o timestamp UTC interno antes da comparação.

from delorean import Delorean
from datetime import datetime
import pytz

horario_pacifico = Delorean(datetime=datetime(2023, 1, 1, 12, 0), timezone='US/Pacific')
horario_utc = Delorean(datetime=datetime(2023, 1, 1, 20, 0), timezone='UTC')

# Retorna True, pois representam o mesmo instante absoluto (epoch)
print("Comparação absoluta:", horario_pacifico == horario_utc)

# Para comparar o horário do relógio local, converta explicitamente
horario_pacifico_convertido = horario_utc.datetime.astimezone(pytz.timezone('US/Pacific'))
print("Comparação local:", horario_pacifico.datetime == horario_pacifico_convertido)

Parsing e Formatação de Datas

Ambiguidade em Strings de Data

Strings de data sem separadores claros ou com formatos regionais misturados podem ser interpretadas incorretamente. Os parâmetros dayfirst e yearfirst devem ser utilizados para eliminar ambiguidades.

from delorean import parse

# Forçando o formato dia/mês/ano (padrão europeu/brasileiro)
data_local = parse("06-05-2023", dayfirst=True)
print("Data local:", data_local.datetime.date())

# Forçando o formato ano/mês/dia (padrão ISO)
data_iso = parse("2023-05-06", yearfirst=True)
print("Data ISO:", data_iso.datetime.date())

Parsing com Offset de Fuso Horário

O Delorean consegue interpretar nativamente strings que contêm offsets numéricos de fuso horário, convertendo-os para objetos FixedOffset.

from delorean import parse

registro_tempo = parse("2023-01-01T00:00:00+08:00")
print("Fuso detectado:", registro_tempo.timezone)
print("Datetime UTC:", registro_tempo.to_utc().datetime)

Técnicas Avançadas de Manipulação

Truncamento de Tempo

O método truncate() redefine as unidades de tempo menores para zero. Tentar usar níveis não suportados resultará em erro.

from delorean import Delorean
from datetime import datetime

marco_temporal = Delorean(datetime=datetime(2023, 5, 15, 14, 30, 25, 500000))

print("Truncado para hora:", marco_temporal.truncate('hour').datetime)
print("Truncado para dia:", marco_temporal.truncate('day').datetime)
print("Truncado para mês:", marco_temporal.truncate('month').datetime)

try:
    marco_temporal.truncate('quarter')
except ValueError as erro:
    print("Erro capturado:", erro)

Deslocamento de Tempo

A API de deslocamento permite navegar pelo calendário de forma fluente, ignorando fins de semana ou pulando unidades específicas.

from delorean import Delorean

ponto_no_tempo = Delorean()

# Navegação relativa
proximo_mesmo_dia = ponto_no_tempo.next_month(1)
tres_anos_atras = ponto_no_tempo.last_year(3)

# Encontrar o próximo dia da semana específico
proxima_sexta = ponto_no_tempo.next_friday()
print("Próxima sexta-feira:", proxima_sexta.datetime)

Otimização de Desempenho

Geração em Lote com Geradores

Ao gerar grandes sequências de datas com a função stops(), o uso de geradores evita o consumo excessivo de memória RAM.

from delorean import stops, DAILY

# Abordagem ineficiente (carrega todos os objetos na memória)
# lista_pontos = list(stops(freq=DAILY, count=10000))

# Abordagem otimada (avaliação preguiçosa)
iterador_pontos = (ponto for ponto in stops(freq=DAILY, count=10000))

for ponto in iterador_pontos:
    # processar_dado(ponto)
    pass

Comparação em Massa

Em loops que comparam milhares de objetos Delorean, acessar diretamente a propriedade epoch (que retorna um float/int) é significativamente mais rápido do que comparar os objetos complexos.

from delorean import Delorean

evento_x = Delorean()
evento_y = Delorean()

# Comparação lenta (envoca métodos mágicos e verificações de fuso)
# if evento_x == evento_y:

# Comparação rápida (operação numérica direta)
if evento_x.epoch == evento_y.epoch:
    print("Eventos simultâneos")

Tratamento de Exceções e Depuração

Estratégias para Exceções

O Delorean expõe exceções específicas que devem ser capturadas para garantir a resiliência da aplicação em ambientes de produção.

from delorean import Delorean
from delorean.exceptions import (
    DeloreanError,
    DeloreanInvalidTimezone,
    DeloreanInvalidDatetime
)
import logging

logger = logging.getLogger(__name__)

try:
    instancia = Delorean(timezone="Regiao/Invalida")
except DeloreanInvalidTimezone as erro_tz:
    logger.error(f"Fuso horário incorreto: {erro_tz}")
    instancia = Delorean(timezone="UTC")
except DeloreanInvalidDatetime as erro_dt:
    logger.error(f"Data inválida: {erro_dt}")
    instancia = Delorean()
except DeloreanError as erro_geral:
    logger.error(f"Erro genérico do Delorean: {erro_geral}")

Depurando Conversões

Para inspecionar visualmente como o Delorean está interpretando um fuso horário, utilize o método de formatação com locales específicos.

from delorean import Delorean

data_local = Delorean(timezone="America/Sao_Paulo")
print(data_local.format_datetime(format='full', locale='pt_BR'))

Migração de Versões e Compatibilidade

Atualização da 0.x para 1.x

A versão 1.0.0 introduziu uma mudança de API onde vários métodos foram convertidos em propriedades (properties) para melhorar a legibilidade e consistência.

objeto_data = Delorean()

# Sintaxe obsoleta (Versão 0.x)
# timestamp = objeto_data.epoch()
# inicio_dia = objeto_data.midnight()
# fuso = objeto_data.timezone()

# Sintaxe atual (Versão 1.x)
timestamp = objeto_data.epoch
inicio_dia = objeto_data.midnight
fuso = objeto_data.timezone

Compatibilidade com Versões do Python

O Delorean 1.x requer recursos de sintaxe presentes apenas no Python 3.7+. Para ambientes legados, é necessário fixar a versão da biblioteca.

# Para ambientes Python 3.6 ou inferiores
# pip install "delorean<1.0.0"

# Para ambientes Python 3.7+
# pip install "delorean>=1.0.0"