README.md: Show how to interact with Python's datetime

[Feuermurmel]

I heard about this library while doing some research (after a switch from pytz to Python's zoneinfo
broke some time calculations in our codebase). I'm very interested to follow the library. The first question I had, and I'm bringing this up because I think others might also have that question, is how easy it is to interact with Python's datetime.

I found it in the docs at Overview (To and from the standard library). But maybe, since it's so short, copy that to the Readme?

Also, since we're on the topic, I have some input on that part of the API: I'd prefer it if converting from datetime to e.g. ZonedDateTime worked by calling the class:

dt = datetime.now(tz=UTC)
zdt = ZonedDateTime(dt)

I'm assuming that this is what many Python developers would expect, or at least find intuitive. Type conversions in Python are often done by calling the class (str(), list(), UUID()).

Thanks!

[ariebovenberg]

Hi @Feuermurmel thanks for posting. I'm always happy to hear about people using the library.

[..] But maybe, since it's so short, copy that to the Readme?

I do mention it at the end of the "quickstart" section. It's not that prominent though. One thing I'm considering is adding the conversion from datetime to it.

Do you have any thoughts on what parts of the readme could be de-emphasized, do make space for this?

I'm assuming that this is what many Python developers would expect, or at least find intuitive

I'm open to this, since the constructors already support str input.

[Feuermurmel]

Thanks for the quick response!

I do mention it at the end of the "quickstart" section. It's not that prominent though. One thing I'm considering is adding the conversion from datetime to it.

Do you have any thoughts on what parts of the readme could be de-emphasized, do make space for this?

You are right! I overlooked that part. I went over the examples, but glossed over them towards the end.

I thought about this for a long time (and read through the API docs) and I figured out what I was actually missing: Something that's giving me an overview of all the types that the library provides and their members. I'm not one that easily understands an API by reading example code, so I probably can't give you advice on how to extend/restructure the "Quickstart" examples.

There are a few compounding factors:

• I only found the TOC ("ON THIS PAGE") while I was already writing this response. Somehow, with my browser's width, the main navigation on the left is shown, but not the one on the right (and I didn't notice the little button in the top right to show it). I was somehow assuming that the TOC would also be on the left side, below the main navigation… silly me.

• The TOC is a bit hard to get an overview with, because it lists everything in a big tree. I'm not sure if it would be a perfect solution here, but e.g. the documentation of the Python standard library (e.g. datetime) only lists some top-level objects. But in my mind, nothing tops JavaDoc in clarity (e.g. java.time), so I might be the odd one out in the Python ecosystem.

  I think in your situation I would add a list of all non-abstract types at the top of the API reference, before or instead of the graphic, with a one-sentence description of each type.

  whenever provides the following types to represent time-related values:

  • Instant: Represents a moment in time with nanosecond precision.
  • PlainDateTime: A combination of date and time-of-day, without a timezone.
  • …

• Many interesting methods (e.g. from_py_datetime(), py_datetime()) are not listed in the concrete classes, but under _BasicConversions instead. This made them hard to discover for me, because I first had to understand the class hierarchy before I could make sense of where these methods apply and where to look for them.

  I think the class hierarchy is more of an implementation detail than part of the public API?

I'm assuming that this is what many Python developers would expect, or at least find intuitive

I'm open to this, since the constructors already support str input.

👍

[ariebovenberg]

I'm happy to hear somebody appreciates API docs 😄 . My focus at the moment is making the last breaking changes before 1.x, but I hope to give the API docs a proper refresh after that.

Something that's giving me an overview of all the types that the library provides and their members

Many interesting methods (e.g. from_py_datetime(), py_datetime()) are not listed in the concrete classes, but under _BasicConversions instead

My intention with these 'virtual' base classes was to avoid overly duplicated definitions. But considering the downsides of the current approach, I agree it's probably best to just make a "big simple list".

Somehow, with my browser's width, the main navigation on the left is shown, but not the one on the right

Regarding docs styling I try to stick with the defaults, so there are no surprises. Unfortunate the it isn't so intuitive then. The "main TOC on left, page TOC on the right" seems to be something mainstream in Python documentation themes. I'll have a look what can be customized here. The theme I'm using is very popular so should offer good, readable, customization.

[Feuermurmel]

I'm happy to hear somebody appreciates API docs 😄 . My focus at the moment is making the last breaking changes before 1.x, but I hope to give the API docs a proper refresh after that.

I get it. Sounds good! :)

Somehow, with my browser's width, the main navigation on the left is shown, but not the one on the right

Regarding docs styling I try to stick with the defaults, so there are no surprises. Unfortunate the it isn't so intuitive then. The "main TOC on left, page TOC on the right" seems to be something mainstream in Python documentation themes. I'll have a look what can be customized here. The theme I'm using is very popular so should offer good, readable, customization.

I would also definitely try to use something that is widely used. Even if the defaults aren't optimal, there's a higher change that they get fixed or people get used to it and it's no longer an issue for many people.

Just to see if I was way off in how I remembered the docs I often visit, here's a quick list of the top 5:

• Python: Navigation at top, TOC on left.
• Django: Navigation and TOC in single column on right.
• AIOHTTP: Navigation on left and no TOC.
• Requests: Navigation and TOC in single column on left.
• Beautiful Soup: Single page, TOC on left.

No two are doing the same. 😅