Pendulum Module in Python

The Pendulum Module is a powerful Python library for datetime manipulation and time zone management. It provides an intuitive API for handling dates, times, and timezone conversions more elegantly than Python's built-in datetime module.

The Pendulum Module's main advantage is its ability to manage time zones easily. It can instantly convert between various time zones and handle dates and times from around the world. You can install this module using the following command ?

pip install pendulum

Key Methods in Pendulum Module

The Pendulum module provides several essential methods for datetime operations ?

• add() Add time units to a datetime

• subtract() Subtract time units from a datetime

• format() Format datetime as string

• period() Create time periods between dates

• parse() Parse string to datetime object

• in_timezone() Convert to different timezone

add() Method

The add() method increments a Pendulum instance by one or more time units (years, months, days, hours, minutes, seconds, etc.).

import pendulum

# Get current datetime
now = pendulum.now()
print("Current time:", now)

# Add 3 days
result = now.add(days=3)
print("After adding 3 days:", result)

# Add multiple units
result2 = now.add(days=2, hours=5, minutes=30)
print("After adding 2 days, 5 hours, 30 minutes:", result2)

Current time: 2023-06-12T12:59:34.170914+05:30
After adding 3 days: 2023-06-15T12:59:34.170914+05:30
After adding 2 days, 5 hours, 30 minutes: 2023-06-14T18:29:34.170914+05:30

subtract() Method

The subtract() method removes one or more time units from a Pendulum instance and returns the new datetime.

import pendulum

now = pendulum.now()
print("Current time:", now)

# Subtract 3 days and 2 hours
result = now.subtract(days=3, hours=2)
print("After subtracting 3 days and 2 hours:", result)

Current time: 2023-06-12T13:21:58.461996+05:30
After subtracting 3 days and 2 hours: 2023-06-09T11:21:58.461996+05:30

format() Method

The format() method displays datetime in a specified format using format strings.

import pendulum

# Create a Pendulum instance
dt = pendulum.datetime(2023, 6, 12, 14, 19, 35, 123456, tz='UTC')

# Format in different ways
date_format = dt.format('YYYY-MM-DD')
time_format = dt.format('HH:mm:ss.SSSSSS')
datetime_format = dt.format('YYYY-MM-DD HH:mm:ss')
custom_format = dt.format('dddd, MMMM Do, YYYY [at] HH:mm A')

print("Date formatted:", date_format)
print("Time formatted:", time_format)
print("DateTime formatted:", datetime_format)
print("Custom format:", custom_format)

Date formatted: 2023-06-12
Time formatted: 14:19:35.123456
DateTime formatted: 2023-06-12 14:19:35
Custom format: Monday, June 12th, 2023 at 14:19 PM

period() Method

The period() method creates a Period object representing the duration between two datetime instances.

import pendulum

start_date = pendulum.datetime(2022, 6, 12)
end_date = pendulum.datetime(2023, 6, 12)

# Create period between two dates
period = pendulum.period(start_date, end_date)

print("Period in days:", period.days)
print("Period in hours:", period.hours)
print("Period in years:", period.years)
print("Total seconds:", period.total_seconds())

Period in days: 365
Period in hours: 8760
Period in years: 1
Total seconds: 31536000.0

parse() Method

The parse() method creates a Pendulum instance by parsing date/time strings. It automatically recognizes various formats.

import pendulum

# Parse different date/time formats
result1 = pendulum.parse("2023-06-12T15:30:48", tz="UTC")
result2 = pendulum.parse("2023-06-12 15:30:48")
result3 = pendulum.parse("June 12, 2023")

print("ISO format:", result1)
print("Standard format:", result2)
print("Natural format:", result3)

ISO format: 2023-06-12T15:30:48+00:00
Standard format: 2023-06-12T15:30:48+00:00
Natural format: 2023-06-12T00:00:00+00:00

in_timezone() Method

The in_timezone() method converts a datetime instance to a different timezone.

import pendulum

# Get current time in UTC
utc_time = pendulum.now("UTC")
print("Current UTC time:", utc_time)

# Convert to different timezones
kolkata_time = utc_time.in_timezone("Asia/Kolkata")
tokyo_time = utc_time.in_timezone("Asia/Tokyo")
new_york_time = utc_time.in_timezone("America/New_York")

print("Kolkata time:", kolkata_time)
print("Tokyo time:", tokyo_time)
print("New York time:", new_york_time)

Current UTC time: 2023-06-14T09:53:50.575082+00:00
Kolkata time: 2023-06-14T15:23:50.575082+05:30
Tokyo time: 2023-06-14T18:53:50.575082+09:00
New York time: 2023-06-14T05:53:50.575082-04:00

Comparison with Standard datetime

Conclusion

The Pendulum Module is an excellent replacement for Python's built-in datetime module, offering intuitive timezone handling, automatic string parsing, and a clean API. It's particularly valuable for applications dealing with international dates and times across multiple timezones.