Skip to content

zen-xu/atomic-clock

Repository files navigation

AtomicClock: Better, Faster dates & times for Python

Arrow is a very awesome library for date, time and timezone handling. BUT, it is very slow. Because it is a python builtin datetime module wrapper, so it will cost more time to process.

So I create the AtomicClock. It implements most of Arrow features, and it is super fast (nearly x10).

One more thing: AtomicClock has no other dependencies, it has builtin Tz and RelativeDelta. So you don't need packages like pytz or dateutil.

Features

  • Fully-implemented, drop-in replacement for datetime
  • Support for Python 3.7+
  • Timezone-aware and UTC by default
  • Super-simple creation options for many common input scenarios
  • shift method with support for relative offsets, including weeks
  • Format and parse strings automatically
  • Wide support for the ISO 8601 standard
  • Timezone conversion
  • Support for dateutil, pytz, and ZoneInfo tzinfo objects
  • Generates time spans, ranges, floors and ceilings for time frames ranging from microsecond to year
  • Humanize dates and times with a growing list of contributed locales (no plan)
  • Extensible for your own Arrow-derived types
  • Full support for PEP 484-style type hints

Quick Start

Installation

$ pip install -U atomic-clock

Example Usage

>>> import atomic_clock
>>> atomic_clock.get("2022-04-06T23:10:39.503909+08:00")
... <AtomicClock [2022-04-06T23:10:39.503909+08:00]>

>>> utc = atomic_clock.utcnow()
>>> utc
... <AtomicClock [2022-04-06T15:12:36.641201+00:00]>

>>> utc = utc.shift(hours=-1)
>>> utc
... <AtomicClock [2022-04-06T14:12:36.641201+00:00]>

>>> local = utc.to("Asia/Shanghai")
>>> local
... <AtomicClock [2022-04-06T22:12:36.641201+08:00]>

>>> local.timestamp()
... 1649254356.641201

>>> local.format()
... '2022-04-06 22:12:36+08:00'

>>> local.format("%Y-%m-%d %H:%M:%S %:z")
... '2022-04-06 22:12:36 +08:00'