Timezone of Instant.py_datetime()?

[arjenzorgdoc]

Instant.py_datetime() always returns a UTC time:

from whenever import Instant

t = Instant.now()
print(f"Today is {t.py_datetime():%A (%z)}")

Today is Tuesday (+0000)

I think a better API would be to make that configurable and/or explicit:

t.py_datetime("Europe/Paris")
t.py_datetime_utc()
t.py_datetime_system_tz()

or at least default to the system timezone.

[arjenzorgdoc]

This issue will also arise in any future Instant.strftime() method. In what timezone will Instants be converted to str?

[ariebovenberg]

Hi @arjenzorgdoc, thanks for sharing your experiences with whenever! I see how that corner of the API could be improved somewhat. The whole deal of Instant is that it doesn't have a timezone, after all!

The reason to have Instant.py_datetime() is that I've observed most developers use datetime(..., tzinfo=UTC) as an Instant equivalent. If the method didn't exist, there'd be no quick way to translate whenever types to a datetime with tzinfo=datetime.UTC. A super common use-case. Practicality beats purity here. This is also why Instant.round() exists, even though strictly rounding is dependent on a timezone.

While py_datetime_utc()/py_utc_datetime() is nice and explicit, it makes the names inconsistent with the py_datetime() methods on other classes. It also introduces a breaking change, which I'd like to avoid unless absolutely needed. I'm not sure it's worth the cost. I will give it some thought though, as there is still a window before the 1.0 release.

Regarding t.py_datetime(<tz>) or t.py_datetime_system_tz(): I'd rather avoid "shortcut" APIs like this as they can be easily written by chaining existing methods t.to_tz(<tz>).py_datetime() or t.to_system_tz().py_datetime(). There needs to be a really compelling reason to make the signatures/API more complicated, if the equivalent is already available and not too verbose or error-prone.

This issue will also arise in any future Instant.strftime() method. In what timezone will Instants be converted to str?

I'm not planning to add strftime() to Instant for this reason. While I believe "practicality beats purity" for py_datetime() and round(), formatting should be strict. Note strftime will be superseded by a custom formatting API anyway (#174)