0
# Pendulum
1
2
A comprehensive Python datetime library that provides timezone-aware datetime manipulation with an intuitive API. Pendulum serves as a drop-in replacement for Python's native datetime class while offering enhanced functionality including seamless timezone handling, natural language formatting, precise duration calculations, and proper handling of daylight saving time transitions.
3
4
## Package Information
5
6
- **Package Name**: pendulum
7
- **Package Type**: Library
8
- **Language**: Python
9
- **Installation**: `pip install pendulum`
10
11
## Core Imports
12
13
```python
14
import pendulum
15
```
16
17
For specific classes:
18
19
```python
20
from pendulum import DateTime, Date, Time, Duration, Interval
21
```
22
23
## Basic Usage
24
25
```python
26
import pendulum
27
28
# Create timezone-aware datetime (defaults to UTC)
29
dt = pendulum.now()
30
print(dt) # 2024-03-15T14:30:00+00:00
31
32
# Create datetime in specific timezone
33
paris_dt = pendulum.now('Europe/Paris')
34
print(paris_dt) # 2024-03-15T15:30:00+01:00
35
36
# Create datetime from components
37
dt = pendulum.datetime(2024, 3, 15, 14, 30, 0)
38
39
# Parse datetime strings
40
dt = pendulum.parse('2024-03-15T14:30:00')
41
dt = pendulum.from_format('2024-03-15 14:30', 'YYYY-MM-DD HH:mm')
42
43
# Date arithmetic with timezone awareness
44
tomorrow = dt.add(days=1)
45
last_week = dt.subtract(weeks=1)
46
47
# Human-readable differences
48
diff = dt.diff_for_humans() # "2 hours ago"
49
50
# Duration with years and months support
51
duration = pendulum.duration(years=1, months=2, days=3)
52
print(duration.in_words()) # "1 year 2 months 3 days"
53
54
# Timezone conversion
55
utc_dt = paris_dt.in_timezone('UTC')
56
local_dt = dt.in_timezone('local')
57
```
58
59
## Architecture
60
61
Pendulum's design centers around timezone-aware datetime objects with comprehensive manipulation capabilities:
62
63
- **DateTime/Date/Time Classes**: Core temporal objects with extensive manipulation methods
64
- **Duration/Interval**: Time spans with support for years/months (unlike standard timedelta)
65
- **Timezone Handling**: IANA timezone database integration with DST support
66
- **Parsing/Formatting**: Flexible string parsing and multiple output formats
67
- **Localization**: 200+ locales for human-readable formatting
68
- **Testing Utilities**: Time freezing and travel for deterministic testing
69
70
All datetime objects are timezone-aware by default (UTC if not specified), eliminating naive datetime issues while maintaining full compatibility with Python's datetime module.
71
72
## Capabilities
73
74
### DateTime Operations
75
76
Core datetime creation, manipulation, and timezone handling. Includes creating DateTime objects, timezone conversion, date arithmetic, and comparison operations.
77
78
```python { .api }
79
def now(tz: str | Timezone | FixedTimezone | None = None) -> DateTime: ...
80
def datetime(year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0, tz: str | float | Timezone | FixedTimezone | datetime.tzinfo | None = UTC, fold: int = 1, raise_on_unknown_times: bool = False) -> DateTime: ...
81
def local(year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0) -> DateTime: ...
82
def naive(year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0, fold: int = 1) -> DateTime: ...
83
def today(tz: str | Timezone = 'local') -> DateTime: ...
84
def tomorrow(tz: str | Timezone = 'local') -> DateTime: ...
85
def yesterday(tz: str | Timezone = 'local') -> DateTime: ...
86
def instance(obj: datetime.datetime | datetime.date | datetime.time, tz: str | None = None) -> DateTime | Date | Time: ...
87
def parse(string: str, **options) -> DateTime | Date | Time | Duration: ...
88
def from_format(string: str, fmt: str, tz: str | Timezone = UTC, locale: str | None = None) -> DateTime: ...
89
def from_timestamp(timestamp: int | float, tz: str = 'UTC') -> DateTime: ...
90
```
91
92
[DateTime Operations](./datetime-operations.md)
93
94
### Date and Time Components
95
96
Specialized classes for working with date-only and time-only values, providing targeted functionality for applications that don't need full datetime capabilities.
97
98
```python { .api }
99
def date(year: int, month: int, day: int) -> Date: ...
100
def time(hour: int, minute: int = 0, second: int = 0, microsecond: int = 0) -> Time: ...
101
```
102
103
[Date and Time Components](./date-time-components.md)
104
105
### Duration and Intervals
106
107
Time span calculations with support for years and months. Includes duration creation, interval operations, and human-readable formatting of time differences.
108
109
```python { .api }
110
def duration(days: float = 0, seconds: float = 0, microseconds: float = 0, milliseconds: float = 0, minutes: float = 0, hours: float = 0, weeks: float = 0, years: float = 0, months: float = 0) -> Duration: ...
111
def interval(start: DateTime, end: DateTime, absolute: bool = False) -> Interval: ...
112
```
113
114
[Duration and Intervals](./duration-intervals.md)
115
116
### Timezone Management
117
118
Comprehensive timezone handling with IANA database support, including timezone creation, conversion, and local timezone management for testing.
119
120
```python { .api }
121
def timezone(name: str | int) -> Timezone | FixedTimezone: ...
122
def local_timezone() -> Timezone: ...
123
def set_local_timezone(tz: str | Timezone) -> None: ...
124
def test_local_timezone(tz: str | Timezone): ...
125
def timezones() -> set[str]: ...
126
```
127
128
[Timezone Management](./timezone-management.md)
129
130
### Formatting and Localization
131
132
Multiple output formats and localization support for human-readable datetime representation across different cultures and languages.
133
134
```python { .api }
135
def format_diff(diff: Duration, is_now: bool = True, absolute: bool = False, locale: str | None = None) -> str: ...
136
def set_locale(name: str) -> None: ...
137
def get_locale() -> str: ...
138
def locale(name: str): ...
139
def week_starts_at(wday: WeekDay) -> None: ...
140
def week_ends_at(wday: WeekDay) -> None: ...
141
```
142
143
[Formatting and Localization](./formatting-localization.md)
144
145
### Testing Utilities
146
147
Time manipulation utilities for deterministic testing, including freezing time and traveling to specific moments.
148
149
```python { .api }
150
def freeze() -> None: ...
151
def travel(years: int = 0, months: int = 0, weeks: int = 0, days: int = 0, hours: int = 0, minutes: int = 0, seconds: int = 0, microseconds: int = 0) -> None: ...
152
def travel_to(dt: DateTime, freeze: bool = False) -> None: ...
153
def travel_back() -> None: ...
154
```
155
156
[Testing Utilities](./testing-utilities.md)
157
158
## Types
159
160
```python { .api }
161
class DateTime:
162
"""Timezone-aware datetime with extensive manipulation capabilities"""
163
164
class Date:
165
"""Date without time component"""
166
167
class Time:
168
"""Time without date component"""
169
170
class Duration:
171
"""Time duration with years/months support"""
172
173
class Interval:
174
"""Time interval between two DateTime objects"""
175
176
class Timezone:
177
"""IANA timezone representation"""
178
179
class FixedTimezone:
180
"""Fixed offset timezone representation"""
181
182
class WeekDay:
183
"""Weekday enumeration (MONDAY=0 through SUNDAY=6)"""
184
```
185
186
## Constants
187
188
```python { .api }
189
# Version information
190
__version__: str # Package version string
191
192
# Time unit constants
193
YEARS_PER_CENTURY: int = 100
194
YEARS_PER_DECADE: int = 10
195
MONTHS_PER_YEAR: int = 12
196
WEEKS_PER_YEAR: int = 52
197
DAYS_PER_WEEK: int = 7
198
HOURS_PER_DAY: int = 24
199
MINUTES_PER_HOUR: int = 60
200
SECONDS_PER_MINUTE: int = 60
201
SECONDS_PER_HOUR: int = 3600
202
SECONDS_PER_DAY: int = 86400
203
204
# Weekday constants
205
MONDAY: WeekDay
206
TUESDAY: WeekDay
207
WEDNESDAY: WeekDay
208
THURSDAY: WeekDay
209
FRIDAY: WeekDay
210
SATURDAY: WeekDay
211
SUNDAY: WeekDay
212
213
# Special timezone
214
UTC: Timezone
215
```