dst_rule not implemented in 3.x? Has it in documentation but examples don't work.

[baubie]

• [x] I have searched the issues of this repo and believe that this is not a duplicate.

Issue

While working to migrate a codebase from Pendulum 2.x to 3.0.0 where we utilize the dst_rule parameter of Pendulum.datetime we found that it was no longer implementer; however, it is still referenced here: https://pendulum.eustace.io/docs/#timezones

[ariebovenberg]

Ran into this same issue. It seems both the argument and constants have been removed.

To reproduce:

>>> import pendulum
>>> pendulum.__version__
'3.0.0'
>>> pendulum.PRE_TRANSITION
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: module 'pendulum' has no attribute 'PRE_TRANSITION'
>>> pendulum.datetime(2023, 1, 1, dst_rule=...)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: datetime() got an unexpected keyword argument 'dst_rule'

expected pendulum.PRE_TRANSITION constant and dst_rule argument to exist.

[ariebovenberg]

Did some more digging: it seems that pendulum went back to using the standard library's fold for controlling DST behavior. The difference being that fold doesn't support raising an exception like dst_rule=TRANSITION_ERROR did.

Since this is clearly a breaking API change, it probably deserves mention in the changelog...

[gibsondan]

@ariebovenberg I don't work on pendulum and agree this is a breaking change (we are dealing with similar blockers in our library to unpinning pendulum) - I saw that the Timezone.convert method includes a raise_on_unknown_times argument that raises similar exceptions to what the TRANSITION_ERROR rule used to - so maybe that's a path forward https://github.com/sdispater/pendulum/blob/master/src/pendulum/tz/timezone.py#L73