Pendulum Library in Python

In this tutorial, we will learn about the Python pendulum library. We will discuss its feature and usage. Python provides the datetime module, one of the most important libraries to work with date and time, and it is very flexible and comes with many useful methods.

However, the datetime module has some limitations, like failing in different time zones. Sometimes, we need to import the third-party library as supplements, and we need to import the pytz third-party library to perform those tasks that datetime can't perform. So we have a solution in the form of a pendulum library. Let's understand Python's pendulum library.

Introduction

The pendulum library is a date and time manipulation library for Python that provides a more intuitive and easier-to-use interface than the built-in datetime module.

Features of Pendulum Library

• Timezone support: It supports over 500 time zones, including DST transitions and historical timezone information.
• Fluent interface: It allows you to chain methods to create complex date and time objects more readably and intuitively.
• Human-friendly parsing: It can parse natural language strings like "next Friday at 3pm" into a DateTime object.
• Time arithmetic: It allows you to perform arithmetic operations with dates and times, such as adding or subtracting days or hours.
• Date formatting: It provides a powerful formatting system for outputting dates and times in various formats.

We can install it using the below command.

Now, we import the pendulum library to check it is properly installed or not.

The pendulum name seems long, so we imported it as pdl.

Let's create the datetime object using the pendulum and look at its object type.

Example -

Output:

True

While pendulum offers a more intuitive and easier-to-use interface for working with dates and times in Python, it's important to note that pendulum actually inherits from the built-in datetime module. It means that the pendulum includes all of the features and functionality of datetime, and we can use the original datetime methods and attributes with a pendulum datetime object.

In other words, a pendulum datetime object is a Python datetime object with additional features and methods provided by the pendulum library. So if you are familiar with working with datetime objects in Python, you can use that knowledge when working with a pendulum.

Working with Timezone

One of the most powerful features of the pendulum library is its support for time zones, and it is a critical area where the built-in datetime module can be challenging to work with. Prior to Python 3.9, in order to work with IANA timezones, one had to rely on third-party libraries like pytz.

With pendulum, you can easily work with over 500 timezones, including historical timezone data and support for DST transitions. It makes it significantly easier to handle date and time calculations across different timezones and convert between them without running into errors or unexpected behavior.

Let's understand the following example.

Example -

Output:

2021-11-06T00:00:00+11:00
2021-11-06T00:00:00+10:00
2023-02-23T19:14:26.647322+05:30
2023-02-23T14:44:26.647322+01:00

Explanation -

First, we create a pendulum datetime object with the local timezone using the now() method. Then, we create another datetime object in the Australia/Melbourne timezone and a third datetime object in the Australia/Queensland timezone.

The first two datetime objects represent the same moment (midnight on November 6th, 2021), but in different timezones (Australia/Melbourne and Australia/Queensland).

The second two datetime objects represent the current moment (when the code is executed), but again in different timezones (the local timezone and Europe/Paris).

Datetime Parsing

One of the most common tasks in programming is parsing a datetime. While the built-in datetime module in Python is well-suited to this task, it's worth noting that Python uses a different format for datetime strings than many other programming languages. Specifically, Python uses the %Y%m%d format for dates, which is not the most common format used in other languages.

We can parse the date using the from_format() method.

Example -

Output:

DateTime(2023, 11, 3, 21, 0, 0, tzinfo=Timezone('UTC'))

In addition, to its support for the %Y%m%d format, the pendulum module in Python also provides full support for other common datetime formats, such as RFC 3339 and ISO 8601. It means we can parse datetime strings in these formats without manually specifying the format codes. It can be a big time-saver when working with datetime strings in Python.

Example -

Output:

DateTime(2022, 12, 3, 22, 0, 0, tzinfo=Timezone('UTC'))

Apart from these, Pendulum supports much more formats on the fly. For example - The datetime with numbers only.

Example -

Output:

DateTime(2023, 9, 5, 0, 0, 0, tzinfo=Timezone('UTC'))

