pendulum

Pendulum provides classes that inherit from Python's native datetime objects, making them drop-in replacements. It ensures correct timezone handling by performing comparisons in UTC or within the specific timezone of the datetime being used.

Note that the default timezone for Pendulum (except when calling now()) is always UTC.

import pendulum

# Create datetimes with specific timezones
dt_toronto = pendulum.datetime(2012, 1, 1, tz='America/Toronto')
dt_vancouver = pendulum.datetime(2012, 1, 1, tz='America/Vancouver')

# Perform timezone-aware differences
print(dt_vancouver.diff(dt_toronto).in_hours())

To jump to a specific point in time, use pendulum.travel_to(). This method accepts a DateTime instance.

Note: Like travel(), the clock continues to tick by default. Use freeze=True to keep the time fixed at the destination point.

Requirement: These helpers are only available if you installed Pendulum with the test extra.

import pendulum

# Travel to a specific point in time (e.g., yesterday)
pendulum.travel_to(pendulum.yesterday(), freeze=True)

Pendulum provides helper methods to check temporal properties and relationships. For methods that compare an instance to now() (such as is_today()), Pendulum creates the now() instance in the same timezone as the object being checked to ensure consistent comparison.

Key helper methods include:

• is_past(): Checks if the instance is in the past.
• is_leap_year(): Checks if the year is a leap year.
• is_birthday(other_date): Checks if the month and day match the provided date (or current date if no argument is provided).

You can shift the current time forward or backward by a specific duration using pendulum.travel().

Note: By default, the clock continues to tick after traveling. To stop the clock at the target time, set the freeze=True parameter.

Requirement: These helpers are only available if you installed Pendulum with the test extra.

You can install the core pendulum library using pip or poetry depending on your dependency management tool.

$ pip install pendulum

# or using poetry
$ poetry add pendulum

The diff_for_humans() method can be localized in two ways:

1. Globally: Use pendulum.set_locale(locale) to change the locale for all subsequent diff_for_humans() calls in your application.
2. Locally: Pass the locale keyword argument directly to the diff_for_humans() method to use a specific locale for a single call without affecting the global state.

Pendulum offers an optional test feature that provides helpers to control the flow of time, making it easier to write deterministic tests. This feature must be explicitly requested during installation.

$ pip install pendulum[test]

# or using poetry
$ poetry add pendulum[test]

After using time travel helpers, you can return the clock to the actual current time using pendulum.travel_back().

Alternatively, and more conveniently, you can use travel() or travel_to() as a context manager using the with statement. This ensures the clock automatically returns to the present once the block of code is finished, preventing side effects in other tests.

When using .add() or .subtract() on a pendulum.DateTime instance, the library uses the context of the previous instance to automatically apply the correct transition rules. This ensures that if an arithmetic operation lands on a DST transition, the resulting object is correctly normalized.

import pendulum

dt = pendulum.datetime(2013, 3, 31, 1, 59, 59, 999999, tz='Europe/Paris')
# '2013-03-31T01:59:59.999999+01:00'

dt = dt.add(microseconds=1)
# '2013-03-31T03:00:00+02:00' (Automatically handles the jump)