# arrow-py/arrow architecture

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

- Interactive diagram: https://gitdiagram.com/arrow-py/arrow
- Repository: https://github.com/arrow-py/arrow

## Overview

##### File structure
- Top-level directories & files:
- tests/            ← unit test suite
- docs/             ← user documentation
- requirements/     ← pinned dependencies
- CI and config files (GitHub Actions, tox.ini, setup.cfg, pyproject.toml, Makefile)
- api.py            ← module exposing the public API functions
- parser.py         ← parsing engine for a variety of date/time input formats (ISO 8601, timestamps, etc.)
- formatter.py      ← string‐formatting logic, pattern definitions
- locales.py        ← localizations for humanization (“an hour ago”, etc.)
- constants.py      ← shared constants (default formats, lookup tables)
- util.py           ← utility functions (time span generation, floor/ceiling operations)
- _version.py, __init__.py   ← package version & export points

##### README for additional insights
- The README emphasizes:
- Drop-in replacement for datetime
- Timezone-aware by default (supports `dateutil`, `pytz`, `ZoneInfo`)
- Parsing, shifting, formatting, ranges, humanization, extensibility
- PEP 484 type hints

##### Don’t overthink—capture these essential elements
- Consumer entry point and API façade
- Factory & parsing pipeline
- Formatter & localization subsystems
- External TZ back-ends
- Extension/customization hooks

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Consumer"
        Consumer["Library Consumer"] 
    end

    subgraph "API Facade"
        API["arrow.api"]:::api
    end

    subgraph "Core Modules"
        Factory["arrow.factory"]:::core
        Parser["arrow.parser"]:::core
        ArrowClass["arrow.Arrow"]:::core
        Formatter["arrow.formatter"]:::core
        Locales["arrow.locales"]:::core
        Util["arrow.util"]:::core
        Constants["arrow.constants"]:::core
        Version["_version"]:::core
        Typing["py.typed"]:::core
    end

    subgraph "External Dependencies"
        StdDateTime["datetime (stdlib)"]:::external
        Dateutil["dateutil"]:::external
        Pytz["pytz"]:::external
        ZoneInfo["zoneinfo"]:::external
    end

    subgraph "Side Artifacts"
        Tests["tests/"]:::side
        Docs["docs/"]:::side
    end

    Consumer -->|"import & call get()/utcnow()"| API
    API -->|"calls factory.parse()"| Factory
    Factory -->|"parses inputs"| Parser
    Parser -->|"returns datetime + tzinfo"| Factory
    Factory -->|"instantiates Arrow"| ArrowClass
    ArrowClass -->|"uses util functions"| Util
    ArrowClass -->|"uses constants"| Constants
    ArrowClass -->|"formats output"| Formatter
    ArrowClass -->|"humanizes output"| Locales
    ArrowClass -->|"shifts/converts via tz back-ends"| Dateutil
    ArrowClass -->|"shifts/converts via tz back-ends"| Pytz
    ArrowClass -->|"shifts/converts via tz back-ends"| ZoneInfo
    ArrowClass -->|"core uses stdlib"| StdDateTime
    Formatter -->|"uses format patterns"| Constants
    Locales -->|"uses localization data"| Constants

    click API "https://github.com/arrow-py/arrow/blob/master/arrow/api.py"
    click Factory "https://github.com/arrow-py/arrow/blob/master/arrow/factory.py"
    click Parser "https://github.com/arrow-py/arrow/blob/master/arrow/parser.py"
    click ArrowClass "https://github.com/arrow-py/arrow/blob/master/arrow/arrow.py"
    click Formatter "https://github.com/arrow-py/arrow/blob/master/arrow/formatter.py"
    click Locales "https://github.com/arrow-py/arrow/blob/master/arrow/locales.py"
    click Util "https://github.com/arrow-py/arrow/blob/master/arrow/util.py"
    click Constants "https://github.com/arrow-py/arrow/blob/master/arrow/constants.py"
    click Version "https://github.com/arrow-py/arrow/blob/master/arrow/_version.py"
    click Typing "https://github.com/arrow-py/arrow/blob/master/arrow/py.typed"
    click Tests "https://github.com/arrow-py/arrow/tree/master/tests/"
    click Docs "https://github.com/arrow-py/arrow/tree/master/docs/"

    classDef api fill:#e0ffe0,stroke:#333
    classDef core fill:#ddeeff,stroke:#333
    classDef external fill:#ffebcc,stroke:#333
    classDef side fill:#eeeeee,stroke:#333
```
