Whenever – Python के लिए type-safe और DST-safe date-time handling library

• Whenever Python के datetime में naive/aware के मिश्रण और DST calculation की गलतियों को types के ज़रिए रोकने वाली date-time library है, जिसे Rust implementation या pure Python implementation के रूप में इस्तेमाल किया जा सकता है
• Standard library datetime हमेशा DST को reflect नहीं करती; उदाहरण दिया गया है कि datetime(2023, 3, 25, 22, tzinfo=ZoneInfo("Europe/Paris")) + timedelta(hours=8) DST की वजह से एक घंटा skip होने के बावजूद 7 बजे के बजाय 6 बजे लौटाता है
• Type system सिर्फ एक datetime से naive और aware में फर्क नहीं कर पाता, लेकिन Whenever Instant, ZonedDateTime, PlainDateTime जैसे use-case-specific types अलग करता है ताकि type checker गलतियां पकड़ सके
• Comparison table में Arrow और Pendulum DST safety, typed aware/naive और performance—तीनों को पूरा नहीं करते, जबकि Whenever को DST-safe, typed aware/naive और fast सभी items support करने वाला बताया गया है
• यह अभी 1.0 से पहले है, इसलिए minor releases में API बदल सकती है; बदलाव changelog में समझाए जाते हैं और type checker या IDE adjustment में मदद कर सकते हैं

---

Whenever जिस समस्या को हल करना चाहता है

• Whenever Python में सही और type-checkable date-time code लिखने में मदद करने वाली library है
• यह Rust implementation देता है, और जो users Rust नहीं चाहते उनके लिए pure Python version भी है
• इसे modern दूसरी languages की date-time libraries में इस्तेमाल होने वाले proven concepts के आधार पर design किया गया है
• इसे दूसरी third-party libraries से काफी तेज़, और आम तौर पर standard library से भी तेज़ बताया गया है
• 1.0 release long-term API को और refine करने के लिए hold पर है, खासकर duration से जुड़े feedback लिए जा रहे हैं

Standard library datetime की सीमाएं

• Python का datetime 20 साल से ज़्यादा समय में evolve हुआ है, और इसमें कुछ हिस्से modern date-time library से अपेक्षित तरीके से मेल नहीं खाते

• DST calculation की समस्या

  • datetime Daylight Saving Time(DST) को हमेशा ध्यान में नहीं रखता
  • Example code में Europe/Paris timezone में 25 मार्च 2023 को 22:00 बजे में 8 घंटे जोड़ने पर DST के कारण एक घंटा skip होने से 7 बजे होना चाहिए, लेकिन यह 6 बजे लौटाता है
  • यह bug नहीं, बल्कि design decision है कि DST को केवल उन calculations में consider किया जाए जिनमें दो timezones involved हों

• naive/aware type distinction की समस्या

  • सिर्फ एक datetime type से naive datetime और aware datetime को type system में अलग नहीं किया जा सकता
  • def schedule_meeting(at: datetime) -> None: ... जैसी function signature से पता नहीं चलता कि naive expected है या aware

Arrow और Pendulum से तुलना

• Comparison table के अनुसार Whenever DST-safe, typed aware/naive और fast—तीनों को पूरा करता है
• datetime सिर्फ fast item पूरा करता है, DST-safe और typed aware/naive नहीं
• Arrow standard library से ज़्यादा friendly API देने की कोशिश करता है, लेकिन core problem हल नहीं करता
  • वही footgun बनाए रखता है
  • type को arrow.Arrow एक ही type में घटाने के decision के कारण type checker के लिए गलतियां पकड़ना और मुश्किल हो जाता है
• Pendulum ने 2016 में बेहतर DST handling और performance improvement को highlight किया था, लेकिन DST से जुड़े कुछ traps ही ठीक किए
  • समय के साथ performance काफी गिर गई
  • पिछले 4 साल में केवल 2 releases के साथ लंबे maintenance stagnation की स्थिति है, और कई serious व पुराने issues अब भी बचे हैं

मुख्य features

• DST-safe arithmetic support करता है
• Type-safe API से common bugs रोकता है
• Arrow और Pendulum जिन समस्याओं को ठीक नहीं कर पाए, उन्हें ठीक करता है
• Proven और familiar concepts पर आधारित है
• High performance देता है
• Tests और documentation मजबूत हैं
• Date arithmetic support करता है
• Nanosecond precision support करता है
• SQLAlchemy support देता है
• Pydantic support beta status में है
• Rust implementation और pure Python option देता है
• free-threading support beta status में है
• per-interpreter GIL support करता है

Usage example flow

• Instant, ZonedDateTime, PlainDateTime जैसे explicit types import करके अलग-अलग use cases express किए जाते हैं
• Instant.now() timezone या calendar complexity के बिना किसी specific instant को identify करता है
• now.to_tz("Europe/Paris") की तरह timezone को explicitly convert किया जाता है
• PlainDateTime("2023-10-28 22:00") गलती से दूसरे types के साथ mix नहीं होता
  • add(hours=6) call करने पर NaiveArithmeticWarning आता है कि local time adjustment DST को ignore करता है
  • assume_tz("Europe/Amsterdam") से timezone को explicitly assume करना पड़ता है
• ZonedDateTime में add(hours=6) करने पर DST transition reflect होता है और 2023-10-29 03:00:00+01:00[Europe/Amsterdam] result लौटता है
• Comparison, rounding और truncation, ISO8601·RFC3339·RFC2822 format parsing, custom pattern format support करता है
• जरूरत हो तो standard library datetime में convert किया जा सकता है, या उससे वापस convert किया जा सकता है
• Detailed usage feature overview और API reference में देखी जा सकती है

Constraints और stability policy

• Support range वर्ष 1 से 9999 तक के proleptic Gregorian calendar तक सीमित है
• Timezone offsets IANA TZ DB के अनुरूप second-unit integers तक सीमित हैं
• Whenever semantic versioning follow करता है
• 1.0 से पहले minor releases में API बदल सकती है
• breaking changes changelog में detail से explain किए जाते हैं
• API पूरी तरह typed है, इसलिए type checker या IDE API changes से निपटने में मदद कर सकते हैं

License और design influences

• Whenever MIT License के तहत distributed है
• binary wheel में MIT, Apache-2.0 जैसी similarly permissive licenses वाली Rust dependencies शामिल हैं
• Noda Time और Joda Time ने concept-specific type approach को pioneer किया, और Noda Time की type hierarchy ने Whenever design को सीधे inspire किया
• Temporal ने DST ambiguity और rounding के आसपास complex cases handling के लिए inspiration दी
• Python का datetime module Whenever के pure Python implementation में low-level date-time handling के लिए व्यापक रूप से इस्तेमाल होता है
• Jiff के कुछ ideas भी लिए गए हैं
• Benchmark comparison graph Ruff project से adapt किया गया है