Reference implementations

ATS ships two reference implementations: Python (code/ats.py) and JavaScript (docs/assets/js/ats.js). Both round-trip every test-vectors-*.json file bit-identically. Rust and Go are planned for v1.0 (see ROADMAP V1.0-B and versioning §7.2 (3)); third-party implementations in any language are welcome under the conformance contract (manifesto §16.5).

License: MIT (see GOVERNANCE.md §8). Authoritative source: the manifest (manifesto.en.md) and the conformance vectors. The code shown below is one conformant implementation, not the spec.

1. Install (planned, v1.0)

The installable artefacts are not yet published — see versioning §7.2 (4) for the v1.0 release commitment. In the meantime, vendor the file directly:

# Python — vendor the file (no install required)
curl -O https://raw.githubusercontent.com/s-geffroy/ATS/main/code/ats.py

# JavaScript — vendor the file
curl -O https://raw.githubusercontent.com/s-geffroy/ATS/main/docs/assets/js/ats.js

# Planned (v1.0):
# pip install ats-time
# npm install @s-geffroy/ats

Download ats.py · Download ats.js · Browse on GitHub

2. Quick usage

Python

from datetime import datetime, timezone
from ats import gregorian_to_ats, ats_to_gregorian

now = datetime.now(timezone.utc)
ats = gregorian_to_ats(now)
print(ats.to_canonical())   # T+ Δ 20.7.8.4.50000
print(ats.to_short())       # Δ20.7.8.4-50.0

back = ats_to_gregorian(ats.to_canonical())
print(back.isoformat())     # 2026-06-15T12:00:00+00:00 (±432 ms)

JavaScript (browser or Node)

import { atsFromMs, toCanonical, toShort, atsToMs } from './ats.js';

const v = atsFromMs(Date.now());
console.log(toCanonical(v));   // T+ Δ 20.7.8.4.50000
console.log(toShort(v));       // Δ20.7.8.4-50.0

const back = atsToMs(toCanonical(v));
console.log(new Date(back).toISOString());  // round-trip ±432 ms

3. Conformance — one-liner (Docker)

Any third-party implementation MUST round-trip every test-vectors-*.json file bit-identically at the spec_version it claims to target (see versioning §2). Run the reference test suites without installing anything locally:

# Python — 12 core vectors + arithmetic + 5 calendar bridges + 2 multi-planetary
docker run --rm -v "$(pwd):/app" -w /app python:3.11-slim \
  python -m unittest discover tests

# JavaScript — 12 core vectors
docker run --rm -v "$(pwd):/app" -w /app node:20-slim \
  node tests/test_vectors.mjs

# Combined run + property-based (Hypothesis 1000+ instants)
docker run --rm -v "$(pwd):/app" -w /app python:3.11-slim \
  sh -c 'pip install -q hypothesis && python -m unittest discover tests'

All three commands MUST exit 0. Any non-zero exit is a conformance failure.

4. Module structure

File	Role	Spec reference
`code/ats.py`	Core: Gregorian ↔ ATS, canonical/short formats, §11.4 algebra	manifesto §9–§11
`code/ats_multi_planetary.py`	Multi-planetary extension: Earth, Mars, Moon	multi-planetary.en.md
`code/bridges/hebrew.py`	Hebrew calendar bridge (`convertdate`)	manifesto §14
`code/bridges/islamic.py`	Islamic calendar bridge (`convertdate`)	idem
`code/bridges/chinese.py`	Chinese calendar bridge (`lunardate`, HKO tables 1900–2100)	idem
`code/bridges/hindu.py`	Hindu calendar bridge (panchanga regional approximation)	idem
`code/bridges/maya.py`	Maya Long Count bridge	idem
`docs/assets/js/ats.js`	JavaScript core (browser + Node, ES modules)	same as `ats.py`
`docs/assets/js/ats-clock.js`	Web Component `<ats-clock>`	analog-clock.en.md

5. Status of other languages

Rust — planned for v1.0 (see ROADMAP V1.0-B); target crate ats on crates.io, no_std-friendly, core + algebra + canonical/short parsers, optional bridges.
Go — alternative to Rust for v1.0 (see ROADMAP V1.0-B); target module github.com/s-geffroy/ats, server / CLI / cloud-infra audience.
Kotlin, Swift, Elixir — not on the v1.0 critical path; welcomed as third-party implementations under the conformance contract.

6. Full Python source

Inlined live from GitHub raw with a local fallback. License: MIT (GOVERNANCE.md §8.1).

Loading…