Pendulum — Python Datetimes Made Easy

Introduction

Pendulum extends Python's datetime with an intuitive API that makes timezone conversions, period calculations, and localized formatting straightforward. It resolves common pitfalls around DST transitions, duration vs. period semantics, and timezone-naive comparisons.

What Pendulum Does

• Provides timezone-aware datetime objects with intuitive conversion methods
• Distinguishes between absolute Duration and calendar-aware Period for arithmetic
• Offers human-readable relative time formatting in 50+ locales
• Parses ISO 8601, RFC 2822, and common date strings automatically
• Drops in as a replacement for stdlib datetime with full compatibility

Architecture Overview

Pendulum wraps Python's datetime class, adding timezone resolution via the IANA/Olson database. Its DateTime subclass overrides arithmetic operators to return Pendulum objects. Duration and Period classes separate fixed-length intervals from calendar-sensitive spans, avoiding the ambiguity of timedelta for month/year math.

Self-Hosting & Configuration

• Install via pip; includes compiled timezone database (no system tz dependency)
• Set default timezone with pendulum.set_local_timezone()
• Configure default locale with pendulum.set_locale("fr")
• Use pendulum.instance() to convert existing datetime objects
• Integrates with SQLAlchemy, Django, and Pydantic via custom type adapters

Key Features

• Timezone conversion with in_tz() that correctly handles DST transitions
• Period arithmetic that respects calendar months and years
• Built-in localization for relative and absolute formatting in 50+ languages
• Strict and lenient parsing modes for varied input formats
• Immutable objects preventing accidental mutation bugs

Comparison with Similar Tools

• datetime (stdlib) — verbose timezone handling; Pendulum wraps it with a cleaner API
• Arrow — similar goals but Pendulum has stricter duration semantics and better DST handling
• dateutil — powerful parser and rrule but not a datetime replacement
• Day.js / Moment.js — JavaScript equivalents; Pendulum is the Python analog

FAQ

Q: Is Pendulum a drop-in for datetime? A: Mostly yes. Pendulum DateTime inherits from datetime, so it works with code expecting datetime objects. Some edge cases around pickle or type checks may need attention.

Q: How does Pendulum handle DST? A: Pendulum uses the IANA timezone database and correctly adjusts during transitions. Creating a time in an ambiguous DST window raises an exception unless you specify pre/post transition.

Q: What is the difference between Duration and Period? A: Duration is a fixed amount of time (like timedelta). Period is the difference between two DateTime instances and knows about months/years contextually.

Q: Does Pendulum work with Pydantic? A: Yes. Use Pendulum's DateTime type in Pydantic models with a custom validator or the pendulum-pydantic integration package.

Sources

• https://github.com/sdispater/pendulum
• https://pendulum.eustace.io