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.

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.

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:

<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.

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

Output:

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

Converting Timezones

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:

<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.

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.

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:

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.

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:

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

Duration – timedelta replacement

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:

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

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:

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