Python Pendulum Module

Python Pendulum module is a drop-in replacement for the built-in datetime module. Python pendulum module supports timezones and provides useful methods to format, parse and date time manipulations. This module provides all the features of pytz module and much more.

Python Pendulum Module

We can install pendulum module using PIP command.

Copy
pip install pendulum

Python Pendulum Example

We can use the pendulum module to create timezone objects and use it with datetime.now() function to create timezone aware datetime instance.

Copy
from datetime import datetime
import pendulum

utc = pendulum.timezone('UTC')
pst = pendulum.timezone('America/Los_Angeles')
ist = pendulum.timezone('Asia/Calcutta')

print(type(utc))
print('Current Date Time in UTC =', datetime.now(utc))
print('Current Date Time in PST =', datetime.now(pst))
print('Current Date Time in IST =', datetime.now(ist))
print(type(datetime.now(ist)))

Output:

Copy
<class 'pendulum.tz.timezone.FixedTimezone'>
Current Date Time in UTC = 2018-09-25 09:16:45.031461+00:00
Current Date Time in PST = 2018-09-25 02:16:45.031501-07:00
Current Date Time in IST = 2018-09-25 14:46:45.031555+05:30
<class 'datetime.datetime'>

Let’s see how to use pendulum module as a replacement of datetime module. However, if you are already using datetime module then it’s better to not mix them up.

Copy
utc_time = pendulum.now('UTC')
print(type(utc_time))
print('Current Date Time in UTC =', utc_time)

Output:

Copy
<class 'pendulum.datetime.DateTime'>
Current Date Time in UTC = 2018-09-25T09:16:45.031608+00:00

Converting Timezones

Copy
utc_time = pendulum.now('UTC')
ist_time = utc_time.in_timezone('Asia/Calcutta')
print(type(ist_time))
print('Current Date Time in IST =', ist_time)

tz = pendulum.timezone('Europe/Paris')
paris_time = tz.convert(ist_time)
print('Current Date Time in Paris =', paris_time)

Output:

Copy
<class 'pendulum.datetime.DateTime'>
Current Date Time in IST = 2018-09-25T14:46:45.031608+05:30
Current Date Time in Paris = 2018-09-25T11:16:45.031608+02:00

Date Time Manipulations

We can use add() and subtract() functions for date time manipulations.

Copy
utc_time.add(years=1)
utc_time.subtract(months=2)
print('Updated UTC Time', utc_time)

Output: Updated UTC Time 2018-09-25T09:16:45.031608+00:00

Date Time Formatting

There are some useful methods to convert date time to standard formatted string. Pendulum module also has strftime() function where we can specify our own format.

Copy
print(utc_time.to_iso8601_string())
print(utc_time.to_formatted_date_string())
print(utc_time.to_w3c_string())
print(utc_time.to_date_string())

# supports strftime() too
print(utc_time.strftime('%Y-%m-%d %H:%M:%S %Z%z'))

Output:

Copy
2018-09-25T09:16:45.031608Z
Sep 25, 2018
2018-09-25T09:16:45+00:00
2018-09-25
2018-09-25 09:16:45 UTC+0000

Parse String to Date Time

We can use parse() function to parse a string having commonly used formats to datetime object. If you want to specify format string, then use from_format() function.

Copy
dt = pendulum.parse('2018-05-21T22:00:00')
print(dt)

dt = pendulum.parse('2018-05-21T22:00:00', tz='Europe/Paris')
print(dt)

# parsing using specified format string
dt = pendulum.from_format('2018/05/21', 'YYYY/MM/DD')
print(dt)

Output:

Copy
2018-05-21T22:00:00+00:00
2018-05-21T22:00:00+01:00
2018-05-21T00:00:00+00:00

Duration – timedelta replacement

Copy
time_delta = pendulum.duration(days=1, hours=10, years=2)
print(time_delta)
print('time_delta years =', time_delta.years)

print('time_delta in seconds =', time_delta.in_seconds())
print('time_delta in words =', time_delta.in_words())

print('future date =', pendulum.now() + time_delta)

Output:

Copy
2 years 1 day 10 hours
time_delta years = 2
time_delta in seconds = 122400
time_delta in words = 2 years 1 day 10 hours
future date = 2020-09-27T00:46:45.037866+05:30

Period of Time

Copy
current_date = pendulum.now()
future_date = current_date.add(days=4)

period_time = future_date - current_date

print('period in words =', period_time.in_words())

# period is iterable with days
for dt in period_time:
    print(dt)

Output:

Copy
period in words = 4 days
2018-09-25T14:46:45.037972+05:30
2018-09-26T14:46:45.037972+05:30
2018-09-27T14:46:45.037972+05:30
2018-09-28T14:46:45.037972+05:30
2018-09-29T14:46:45.037972+05:30

Reference: Official Website

About Pankaj

I love Open Source technologies and writing about my experience about them is my passion. You can connect with me directly on Facebook, Twitter, and YouTube.