How python-pendulum/pendulum works
Project Type and Purpose
• Type: Open-source library/tool for handling datetimes in Python, with an optional Rust extension for performance-critical parsing.
• Purpose: Provide a richer, timezone-aware DateTime and Duration API, seamless localization, ISO-8601 parsing, and a CLI utility for managing locale files.
Main Components
A. Python Core Library
– Modules under src/pendulum: datetime/date/time/duration/interval/parser/formatting/locales/mixins/utils.
– Relies on Python stdlib datetime and zoneinfo.
B. Rust Extension
– rust/Cargo.toml and rust/src: core Rust logic (constants, parsing, helpers).
– rust/src/python: Python FFI bindings that compile into a dynamic extension module.
– Exposes high-performance parsing routines to the Python core.
C. CLI Utility (“clock”)
– Top-level script clock (shell or Rust binary) used to generate locale scaffolding.
– Reads/writes src/pendulum/locales and writes files on disk.
D. Documentation Site
– docs/ directory with MkDocs config, markdown source in docs/docs, custom theme.
– Generates HTML outputs for the official website.
E. Test Suite & CI
– tests/ directory testing all core modules, parsing, localization, time-travel, benchmarks.
– .github/workflows: CI pipelines for tests, releases, performance metrics.
– tox.ini and Makefile orchestrate building, linting, testing.
F. Packaging & Distribution
– pyproject.toml for Poetry, rust/Cargo for the Rust crate, setup scripts in Makefile.
– Publishes Python wheels with embedded Rust extension to PyPI.
G. External Services
– GitHub Actions (CI), PyPI (distribution), CLDR database (locale source), optionally SQLite/MySQL for adapters.
Component Relationships & Data Flows
– Users import pendulum → calls Python core modules.
– Python core dispatches parsing to:
• Pure-Python parser (src/pendulum/parsing/iso8601.py), or
• Rust extension (via pyo3 bindings under rust/src/python) for performance.
– DateTime/Duration objects reference timezone data under locales and tz/data.
– CLI “clock” tool reads CLDR data, writes new locale directories into src/pendulum/locales.
– Documentation build reads docs/docs/*.md and theme assets to produce the website.
– CI pipelines trigger on GitHub Actions: run tests, build docs, build wheels.
Architectural Patterns & Design Principles
– Layered modular architecture: API layer → parsing layer → locale layer → underlying storage (zoneinfo).
– Polyglot extension pattern: Combine Python for high-level API, Rust for performance.
– Convention-over-configuration for locales (one folder per locale).
– Drop-in replacement: Pendulum types subclass stdlib datetime/timedelta.