Pendulum Versions Save

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

Added

• Made instance() support all native types (date, time, datetime). #732

Changed

• Dropped support for Python 3.7. #734
• Rewrote extensions in Rust. #721
• Made day of week convention more consistent across the codebase. #731

Fixed

• 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

Added

• Added new testing helpers to time travel. #626

Changed

• Dropped support for Python 2.7, 3.5 and 3.6. #569
• 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

Locales

• Added the sk locale. #575
• Added the ja locale. #610
• Added the he locale. #585
• Added the sv locale. #562

Changed

• Added support for build scripts without the setup.py file generation in the editable builder (#2718).

Fixed

• Fixed an error occurring when using older lock files (#2717).

Fixed

• Fixed errors where invalid timezones were matched in from_format() (#374).
• Fixed errors when subtracting negative timedeltas (#419).
• Fixed errors in total units computation for durations with years and months (#482).
• Fixed an error where the fold attribute was overridden when using replace() (#414).
• Fixed an error where now() was not returning the correct result on DST transitions (#483).
• Fixed inconsistent typing annotation for the parse() function (#452).

Locales

• Added the pl locale (#459).

Added

• Added better typing and PEP-561 compliance (#320).
• Added the is_anniversary() method as an alias of is_birthday() (#298).

Changed

• Dropped support for Python 3.4.
• is_utc() will now return True for any datetime with an offset of 0, similar to the behavior in the 1.* versions (#295)
• Duration.in_words() will now return 0 milliseconds for empty durations.

Fixed

• Fixed various issues with timezone transitions for some edge cases (#321, (#350)).
• Fixed out of bound detection for nth_of("month") (#357).
• Fixed an error where extra text was accepted in from_format() (#372).
• Fixed a recursion error when adding time to a DateTime with a fixed timezone (#431).
• Fixed errors where Period instances were not properly compared to other classes, especially timedelta instances (#427).
• Fixed deprecation warnings due to internal regexps (#427).
• Fixed an error where the test() helper would not unset the test instance when an exception was raised (#445).
• Fixed an error where the week_of_month attribute was not returning the correct value (#446).
• Fixed an error in the way the Z ISO-8601 UTC designator was not parsed as UTC (#448).

Locales

• Added the nl locale.
• Added the it locale.
• Added the id locale.
• Added the nb locale.
• Added the nn locale.

Fixed

• Fixed from_format() not recognizing input strings when the specified pattern had escaped elements.
• Fixed missing x token for string formatting.
• Fixed reading timezone files.
• Added support for parsing padded 2-digit days of the month with from_format()
• Fixed from_format() trying to parse escaped tokens.
• Fixed the z token timezone parsing in from_format() to allow underscores.
• Fixed C extensions build errors.
• Fixed age calculation for future dates.

Fixed

• Fixed handling of pytz timezones.
• Fixed some formatter's tokens handling.
• Fixed errors on some systems when retrieving timezone from localtime files.
• Fixed diff methods.
• Fixed closest()/farthest() methods.

Fixed

• Fixed the weeks property for negative Period instances.
• Fixed start_of() methods not setting microseconds to 0.
• Fixed errors on some systems when retrieving timezone from clock files.
• Fixed parsing of partial time.
• Fixed parsing not raising an error for week 53 for ordinary years.
• Fixed string formatting not supporting strftime format.

Fixed

• Fixed behavior of the YY token in from_format().
• Fixed errors on some systems when retrieving timezone from clock files.