pendulum
Drop-in datetime replacement with timezone support — extends Python's datetime with intuitive API, timezone handling, and human-friendly output. pendulum features: pendulum.now() for current time with automatic DST handling, pendulum.parse() for ISO 8601 and RFC 2822 parsing, DateTime.add()/subtract() for date arithmetic, DateTime.diff() returning Duration objects, Duration with in_seconds()/in_hours() methods, Period between two datetimes, is_past()/is_future()/is_today() predicates, for_humans() for natural language diffs, timezone() for IANA timezone lookup, datetime() factory, in_timezone() for conversion, and timezone-aware datetime replacing pytz.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Pure datetime library with Rust extension. No network calls. No security concerns beyond standard input validation. parse() with user-provided strings: validates format but does not execute code.
⚡ Reliability
Best When
Timezone-aware datetime operations requiring human-readable output and DST-safe arithmetic — pendulum provides the most ergonomic datetime API in Python.
Avoid When
Python 3.9+ where zoneinfo suffices, bulk date operations (use pandas), or simple humanizing (use humanize library).
Use Cases
- • Agent current time — import pendulum; now = pendulum.now('US/Eastern'); utc = pendulum.now('UTC'); print(now.to_iso8601_string()) — '2024-01-15T14:30:00-05:00'; agent gets timezone-aware current time; pendulum.now() is safe unlike naive datetime.now()
- • Agent date arithmetic — dt = pendulum.now(); future = dt.add(days=7, hours=2); past = dt.subtract(months=3); diff = future.diff(past) — Duration; agent computes date differences; diff() returns Duration with .in_days(), .in_hours(), .in_seconds(); add/subtract create new DateTime objects
- • Agent human-friendly diff — created = pendulum.parse('2024-01-01'); diff = pendulum.now().diff(created); print(diff.in_words()) — '1 month'; print(diff.for_humans()) — '1 month ago'; agent displays time differences in natural language; for_humans() includes 'ago'/'from now'
- • Agent parse flexible formats — dt1 = pendulum.parse('2024-01-15T14:30:00Z'); dt2 = pendulum.parse('Mon, 15 Jan 2024 14:30:00 +0000'); dt3 = pendulum.parse('2024-01-15', tz='US/Eastern') — parsing; agent parses various date string formats; tz= applies timezone to parsed date
- • Agent period between dates — start = pendulum.parse('2024-01-01'); end = pendulum.parse('2024-12-31'); period = pendulum.period(start, end); for dt in period.range('months'): print(dt.format('MMMM YYYY')) — month iteration; agent iterates over date ranges; range('days'/'weeks'/'months'/'years')
Not For
- • Python 3.9+ zoneinfo users — stdlib zoneinfo + datetime covers most timezone use cases without deps
- • Simple date display — for basic humanizing use the humanize library; pendulum is heavier
- • High-performance bulk processing — pendulum adds overhead vs stdlib datetime; for bulk date operations use pandas
Interface
Authentication
No auth — datetime library.
Pricing
pendulum is MIT licensed. Created by Sebastien Eustace. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ pendulum v3 broke v2 API — pendulum 3.x changed several APIs from v2; in_timezone() replaces in_tz(); Duration replaced Interval in some contexts; agent code upgrading from v2: review breaking changes; pendulum.parse() strict parameter default changed; pin version: pendulum>=3.0,<4.0
- ⚠ pendulum.DateTime is a datetime subclass — isinstance(pendulum.now(), datetime) is True; drop-in replacement works for most cases; exception: some libraries check type exactly (type(x) is datetime) which fails; agent code: convert to stdlib when needed: dt.replace(tzinfo=dt.tzinfo) — returns plain datetime
- ⚠ diff() returns Duration not timedelta — pendulum.now().diff(past) returns pendulum.Duration; in_seconds() for float seconds; in_days() for days; NOT .days .seconds like timedelta; agent code: if passing diff to stdlib code expecting timedelta: use as_timedelta() or compute seconds manually
- ⚠ parse() is strict by default in v3 — pendulum.parse('01/15/2024') raises ParserError (ambiguous format); must be ISO 8601 or RFC 2822 without explicit format; agent code: for non-standard formats use pendulum.from_format('01/15/2024', 'MM/DD/YYYY'); or arrow which is more flexible in parsing
- ⚠ timezone names must be IANA — pendulum.timezone('US/Eastern') or pendulum.timezone('America/New_York'); 'EST' raises InvalidTimezone; agent code: use IANA names; pendulum.timezones lists all valid names; abbreviations like EST/PST are not valid timezone names
- ⚠ period.range() end is exclusive — pendulum.period(start, end).range('days') yields start but not end; for inclusive end: range to end.add(days=1) or use <= condition; agent code: test range boundaries explicitly; 7-day range from Monday to next Monday: period(monday, monday.add(weeks=1)).range('days') — 7 days
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for pendulum.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-06.