If you've not read the blog post that explains why this library exists I recommend it. It's called "Ten Python datetime pitfalls, and what libraries are (not) doing about it"

https://dev.arie.bovenberg.net/blog/python-datetime-pitfalls...

Ah nice it solves the Liskov violation that the standard library has. In the standard library, dates can be compared with <, and datetimes are dates. But compare a datetime with a date with <, and you get an error. This drove me nuts at work recently.

I wonder what benefits this choice has that outweigh the risks of this behavior.

I’ve tried Arrow, Delorean, and Pendulum, plus the stdlib datetime of course, and settled on Whenever. It fits what I actually do with datetimes better, plus it seems more actively maintained. With the others I always seem to have a nagging feeling in the back of my mind that I am missing a whole load of edge cases. With Pendulum that seems more baked into the API.

Sounds like we need an industry/language-wide test suite to check these many date/time/calendar libraries against. Like the browser acid tests, though focused to baseline functionality only.

https://en.wikipedia.org/wiki/Acid3

I like this new lib (Thank You) but the name unfortunately implies the opposite of what it is. "Whenever" sounds like you don't care, but you'd only be using this if you did care! Also Shakira, haha. Hmm, pedantic is taken. Timely, precise, punctual, meticulous, ahorita, pronto, etc. I like that temporal name.

Finally, none of these links mention immutability, but it should be mentioned at the top.

Am I the only one to stick with the std lib, read the docs and changelogs carefully, and implement functions I really need the way my application makes use of them?

I learned the hard way, that dependencies kill projects.

Not saying this isn't great, thanks for creating it! It does have its use cases, of course.

> available in Rust or pure Python.

Hard pass. The complexity of having to use binary packages or build things is not worth the performance benefit. The pure-Python version requires building from source and passing special flags, so it is not possible to specify it in requirements.txt.

A big revelation for me in solving so much timezone insanity came from realising that timezones should be expressed as locations rather than zones.

Avoid general terms like "Pacific Standard Time" and stick to location-specific ones like: "Vancouver/Canada". The latter is how people expect their time to work, and correctly handles whatever quirky choices jurisdictions choose to do with their time.

Funny it doesn’t add comparison to date times in pandas, which is probably used to handle more dates than any of the others.

> If performance isn't your top priority, a pure Python version is available as well.

Then it would have been nice to see the benchmarks of the pure Python implementation as well. What if it's worse than arrow?

Does someone know when these performance issues matter? My understanding is that datetime is a shortlived object, you wouldn't want thousands of datetime objects all over the codebase.

Almost all of the time UTC is enough, if I need to filter/bucket/aggregate by some range, I can reach for datetime with tz for these filter/bucket/aggregate criteria, convert them to UTC and on continues `int` comparison.

I'd imagine all of the cases handled by Whenever are mostly when datetime is a long lived object, which I don't see a need for at all.

I use it purely for allowing tz input from client, convert to UTC immediately when it arrives, or, if I really need the tz, then save it separately, which is rare (one example is calendar, where tz should be stored, although probably not even next to every UTC but at the user level, another is workforce scheduling, where 8am-4pm or 8pm-4am can mean different things for different locations -- but this is no longer datetime, it's purely time in a timezone).

A tangent, but I hope the world gets its shit together and gets rid of DST.

I am currently enjoying DST-free life in Japan, and feel that people around the world deserve to get this much respect from their own official clocks.

I like that the type names are the same as in Java (java.time package). Great work!

I go for Arrow when I want anything beyond the basics. This looks pretty interesting, not really because of the greater coverage in edge cases, but because while it has a Rustified mode, a pure Python mode is also available. If I do use whenever, I don't have to worry about having something else or falling back to datetime if I want better datetime handling in a project on my phone, or in some other environment where the Rust toolchain is non-existent or problematic. Kudos.

Looks amazing. I had to deal with time handling in my very first programming job 25 years ago, and lousy handling has been a pet peeve of mine ever since.

Dates and HTTP requests are the two things I always manipulate through libraries (no matter the language, except maybe for timestamps). It is so much simpler that way.

I am an amateur dev, though, so maybe someone who masters the language will be better off using the raw standard libraries.

I've read the link and the GitHub readme page.

I'm sure I'm in the top 1% of software devs for the most number of timestamps parsed. [1]

DST is not a problem in Python. It's parsing string timestamps. All libraries are bad, including this one, except Pandas. Pandas does great at DST too btw.

And I'm not shilling for Pandas either. I'm a Polars user who helicopters Pandas in whenever there's a timestamp that needs to be parsed.

Pandas has great defaults. Here's string timestamps I expect to be paesed by default. I'm willing to pass timezone in case of naive timestamps:

* All ISO 8601 formats and all its weird mutant children that differ by a tiny bit.

* 2025-05-01 (parsed not as date, but as timestamp)

* 2025-05-01 00:00:00 (or 00.0 or 00.000 or 0.000000 etc)

* 2025-05-01 00:00:00z (or uppercase Z or 00.0z or 00.000z or 0.000000z)

* 2025-05-01 00:00:00+02:00 (I don't need this converted to some time zone. Store offset if you must or convert to UTC. It should be comparable to other non naive timestamps).

* 2025-03-30 02:30:00+02:00 (This is a non existent timestamp wrt European DST but a legitimate timestamp in timestamp representation, therefore it should be allowed unless I specify CET or Europe/Berlin whatever)

* There's other timestamps formats that are non standard but are obvious. Allow for a Boolean parameter called accept_sensible_string_parsing and then parse the following:

  \* 2025-05-01 00:00 (HH:mm format)

  \* 2025-05-01 00:00+01:00 (HH:mm format)

Disclaimer: I'm on the phone and on the couch so I wasn't able to test the lib for its string parsing before posting this comment.

I really hoped this was about https://www.dangermouse.net/esoteric/whenever.html

I am still trying to cope with pytz and dateutils

Reading this post and comment section makes me shake my head. This looks like a near clone of Java JSR-310 (new date/time APIs), which was headed by the original author of Joda Time (Stephen Colebourne). Java 8 (and JSR-310) was released in 2014 -- 11 years ago(!). Amazingly, Python has suffered with their date/time libs this whole time with very little concerted effort to create new date/time APIs in the standard library. It's pathetic. I know I will be downvoted for this post, but I don't care. The Python standard library has so many of these awful weaknesses that other languages handle better. Except for machine learning R&D, I never recommend to use Python for any enterprise project except trivial ones. You are walking into a double trap of (1) weak types and (2) weak standard library.