Arrow

Arrow is a Python library that offers a single, sensible Arrow object as a drop-in replacement for the standard library’s fragmented datetime/time/calendar/dateutil/pytz landscape. It provides timezone-aware-by-default dates, simple creation from many input formats, ISO 8601 parsing, humanized relative-time strings, and a fluent shift() API for relative offsets.

Inspired by moment.js and Requests, Arrow is one of the most widely used third-party date/time libraries in the Python ecosystem, valued for collapsing several stdlib modules and types into one intuitive interface.

What You Get

• A single Arrow type that’s a fully-implemented, drop-in replacement for datetime
• Timezone-aware and UTC-by-default handling, with dateutil, pytz, and zoneinfo support
• Wide ISO 8601 parsing and flexible string formatting/parsing
• A shift() method for relative time offsets, including weeks
• Humanized, locale-aware relative time strings ('an hour ago') with a growing list of contributed locales

Common Use Cases

• Parsing and formatting dates/timestamps from APIs or user input without juggling multiple stdlib modules
• Displaying human-friendly relative timestamps (e.g. ‘an hour ago’) in an application UI
• Converting and comparing timestamps across timezones consistently
• Generating time spans, floors, and ceilings for reporting or scheduling logic

Under The Hood

Architecture - The library’s public surface is a small set of modules — arrow.py (the core Arrow class), factory.py (the ArrowFactory used by the top-level arrow.get/arrow.now functions), parser.py, formatter.py, and locales.py — with the Arrow class itself subclassing behavior around Python’s native datetime rather than reimplementing date math from scratch. Tech Stack - Pure Python (99.8% of the codebase) with python-dateutil as its main runtime dependency, supporting Python 3.8+, formatted with Black, and packaged via standard setuptools/PyPI tooling. Code Quality - The tests/ directory mirrors each core module (test_arrow.py, test_factory.py, test_formatter.py, test_locales.py, test_parser.py) with Codecov-tracked coverage and a tox/Makefile-driven CI matrix across Python versions and lint checks. API Design - Arrow deliberately optimizes for discoverability and low ceremony (arrow.get(...), .shift(hours=-1), .humanize()), trading some of the stdlib’s low-level flexibility for a consistently friendly, chainable API — a design explicitly modeled on moment.js and Requests.