[grawlinson]

This kind of stuff really needs to be made explicitly clear in any/all API documentation as it inevitably leads to underlying issues later down the line. It's amazing how something as "simple" as official time/date libraries still have footguns like these.

I'm not bashing anyone that's involved as I realize we're all human and prone to mistakes, I just wish we could all do better.

[oefrha]

Both datetime.utcnow() and datetime.utcfromtimestamp() have red box warnings in the documentation. People copying code from StackOverflow won’t see them, of course.

I should mention that the warnings are relatively recent, added in 3.8.

https://docs.python.org/3/library/datetime.html#datetime.dat...

[EdwardDiego]

Datetime APIs are ridiculously hard.

I suspect that the author of Jodatime (which effectively became the java.time API), who was notorious for being almost Linus Torvalds like in his attitudes and approaches, was probably once a very nice and kind individual. Until he started implementing a datetime library.

I mean, he nailed it, but at what cost? java.time.* is my second favourite datetime API, the first being Postgres'.

I'm actually surprised the source code of Jodatime isn't entirely in Zalgotext, technically it'd be valid Java code (I'm pretty sure, anyway).

[quickthrower2]

When dealing with any date-time library in any platform I find it best to reread the documentation almost every time I use it.

[eusto]

I bet you learned that the hard way.

It's surprising how poorly the situation with timezones is understood in the industry.

[duckmysick]

It doesn't surprise me. Timezones - and dates and time in general - are extremely complicated. Deceptively so. Although we interact with timezones, dates, and time every day, we don't think about layers of complexity and edge cases. More importantly, we don't practice them.

We have courses about compilers, databases, data structures, algorithms, cryptography. It's surprising we don't have courses about dates and time.

[eusto]

It's not surprising they didn't make an appearance in the academic world. They are utterly boring. Insanely complex, of course, but there's nothing that can be built upon. Everything in a CS curriculum is an extendable domain

[quickthrower2]

Yes .NET's DateTimeOffset was my baptism. See https://stackoverflow.com/questions/4331189/datetime-vs-date.... So confusing. Definitely readying that SO post again if I need to use it.

[radicalbyte]

Same here - it's why I like working with languages which feature IntelliSense. The documentation is right there in your IDE as you're working.

[quickthrower2]

True but often you need something to explain at a bit more of an overview level. Intelisense helps when you know the object and want to explore the methods.

[9wzYQbTYsAIc]

I’d second that recommendation.

[radicalbyte]

Most languages have something similar, that's why it's important to use static analysers as part of your process to identify usage errors. Everyone is human, mistakes happen. Having tooling as a backup is great.