Python: Getting started with Pendulum package

It is quite challenging to work with Python’s native datetime class especially when the project has complex date manipulation requirements involving timezones. There are several datetime packages available in Python that try to address this problem. Pendulum is one of the popular Python datetime libraries. In this article, let’s examine some of the Pendulum package’s capabilities.

Why choose Pendulum?

• Pendulum is a drop-in replacement for the standard datetime class as it inherits from Python’s built-in datetime class. This means Pendulum can be introduced in Python projects that are already using built-in datetime class.
• Pendulum simplifies complex timezone problems by storing datetime values with timezone (by default it stores datetimes in UTC format)
• This library has support for Daylight Savings Time (DST)
• It also has a rich set of utility functions that makes date manipulations and formatting quite easy.

How to install Pendulum?

Like any other Python package Pendulum can be installed using the pip install pendulum command. If you encounter any issues during installation, try installing a specific version - pip install pendulum==2.0.5

Basic Pendulum Usage

Here are sample of some of the functions available in Pendulum library:

from datetime import datetime
import pendulum

# Basic datetime creation
dt1 = pendulum.datetime(2020, 1, 1)
print(dt1)  # 2020-01-01T00:00:00+00:00
print(isinstance(dt1, datetime))  # True  (pendulum datetime inherits from built-in datetime)
print(dt1.timezone.name)  # UTC (By default datetimes are stored in UTC timezone)

# convert date to another time zone
dt2 = dt1.in_timezone("Europe/Paris")
print(dt2)   # 2020-01-01T01:00:00+01:00

# There are convience methods for today, tomorrow and yesterday
# If no timezone specified, datetimes are created with local timezone
today = pendulum.today("Europe/London")
print(today)  # 2020-06-14T00:00:00+01:00

tomorrow = pendulum.tomorrow()
print(tomorrow)  # 2020-06-15T00:00:00-04:00

yesterday = pendulum.yesterday("America/New_York")
print(yesterday)    # 2020-06-13T00:00:00-04:00

Formatting Examples

There is a rich set of formatting functions including localization support offered by this library.

import pendulum

# create a datetime
dt1 = pendulum.datetime(2020, 6, 30, 21, 30)
print(dt1)   # 2020-06-30T21:30:00+00:00

# use the format function
print(dt1.format("YYYY MM-DD HH:MM A"))   # 2020 06-30 21:06 PM
print(dt1.format("dddd DD MMMM YYYY"))  # Tuesday 30 June 2020
print(dt1.format("dddd, MMMM Do"))  # Tuesday, June 30th

# localization examples
print(dt1.format("dddd DD MMMM YYYY", locale="de"))  # Dienstag 30 Juni 2020 (German)
print(dt1.format("dddd DD MMMM YYYY", locale="zh"))  # 星期二 30 六月 2020 (Chinese)

Date Manipulation and Comparison Examples

Dates can be manipulated using add and subtract functions with a variety of arguments ranging from years to seconds. Dates can be compared with each other as well.

import pendulum

# create some base datetimes
dt1 = pendulum.datetime(2020, 6, 30, 23, 30, 0)

# Add function accepts negative values as well
newdate = dt1.add(hours=1)  
print(newdate.to_datetime_string()) # 2020-07-01 00:30:00 (Date changes to next day)

dt2 = pendulum.datetime(2020, 3, 20)
print(dt2.is_past())  # True (dt2 is compared with today)
print(dt2.is_future())  # False (dt2 is compared with today)
print(dt2.is_dst())  # False
print(dt2.is_leap_year())  # True

# comparing datetimes
print(dt1 > dt2)  # True

# Create a Period using date differences
p = dt1.diff(dt2)
print(p.in_days())  # 102

p = dt2.diff_for_humans(dt1)
print(p)  # 3 months before

Further Reading

Please visit Pendulum Documentation to learn more about the package.