# Pendulum — Python Datetimes Made Easy

> Pendulum is a drop-in replacement for Python's datetime module that provides a cleaner API for timezone handling, duration arithmetic, and human-friendly formatting.

## Install

Save as a script file and run:

# Pendulum — Python Datetimes Made Easy

## Quick Use
```bash
pip install pendulum

import pendulum

now = pendulum.now("America/New_York")
print(now.to_iso8601_string())
print(now.diff_for_humans())  # "just now"

dt = pendulum.parse("2024-03-15T10:30:00", tz="UTC")
print(dt.in_tz("Asia/Tokyo").format("YYYY-MM-DD HH:mm zz"))
```

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

---
Source: https://tokrepo.com/en/workflows/asset-e719641c
Author: Script Depot