Python: Getting started with Pendulum package
Tags: python, beginners
Published: 2020-06-15 00:33:42

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.

<h4>Why choose Pendulum?</h4>
* 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.   

<h4>How to install Pendulum?</h4>
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`

<h4>Basic Pendulum Usage</h4>
Here are sample of some of the functions available in Pendulum library:  
```python
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
```
<h4>Formatting Examples</h4>
There is a rich set of formatting functions including localization support offered by this library.  
```python
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)
```

<h4>Date Manipulation and Comparison Examples</h4>
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.
```python
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
```
 
<h4>Further Reading</h4>
Please visit <a href="https://pendulum.eustace.io/docs/">Pendulum Documentation</a> to learn more about the package.