Whenever – técnica de manipulação de data e hora segura em tipos e DST para Python

• Whenever é uma biblioteca que aprimora o datetime do Python, oferecendo segurança com DST e segurança de tipos
• Pode ser usada com Rust e Python puro, com alto desempenho
• Supera a biblioteca padrão do Python, além de Arrow e Pendulum, em tratamento de DST e segurança de tipos
• Suporta precisão de nanossegundos e as melhorias mais recentes no GIL, com desempenho aprimorado por meio de uma extensão em Rust
• É distribuída sob a licença MIT e segue sendo aprimorada continuamente com base em feedback

---

Introdução ao Whenever

• Whenever é uma biblioteca desenvolvida para superar as limitações do módulo datetime do Python
• Oferece segurança com DST e segurança de tipos, aumentando a precisão do código
• É implementada em Rust e Python puro, com excelente desempenho

Limitações da biblioteca padrão

• O datetime do Python nem sempre considera DST
• No sistema de tipos, não é possível distinguir entre datetimes naive e aware

Comparação com outras bibliotecas

• Arrow oferece uma API amigável, mas não resolve os problemas centrais
• Pendulum resolveu parte dos problemas de DST, mas teve queda de desempenho e pouca manutenção

Vantagens do Whenever

• Oferece operações aritméticas seguras com DST e uma API segura em tipos
• Tem alto desempenho, ainda melhor com a extensão em Rust
• Suporta precisão de nanossegundos e as melhorias mais recentes no GIL

Início rápido

• Fornece tipos explícitos como Instant, ZonedDateTime e LocalDateTime
• Permite operações aritméticas seguras com DST e conversões explícitas
• Suporta formatação e parsing nos formatos ISO8601, RFC3339 e RFC2822

Roadmap

• Versão 0.x: alcançar paridade de recursos e melhorar a API
• Versão 1.0: garantir estabilidade da API e compatibilidade retroativa

Limitações

• Suporta o calendário gregoriano de 1 d.C. a 9999
• Suporta offsets de fuso horário compatíveis com o IANA TZ DB
• Não oferece suporte a segundos bissextos

Política de versionamento e compatibilidade

• Whenever segue versionamento semântico
• Antes da versão 1.0, ainda pode haver mudanças na API

Licença

• É distribuída sob a licença MIT, e as dependências em Rust usam licenças permissivas semelhantes

Agradecimentos

• Inspirado nos projetos Temporal, Noda Time e Joda Time
• Baseado no gráfico comparativo de benchmarks do projeto Ruff

[GN⁺]

Comentários no Hacker News

• Se você ainda não leu o post no blog que explica por que essa biblioteca existe, recomendo. O título é "Ten Python datetime pitfalls, and what libraries are (not) doing about it"
• Esta biblioteca corrige o problema de violação de Liskov da biblioteca padrão. Na biblioteca padrão, é possível comparar datas, mas comparar datetime com data gera erro. Recentemente passei por dificuldades no trabalho por causa disso
• Já usei Arrow, Delorean, Pendulum e o datetime da biblioteca padrão, mas no fim escolhi Whenever. Ela realmente parece mais adequada para lidar com datetime e aparenta ser mantida de forma mais ativa. Sempre tive a sensação de que as outras bibliotecas deixavam escapar casos de borda. O Pendulum parece ter isso mais profundamente embutido na API
• Sou só eu que uso a biblioteca padrão, leio a documentação e o changelog com atenção, e implemento o que preciso? Aprendi da pior forma que dependências podem arruinar um projeto. Isso não quer dizer que esta biblioteca não seja ótima. Claro que há casos de uso para ela
• É oferecida em Rust ou em Python puro. A complexidade de usar pacotes binários ou precisar compilar não compensa em relação ao ganho de desempenho. A versão em Python puro precisa ser compilada a partir do código-fonte e requer flags especiais, então não pode ser especificada no requirements.txt
• Se desempenho não for a prioridade máxima, também dá para usar a versão em Python puro. Eu também gostaria de ver benchmarks da implementação em Python puro. E se ela for mais lenta que Arrow?
• É curioso que o Pandas não adicione comparação de datetime. Provavelmente ele seria usado para lidar com mais datas do que outras bibliotecas
• Alguém sabe quando questões de desempenho realmente importam? Entendo datetime como objetos de vida curta. Você provavelmente não vai querer milhares de objetos datetime espalhados pelo codebase. Em quase todos os casos, UTC já basta. Quando é preciso filtrar/agrupar em buckets/agregar por intervalo, use datetime com tz para definir os critérios de filtragem/bucket/agregação, converta isso para UTC e continue fazendo comparações com int. A maioria dos casos que Whenever trata deve ser quando datetime é um objeto de longa duração. Não sinto essa necessidade de jeito nenhum. Eu uso isso para aceitar entrada de tz do cliente e converto para UTC assim que chega. Se realmente preciso de tz, armazeno separadamente. Isso acontece raramente (por exemplo, em calendários você precisa armazenar tz, mas provavelmente não ao lado de cada UTC, e sim no nível do usuário. Outro exemplo é agendamento de equipes, em que 8am-4pm ou 8pm-4am podem significar coisas diferentes dependendo da localização. Aí já não é mais datetime, e sim horário dentro de um fuso)
• Uso Arrow quando quero algo além do básico. Esta biblioteca é bem interessante. Não por cobrir mais casos de borda, mas por oferecer tanto modo Rustified quanto modo Python puro. Com Whenever, não preciso me preocupar com outra coisa nem voltar para datetime quando quero um tratamento melhor de datas e horas no projeto. Também dá para usar em ambientes sem toolchain de Rust ou onde isso cause problema. Kudos
• Acho que deveríamos criar uma suíte de testes para toda a indústria/linguagens. Algo que permita testar muitas bibliotecas de data/hora/calendário. Seria parecido com um teste ácido para navegadores, mas focado apenas em funcionalidades básicas. Gostei desta nova biblioteca (obrigado), mas o nome sugere o oposto do que ela realmente é. "Whenever" soa como se você não se importasse, mas na prática eu só a usaria quando me importasse. E também Shakira, haha. Hmm, pedantic já está em uso. Timely, precise, punctual, meticulous, ahorita, pronto etc. Gosto de nomes relacionados a tempo. Por fim, nenhum desses links menciona imutabilidade, mas isso deveria ser citado logo no topo