An interesting feature of the pendulum library is that it can create a datetime object from a year, week number, and day of the week. This can be accomplished using the datetime method, as shown in the following code example.

Example -

Output:

DateTime(2022, 11, 5, 0, 0, 0, tzinfo=Timezone('UTC'))

We can get date object or time object particularly, we need to specify exact=True, which is quite easier than datetime.

Output:

Date(2023, 11, 29)
Time(22, 0, 0)

String Formatting

We can also format the given string using the pendulum. We will perform the datetime into strings with formats.

First, we create the datetime object using the now() method.

DateTime(2023, 2, 24, 18, 12, 58, 297781, tzinfo=Timezone('Asia/Calcutta'))

Below is some example of to string method from pendulum.

Example -

Output:

'2023-02-24'
'18:12:58'
'Feb 24, 2023'
'Fri, Feb 24, 2023 6:12 PM'
'2023-02-24T18:12:58.297781+05:30'
'2023-02-24T18:12:58+05:30'
'Friday, 24-Feb-2023 18:12:58 IST'

We can also format some random words into format string and have them escape from the format.

Output:

'Hi! Today is 24 February, 2023 Friday 18:12:58 PM'

Find Relative Datetime

There is room for improvement in the built-in Python datetime module when it comes to finding relative datetime based on a given one. For instance, in order to determine the last day of the current month using the built-in module, we must use relativedelta from the datetutil module. Let's understand the following example.

Example -

Output:

datetime.datetime(2023, 2, 28, 0, 0)

Furthermore, the code using the built-in module can be difficult to read since we pass day=31 as the argument, even though this approach may work for months with fewer than 31 days.

It can be done easier using pendulum.

Example -

Output:

DateTime(2023, 2, 24, 0, 0, 0, tzinfo=Timezone('Asia/Calcutta'))
DateTime(2023, 2, 1, 0, 0, 0, tzinfo=Timezone('Asia/Calcutta'))
DateTime(2023, 2, 24, 23, 59, 59, 999999, tzinfo=Timezone('Asia/Calcutta'))
DateTime(2023, 2, 28, 23, 59, 59, 999999, tzinfo=Timezone('Asia/Calcutta'))

The datetime module also lack in finding the day of a week. For example - We want to find the day of next Tuesday, we can do in datetime as following.

Example -

Output:

datetime.datetime(2023, 2, 27, 18, 42, 48, 88371)

As we can see that, the above code is bit complex and developer needs to spend some time to understand it. We can do it with the pendulum easily.

Example -

Output:

DateTime(2023, 2, 28, 0, 0, 0, tzinfo=Timezone('Asia/Calcutta'))

With Pendulum, we do not have to worry about whether we should use 0 or 1 to indicate Tuesday, since it uses enumeration for this purpose.

The pendulum library also provide the previous() method to get the previous Monday. We can keep the time part by setting the argument keep_time=True.

Example -

Output:

DateTime(2023, 2, 21, 18, 54, 6, 591922, tzinfo=Timezone('Asia/Calcutta'))
DateTime(2023, 2, 21, 0, 0, 0, tzinfo=Timezone('Asia/Calcutta'))

Human Readable

The built-in Python datetime module offers the timedelta tool which effectively performs comparison tasks. Nevertheless, Pendulum has the potential to enhance this feature by providing more user-friendly output when comparing two datetime objects.

As an illustration, the diff_for_humans() method in Pendulum can be used to compare a datetime object with the current time and produce an output that is easily understandable by humans.

Example -

Output:

'in 5 days'
'1 year ago'

Conclusion

In conclusion, the pendulum library is a powerful and intuitive tool for working with datetime information in Python. It provides a range of features that make it easier to handle common datetime-related tasks, such as finding relative dates and times, working with timezones, and parsing datetime strings in a variety of formats. Compared to the built-in datetime module, pendulum provides a cleaner and more intuitive API, which can improve the readability and maintainability of code that deals with datetime information. Overall, pendulum is a valuable addition to the Python ecosystem, and it's worth considering for any project that involves working with datetime information.