Python Pendulum Date Arithmetic and Duration

When working with python pendulum date arithmetic and duration, the Pendulum library provides a DateTime class that makes date manipulation more readable and less error-prone than the standard library's datetime. Pendulum's API is designed around intuitive methods and a clear separation between durations (fixed lengths of time) and periods (spans between two instants). This article covers the core operations you'll need: adding and subtracting time, calculating differences, and handling timezone-aware arithmetic correctly.

Adding and Subtracting Durations

Pendulum's DateTime objects support the add() and subtract() methods, which accept a Duration object or keyword arguments for common units. For example, to add three days and two hours to a specific date:

import pendulum

dt = pendulum.datetime(2025, 3, 10, 12, 0, 0)
result = dt.add(days=3, hours=2)
print(result)  # 2025-03-13 14:00:00

The Duration class is used when you need to reuse a fixed time span. You can create one and apply it to multiple dates:

delay = pendulum.duration(days=1, hours=4)
start = pendulum.datetime(2025, 3, 10, 9, 30)
end = start.add(delay)

Subtraction works symmetrically with subtract(). Both methods return a new DateTime instance; Pendulum objects are immutable, so the original is unchanged. This immutability avoids accidental mutation bugs when you pass dates around.

Calculating Differences Between Dates

To find the span between two DateTime instances, use the diff() method. It returns a Period object that exposes the difference in years, months, days, hours, and so on. For example:

start = pendulum.datetime(2025, 1, 1, 0, 0, 0)
end = pendulum.datetime(2025, 3, 1, 12, 30, 0)
period = start.diff(end)
print(period.days)   # 59
print(period.hours)  # 12

diff() also accepts an optional unit argument to get the difference in a specific unit directly, such as start.diff(end, 'hours') returning the total hours as a float. This is useful when you need a single numeric value for calculations.

Duration vs Period: What's the Difference?

Pendulum distinguishes between a Duration and a Period. A Duration represents a fixed amount of time, like "2 hours" or "3 days". It is independent of any calendar context. A Period, on the other hand, is the exact span between two specific instants. Because of timezone transitions and daylight saving time, a "day" can be 23 or 25 hours long. When you subtract two DateTime objects, you get a Period that reflects the actual elapsed time, not just the calendar difference.

# A Duration is fixed
two_hours = pendulum.duration(hours=2)

# A Period is the real span between instants
p = start.diff(end)

This distinction matters when you perform arithmetic across DST boundaries. Adding a Duration of 24 hours to a timezone-aware DateTime may not land on the same wall-clock time if a DST shift occurs. Pendulum's behavior here is deliberate: add() with a Duration adds the exact number of seconds, while add() with keyword arguments like days=1 adds one calendar day, preserving the the local time where possible.

Timezone-Aware Date Arithmetic

Pendulum DateTime objects are timezone-aware by default. When you create one with datetime(), you can pass a timezone name. Arithmetic respects the timezone's rules, which is critical for applications that schedule events across DST changes.

ny = pendulum.datetime(2025, 3, 8, 12, 0, 0, tz='America/New_York')
# Add one day: DST starts on March 9,  ‍2025
next_day = ny.add(days=1)
print(next_day)  #  ‍2025-03-09 12:00:00-04:00

The wall-clock time remains ‍12:00, but the UTC offset changes from -05:00 to -04:00. If you instead added pendulum.duration(hours=24), the result would be 13:00 local time because 24 hours of actual time have passed. This distinction is a common source of bugs when migrating from the standard library, which often treats naive datetime arithmetic as if timezones did not exist.

Comparing Date and Time Values

Pendulum DateTime instances support the standard comparison operators (<, >, ==, etc.) and they work correctly across timezones because comparisons are based on the underlying UTC instant. You can also use the is_between() method to check if a date falls within a range:

start = pendulum.datetime(2025, 1, 1)
end = pendulum.datetime(2025, 12, 31)
candidate = pendulum.datetime(2025, 6, 15)
print(candidate.is_between(start, end))  # True

Equality checks compare the exact instant, so two DateTime objects representing the same moment in different timezones are considered equal. This is usually the behavior you want, but be aware that it differs from comparing wall-clock strings.

Common Pitfalls and Edge Cases

One recurring issue is mixing naive and aware DateTime objects. Pendulum does not allow arithmetic between a naive and an aware object; it raises a TypeError to force you to make the timezone explicit. This is a safety feature, but it means you must consistently attach a timezone to all values in a calculation.

Another edge case is adding months or years. Pendulum's add(months=1) handles month-end rollover differently from the standard library. For example, adding one month to January 31 yields February 28 (or 29 in a a leap year), not March 2. This is often the desired behavior for calendar-based scheduling, but it can surprise developers who expect a fixed 30-day span. If you need a fixed number of days, use add(days=30) instead.

Leap years are handled correctly by the underlying date logic, so February 29 plus one year becomes February 28 in a non-leap year.

Performance and Production Considerations

Pendulum's rich API and timezone handling come with a cost compared to the standard library's datetime for very simple operations. If your application performs millions of trivial date additions in a tight loop, the overhead of Pendulum's object model and timezone calculations may be measurable. In most web applications, however, the readability and reduced bug rate outweigh this overhead.

For production use, be deliberate about where you use Pendulum. It is an excellent choice for business logic that involves scheduling, timezone conversion, or human-readable differences. For high-throughput data processing where only the standard library's basic arithmetic is needed, sticking with datetime and timedelta can be more efficient. The decision should be based on the complexity of your timezone rules and the maintainability of the codebase, not on micro-optimizations.

When you do use Pendulum, avoid creating DateTime objects repeatedly in loops; reuse a single instance when possible. Also, be consistent with timezone handling: either always attach a timezone or always use UTC internally and convert only at the boundaries of your application.