Whenever – Library pemrosesan tanggal dan waktu yang type-safe dan aman DST untuk Python

(github.com/ariebovenberg)

1 poin oleh GN⁺ 2025-04-14 | Belum ada komentar. | Bagikan ke WhatsApp

Whenever adalah library tanggal dan waktu untuk Python yang mencegah, lewat tipe, pencampuran naive/aware dan kesalahan perhitungan DST pada datetime, serta bisa digunakan dengan implementasi Rust atau implementasi Python murni
datetime di standard library tidak selalu memperhitungkan DST; contoh yang diberikan adalah datetime(2023, 3, 25, 22, tzinfo=ZoneInfo("Europe/Paris")) + timedelta(hours=8), yang mengembalikan 06.00 alih-alih 07.00 meski satu jam dilewati karena DST
Sistem tipe tidak dapat membedakan naive dan aware hanya dengan satu datetime, tetapi Whenever memisahkan tipe berdasarkan penggunaan seperti Instant, ZonedDateTime, dan PlainDateTime agar type checker bisa menangkap kesalahan
Dalam tabel perbandingan, Arrow dan Pendulum disebut tidak memenuhi semua aspek keamanan DST, typed aware/naive, dan performa, sementara Whenever mendukung semua kategori DST-safe, typed aware/naive, dan fast
Karena masih sebelum 1.0, API dapat berubah pada rilis minor; perubahan dijelaskan di changelog, dan type checker atau IDE dapat membantu penyesuaian

Masalah yang ingin diselesaikan Whenever

Whenever adalah library yang membantu menulis kode tanggal dan waktu yang benar dan dapat diperiksa tipenya di Python
Menyediakan implementasi Rust, serta versi Python murni untuk pengguna yang tidak ingin memakai Rust
Dirancang berdasarkan konsep-konsep teruji yang digunakan di library tanggal dan waktu modern dari bahasa lain
Diperkenalkan sebagai jauh lebih cepat daripada library pihak ketiga lain, dan biasanya juga lebih cepat daripada standard library
Rilis 1.0 ditunda untuk lebih menyempurnakan API jangka panjang, khususnya sambil menerima masukan terkait duration

datetime Python telah berkembang selama lebih dari 20 tahun, dan ada bagian-bagian yang tidak sejalan dengan ekspektasi terhadap library tanggal dan waktu modern
Masalah perhitungan DST
- datetime tidak selalu mempertimbangkan Daylight Saving Time (DST)
- Dalam contoh kode, jika menambahkan 8 jam ke pukul 22.00 tanggal 25 Maret 2023 di zona waktu Europe/Paris, hasilnya seharusnya pukul 07.00 karena satu jam dilewati akibat DST, tetapi yang dikembalikan adalah pukul 06.00
- Ini bukan bug, melainkan keputusan desain untuk mempertimbangkan DST hanya pada perhitungan yang melibatkan dua zona waktu
Masalah pembedaan tipe naive/aware
- Dengan satu tipe datetime saja, naive datetime dan aware datetime tidak dapat dibedakan dalam sistem tipe
- Signature fungsi seperti def schedule_meeting(at: datetime) -> None: ... tidak menunjukkan apakah yang diharapkan adalah naive atau aware

Berdasarkan tabel perbandingan, Whenever memenuhi semua aspek DST-safe, typed aware/naive, dan fast
datetime hanya memenuhi aspek fast, tetapi tidak memenuhi DST-safe dan typed aware/naive
Arrow berupaya menyediakan API yang lebih ramah daripada standard library, tetapi tidak menyelesaikan masalah inti
- Tetap mempertahankan footgun yang sama
- Keputusan untuk menyederhanakan tipe menjadi satu arrow.Arrow membuat type checker lebih sulit menangkap kesalahan
Pendulum pada 2016 mengusung penanganan DST yang lebih baik dan peningkatan performa, tetapi hanya memperbaiki sebagian jebakan terkait DST
- Performanya menurun secara signifikan seiring waktu
- Dalam 4 tahun terakhir hanya ada 2 rilis, menunjukkan stagnasi pemeliharaan yang panjang, dan masih banyak isu serius yang sudah lama ada

Mengimpor tipe eksplisit seperti Instant, ZonedDateTime, dan PlainDateTime untuk merepresentasikan berbagai use case
Instant.now() mengidentifikasi satu titik waktu tertentu tanpa kompleksitas zona waktu atau kalender
Mengonversi zona waktu secara eksplisit seperti now.to_tz("Europe/Paris")
PlainDateTime("2023-10-28 22:00") tidak akan tercampur secara tidak sengaja dengan tipe lain
- Saat memanggil add(hours=6), muncul NaiveArithmeticWarning bahwa penyesuaian waktu lokal mengabaikan DST
- Zona waktu harus diasumsikan secara eksplisit dengan assume_tz("Europe/Amsterdam")
Saat menjalankan add(hours=6) pada ZonedDateTime, hasilnya mencerminkan transisi DST dan mengembalikan 2023-10-29 03:00:00+01:00[Europe/Amsterdam]
Mendukung perbandingan, pembulatan dan pemotongan, parsing format ISO8601·RFC3339·RFC2822, serta format pola kustom
Jika diperlukan, dapat dikonversi ke datetime standard library atau sebaliknya
Cara penggunaan lebih detail dapat dilihat di feature overview dan API reference

Cakupan dukungan adalah proleptic Gregorian calendar dari tahun 1 hingga 9999
Offset zona waktu dibatasi ke bilangan bulat dalam satuan detik, konsisten dengan IANA TZ DB
Whenever mengikuti semantic versioning
Sebelum 1.0, API dapat berubah pada rilis minor
breaking change dijelaskan secara rinci di changelog
Karena API sepenuhnya diberi tipe, type checker atau IDE dapat membantu menangani perubahan API

Whenever didistribusikan dengan MIT License
binary wheel menyertakan dependensi Rust dengan lisensi permisif serupa seperti MIT dan Apache-2.0
Noda Time dan Joda Time memelopori pendekatan tipe berdasarkan konsep, dan hierarki tipe Noda Time menjadi inspirasi langsung bagi desain Whenever
Temporal menginspirasi penanganan kasus-kasus kompleks seputar ambiguitas DST dan pembulatan
Modul datetime Python banyak digunakan untuk pemrosesan tanggal dan waktu tingkat rendah dalam implementasi Python murni Whenever
Sebagian ide dari Jiff juga diadopsi
Grafik perbandingan benchmark diadaptasi dari proyek Ruff