# python-pendulum/pendulum architecture

> Architecture diagram of the GitHub repository python-pendulum/pendulum, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/python-pendulum/pendulum
- Repository: https://github.com/python-pendulum/pendulum

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User("User"):::external

    %% Core Library
    subgraph "Core Library"
        direction TB
        DateModule["pendulum/date.py"]:::python
        DateTimeModule["pendulum/datetime.py"]:::python
        TimeModule["pendulum/time.py"]:::python
        DurationModule["pendulum/duration.py"]:::python
        IntervalModule["pendulum/interval.py"]:::python
        ParserModule["pendulum/parser.py"]:::python
        ISOParser["pendulum/parsing/iso8601.py"]:::python
        Formatter["pendulum/formatting/formatter.py"]:::python
        DiffFormatter["pendulum/formatting/difference_formatter.py"]:::python
        Locales["pendulum/locales/"]:::python
        TimeZone["pendulum/tz/"]:::python
    end

    %% Rust Extension
    subgraph "Rust Extension"
        direction TB
        CargoToml["rust/Cargo.toml"]:::rust
        LibRs["rust/src/lib.rs"]:::rust
        Consts["rust/src/constants.rs"]:::rust
        Helpers["rust/src/helpers.rs"]:::rust
        ParsingRs["rust/src/parsing.rs"]:::rust
        subgraph "Python FFI Bindings"
            direction TB
            ModRs["rust/src/python/mod.rs"]:::rust
            PyParsing["rust/src/python/parsing.rs"]:::rust
            PyHelpers["rust/src/python/helpers.rs"]:::rust
            TypesDir["rust/src/python/types/"]:::rust
        end
    end

    %% CLI Utility
    CLI["clock"]:::cli

    %% Documentation
    subgraph "Documentation"
        direction TB
        MkDocs["docs/mkdocs.yml"]:::docs
        DocsSrc["docs/docs/"]:::docs
        Theme["docs/theme/main.html"]:::docs
        DocsMakefile["docs/Makefile"]:::docs
    end

    %% Tests & CI
    subgraph "Tests & CI"
        direction TB
        TestsDir["tests/"]:::testci
        CI_Tests[".github/workflows/tests.yml"]:::testci
        CI_Release[".github/workflows/release.yml"]:::testci
        CI_Codspeed[".github/workflows/codspeed.yml"]:::testci
        ToxIni["tox.ini"]:::testci
        MakefileTests["Makefile"]:::testci
    end

    %% Packaging & Distribution
    subgraph "Packaging & Distribution"
        direction TB
        PyProject["pyproject.toml"]:::python
        CargoToml2["rust/Cargo.toml"]:::rust
        PackageMakefile["Makefile"]:::python
        CargoConfig["rust/.cargo/config.toml"]:::rust
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GitHubActions("GitHub Actions"):::external
        PyPI("PyPI"):::external
        CLDR("CLDR Database"):::external
    end

    %% Connections
    User -->|"imports"| DateTimeModule
    DateTimeModule -->|uses| DateModule
    DateTimeModule -->|uses| TimeModule
    DateTimeModule -->|creates| DurationModule
    DateTimeModule -->|creates| IntervalModule
    ParserModule -->|parses| ISOParser
    ParserModule -->|calls| PyParsing
    ISOParser -->|fallback| ParsingRs
    LibRs -->|exports| PyParsing
    ParserModule -->|calls| ParsingRs
    Formatter -->|formats| DateTimeModule
    DiffFormatter -->|formats| DurationModule
    DateTimeModule -->|uses| Locales
    DateTimeModule -->|uses| TimeZone
    CLI -->|reads/writes| Locales
    CLI -->|reads| CLDR
    MkDocs -->|builds| DocsSrc
    DocsSrc -->|theme| Theme
    TestsDir -->|runs| DateTimeModule
    TestsDir -->|runs| ParserModule
    TestsDir -->|runs| CLI
    GitHubActions -->|runs| CI_Tests
    GitHubActions -->|runs| CI_Release
    GitHubActions -->|runs| CI_Codspeed
    CI_Tests -->|executes| TestsDir
    CI_Release -->|publishes| PyPI
    CI_Codspeed -->|measures| TestsDir
    PyProject -->|defines| PackageMakefile
    PackageMakefile -->|builds| CargoToml2
    CargoToml2 -->|reads| CargoConfig

    %% Publishing Flow
    PackageMakefile -->|build wheel| PyPI

    %% Click Events
    click DateModule "https://github.com/python-pendulum/pendulum/blob/master/src/pendulum/date.py"
    click DateTimeModule "https://github.com/python-pendulum/pendulum/blob/master/src/pendulum/datetime.py"
    click TimeModule "https://github.com/python-pendulum/pendulum/blob/master/src/pendulum/time.py"
    click DurationModule "https://github.com/python-pendulum/pendulum/blob/master/src/pendulum/duration.py"
    click IntervalModule "https://github.com/python-pendulum/pendulum/blob/master/src/pendulum/interval.py"
    click ParserModule "https://github.com/python-pendulum/pendulum/blob/master/src/pendulum/parser.py"
    click ISOParser "https://github.com/python-pendulum/pendulum/blob/master/src/pendulum/parsing/iso8601.py"
    click Formatter "https://github.com/python-pendulum/pendulum/blob/master/src/pendulum/formatting/formatter.py"
    click DiffFormatter "https://github.com/python-pendulum/pendulum/blob/master/src/pendulum/formatting/difference_formatter.py"
    click Locales "https://github.com/python-pendulum/pendulum/tree/master/src/pendulum/locales/"
    click TimeZone "https://github.com/python-pendulum/pendulum/tree/master/src/pendulum/tz/"
    click CargoToml "https://github.com/python-pendulum/pendulum/blob/master/rust/Cargo.toml"
    click LibRs "https://github.com/python-pendulum/pendulum/blob/master/rust/src/lib.rs"
    click Consts "https://github.com/python-pendulum/pendulum/blob/master/rust/src/constants.rs"
    click Helpers "https://github.com/python-pendulum/pendulum/blob/master/rust/src/helpers.rs"
    click ParsingRs "https://github.com/python-pendulum/pendulum/blob/master/rust/src/parsing.rs"
    click ModRs "https://github.com/python-pendulum/pendulum/blob/master/rust/src/python/mod.rs"
    click PyParsing "https://github.com/python-pendulum/pendulum/blob/master/rust/src/python/parsing.rs"
    click PyHelpers "https://github.com/python-pendulum/pendulum/blob/master/rust/src/python/helpers.rs"
    click TypesDir "https://github.com/python-pendulum/pendulum/tree/master/rust/src/python/types/"
    click CLI "https://github.com/python-pendulum/pendulum/tree/master/clock"
    click MkDocs "https://github.com/python-pendulum/pendulum/blob/master/docs/mkdocs.yml"
    click DocsSrc "https://github.com/python-pendulum/pendulum/tree/master/docs/docs/"
    click Theme "https://github.com/python-pendulum/pendulum/blob/master/docs/theme/main.html"
    click DocsMakefile "https://github.com/python-pendulum/pendulum/tree/master/docs/Makefile"
    click TestsDir "https://github.com/python-pendulum/pendulum/tree/master/tests/"
    click CI_Tests "https://github.com/python-pendulum/pendulum/blob/master/.github/workflows/tests.yml"
    click CI_Release "https://github.com/python-pendulum/pendulum/blob/master/.github/workflows/release.yml"
    click CI_Codspeed "https://github.com/python-pendulum/pendulum/blob/master/.github/workflows/codspeed.yml"
    click ToxIni "https://github.com/python-pendulum/pendulum/blob/master/tox.ini"
    click MakefileTests "https://github.com/python-pendulum/pendulum/tree/master/Makefile"
    click PyProject "https://github.com/python-pendulum/pendulum/blob/master/pyproject.toml"
    click CargoToml2 "https://github.com/python-pendulum/pendulum/blob/master/rust/Cargo.toml"
    click PackageMakefile "https://github.com/python-pendulum/pendulum/tree/master/Makefile"
    click CargoConfig "https://github.com/python-pendulum/pendulum/blob/master/rust/.cargo/config.toml"

    %% Styles
    classDef python fill:#add8e6,stroke:#000,stroke-width:1px
    classDef rust fill:#f08080,stroke:#000,stroke-width:1px
    classDef cli fill:#90ee90,stroke:#000,stroke-width:1px
    classDef docs fill:#ffa500,stroke:#000,stroke-width:1px
    classDef testci fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef external fill:#fff,stroke:#000,stroke-width:1px,stroke-dasharray:5 5
```
