Announcing Pendulum 3.0.0

The Pendulum team is pleased to announce the immediate availability of Pendulum 3.0.0.

The new major version of Pendulum is now finally out. This was a release that took some time to see the light of day and, despite the relatively modest change log and the public API pretty much the same, a lot of the internals have changed to further improve the compatibiility with the standard library and the overall performace of the library.

New features

instance() now supports all native types (date, time and datetime)

Before this release, only a datetime could be given to the instance() helper to get an equivalent DateTime instance.

Now you can give to instance a date or time as well:

import pendulum
from datetime import date, time

pendulum.instance(date(2023, 12, 15))
pendulum.instance(time(12, 34, 56))

New testing helpers (and removal of the old ones)

This release now provides improved testing helpers that rely internally on time-machine.

These helpers are optional and for them to work, you need to opt-in the test extra when installing Pendulum.

poetry add "pendulum[test]"
# Or directly via pip
pip install "pendulum[test]"

Relative time travel

You can travel in time relatively to the current time

>>> import pendulum

>>> now = pendulum.now()
>>> pendulum.travel(minutes=5)
>>> pendulum.now().diff_for_humans(now)
"5 minutes after"

Note that once you've travelled in time the clock keeps ticking. If you prefer to stop the time completely you can use the freeze parameter:

>>> import pendulum

>>> now = pendulum.now()
>>> pendulum.travel(minutes=5, freeze=True)
>>> pendulum.now().diff_for_humans(now)
"5 minutes after"  # This will stay like this indefinitely

Absolute time travel

Sometimes, you may want to place yourself at a specific point in time. This is possible by using the travel_to() helper. This helper accepts a DateTime instance that represents the point in time where you want to travel to.

>>> import pendulum

>>> pendulum.travel_to(pendulum.yesterday())

Similarly to travel, it's important to remember that, by default, the time keeps ticking so, if you prefer stopping the time, use the freeze parameter:

>>> import pendulum

>>> pendulum.travel_to(pendulum.yesterday(), freeze=True)

Travelling back to the present

Using any of the travel helpers will keep you in the past, or future, until you decide to travel back to the present time. To do so, you may use the travel_back() helper.

>>> import pendulum

>>> now = pendulum.now()
>>> pendulum.travel(minutes=5, freeze=True)
>>> pendulum.now().diff_for_humans(now)
"5 minutes after"
>>> pendulum.travel_back()
>>> pendulum.now().diff_for_humans(now)
"a few seconds after"

However, it might be cumbersome to remember to travel back so, instead, you can use any of the helpers as a context manager:

>>> import pendulum

>>> now = pendulum.now()
>>> with pendulum.travel(minutes=5, freeze=True):
>>>     pendulum.now().diff_for_humans(now)
"5 minutes after"
>>> pendulum.now().diff_for_humans(now)
"a few seconds after"

Extensions rewritten in Rust

Some parts of Pendulum were historically written in C for improved performances. These are now written in Rust for cleaner, more maintainable code. Performances are also better with this rewrite.

This is the first step towards a more extensive rewrite in Rust of the library. Note that Pendulum will still provide a pure Python version of the library.

Other changes

• Relaxed dependency constraints. #760
• Made the day of week convention more consistent across the codebase. #731
• The Timezone class now relies on the native zoneinfo.ZoneInfo class. #569
• Renamed the Period class to Interval. #676
• Renamed the period helper to interval. #676
• Removed existing testing helpers: test() and set_test_now(). #626

Fixes

• Fixed the behavior of the week_of_month property for edge cases in January and December. #774
• Fixed the handling of the fold attribute when deep-copying a DateTime instance. #776
• Fixed errors where hours and days were not handled properly when adding durations. #775
• Fixed errors where hours and days were not handled properly when adding durations. #775
• Fixed datetime string representation to match the native library. #733
• Fixed issues on some system when retrieving the local timezone. #733
• Fixed DST handling in start_of()/end_of() methods. #713