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
- 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
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
subtract functions with a variety of arguments ranging from
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
Please visit Pendulum Documentation to learn more about the package.