behavior of ZonedDateTime during a "gap" unclear

[bxparks]

https://whenever.readthedocs.io/en/latest/api.html#whenever.ZonedDateTime

The ZonedDateTime takes an optional disambiguate parameter which allows "later" and "earlier". I think the documentation may need to be more explicit about the behavior is during a "gap". If the library converts the "earlier" string to fold=0 (as documented in the API docs), then according to PEP 495, the ZonedDateTime will actually pick the later datetime, which contradicts the documentation. Similarly, if "later" is chosen and it sets fold=1, then during a gap, the earlier datetime will be selected.

Secondly, I think the API documentation should probably contain a reference to PEP 495 somewhere around the first mention of the fold parameter, because it's basically impossible to understand what that parameter means without PEP 495.

Thirdly, it looks like the fold parameter is no longer exposed through LocalDateTime, but the API documentation still has some examples with an explicit fold=0 or fold=1 in the constructor of LocalDateTime. (I don't want to create too many tickets, so I included this minor issue here.)

[ariebovenberg]

Note that the current release, disambiguate doesn't affect gaps (they always raise an exception).

release 0.4 (see the PR) also adds support for gaps, in which case "earlier" and "later" behave as you'd expect. i.e. earlier is fold=0 for ambiguity, and fold=1 for gaps.

[ariebovenberg]

In any case, have a look at what I'm working on for 0.4, which also affects LocalDateTime. Start with the CHANGELOG.rst to see what has changed.

I'll see if I can get the release candidate docs built on readthedocs.org 👀

[ariebovenberg]

@bxparks you can find the 0.4 release (candidate) docs here: https://whenever.readthedocs.io/en/0.4-dev/

[ariebovenberg]

The behavior is now fixed and documented.