tempoch-py

Python bindings for tempoch, providing astronomical time primitives backed by Rust through PyO3.

The Crates.io and docs.rs badges above refer to the underlying tempoch Rust crate used by these bindings.

Features

Julian Date and Modified Julian Date objects with full arithmetic
UTC conversion (ISO 8601 strings and Python datetime objects)
Time-scale conversion between 11 astronomical scales (JD, MJD, TT, TDB, TAI, TCG, TCB, GPS, UnixTime, UT, JDE)
Time periods (intervals) with duration, intersection, and containment
Python exceptions for errors (no raw FFI/status codes)
Pickle and hash support
All computation in Rust (no reimplementation in Python)
Reusable PyO3 interop for timezone-aware Python datetimes and Time<UTC>

Installation

The bindings are currently built from source. Clone the repository with its Rust submodule, create a Python environment, and install with Maturin:

git clone --recurse-submodules https://github.com/Siderust/tempoch-py.git
cd tempoch-py

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate

python -m pip install --upgrade pip maturin
maturin develop --release

To build a wheel instead:

maturin build --release
python -m pip install target/wheels/tempoch-*.whl

Quick Start

from tempoch import JulianDate, ModifiedJulianDate, TimePeriod, TimeScale, convert_timescale

# Julian Date basics
j2000 = JulianDate.j2000()          # J2000.0 epoch
print(j2000)                         # JulianDate(2451545.0)
print(j2000.to_utc())               # 2000-01-01T11:58:55...+00:00

# Modified Julian Date
mjd = j2000.to_mjd()                # ModifiedJulianDate(51544.5)
jd_back = mjd.to_jd()               # JulianDate(2451545.0)

# UTC conversion
jd = JulianDate.from_utc("2024-06-21T12:00:00Z")
dt = jd.to_datetime()               # Python datetime object (UTC)

# Arithmetic
tomorrow = j2000 + 1.0              # Add 1 day
diff = tomorrow - j2000             # 1.0 (days)

# Julian centuries since J2000
centuries = jd.julian_centuries()

# Time-scale conversion
tdb = convert_timescale(2451545.0, TimeScale.JD, TimeScale.TDB)
tai = convert_timescale(2451545.0, TimeScale.JD, TimeScale.TAI)

# Time periods
period = TimePeriod(59000.0, 59010.0)  # MJD-based
print(period.duration_days())           # 10.0
print(period.contains(59005.0))         # True

# Period intersection
p1 = TimePeriod(59000.0, 59010.0)
p2 = TimePeriod(59005.0, 59015.0)
overlap = p1.intersection(p2)           # TimePeriod(59005.0, 59010.0)

Rust / PyO3 interoperability

The package also builds an rlib named tempoch_py, so another PyO3 crate can reuse the canonical datetime boundary while depending on tempoch directly:

[dependencies]
pyo3 = { version = "0.29", features = ["extension-module"] }
tempoch = "0.7"
tempoch-py = { git = "https://github.com/Siderust/tempoch-py.git" }

use pyo3::prelude::*;
use tempoch::Time;

fn roundtrip<'py>(value: &Bound<'py, PyAny>) -> PyResult<Bound<'py, PyAny>> {
    let instant: Time<tempoch::UTC> = tempoch_py::interop::datetime_to_time(value)?;
    tempoch_py::interop::time_to_datetime(value.py(), instant)
}

datetime_to_time intentionally rejects naive datetimes. Aware datetimes with any valid UTC offset are normalized to UTC without converting through a floating-point POSIX timestamp. Context-aware variants are available for users that need to supply a specific tempoch::TimeContext, and period_to_datetimes converts both endpoints of a Period<UTC>.

The Python TimeScale enum retains its historical names. In the 0.7 model, JD, MJD, UnixTime, and GPS describe formats, while TT, TAI, TDB, TCG, TCB, and UT (UT1) describe physical scales. JDE remains a compatibility alias for a TT Julian Date.

API Reference

Classes

Class	Description
`JulianDate`	Julian Date (continuous day count)
`ModifiedJulianDate`	Modified Julian Date (JD − 2,400,000.5)
`TimePeriod`	Time interval defined by start/end MJD
`TimeScale`	Enum of astronomical time scales

JulianDate

Method	Description
`JulianDate(value)`	Create from day number
`JulianDate.j2000()`	J2000.0 epoch constant
`JulianDate.from_utc(str)`	Create from UTC string
`JulianDate.from_datetime(dt)`	Create from Python datetime
`.value`	Raw day number (float)
`.to_mjd()`	Convert to ModifiedJulianDate
`.to_utc()`	Convert to UTC string (ISO 8601)
`.to_datetime()`	Convert to Python datetime (UTC)
`.add_days(n)`	Add n days
`.difference(other)`	Days between two JDs
`.julian_centuries()`	Centuries since J2000.0
`.julian_years()`	Years since J2000.0
`.julian_millennia()`	Millennia since J2000.0

ModifiedJulianDate

Method	Description
`ModifiedJulianDate(value)`	Create from MJD day number
`ModifiedJulianDate.from_utc(str)`	Create from UTC string
`ModifiedJulianDate.from_datetime(dt)`	Create from Python datetime
`.value`	Raw MJD day number (float)
`.to_jd()`	Convert to JulianDate
`.to_utc()`	Convert to UTC string
`.to_datetime()`	Convert to Python datetime
`.add_days(n)`	Add n days
`.difference(other)`	Days between two MJDs

TimePeriod

Method	Description
`TimePeriod(start_mjd, end_mjd)`	Create from MJD values
`TimePeriod.from_mjd(start, end)`	Create from MJD objects
`TimePeriod.from_jd(start, end)`	Create from JD objects
`TimePeriod.from_utc(start, end)`	Create from UTC strings
`.start` / `.end`	Start/end as ModifiedJulianDate
`.start_mjd` / `.end_mjd`	Start/end as float
`.duration_days()`	Duration in days
`.duration_hours()`	Duration in hours
`.duration_seconds()`	Duration in seconds
`.to_utc()`	Start/end as UTC strings
`.intersection(other)`	Intersection with another period
`.contains(mjd)`	Check if MJD is within period

Functions

Function	Description
`convert_timescale(value, from, to)`	Convert between time scales
`tai_minus_utc(jd)`	TAI − UTC leap seconds (seconds)
`intersect_periods(periods, bounds)`	Intersect period list with bounds

Exceptions

Exception	Base	Description
`NonFiniteTimeError`	`ValueError`	NaN or infinite time value
`InvalidIntervalError`	`ValueError`	Period start after end
`ConversionError`	`ValueError`	UTC/scale conversion out of range

Time Scales

Scale	Description
`TimeScale.JD`	Julian Date (identity)
`TimeScale.JDE`	Julian Ephemeris Day
`TimeScale.MJD`	Modified Julian Date
`TimeScale.TDB`	Barycentric Dynamical Time
`TimeScale.TT`	Terrestrial Time
`TimeScale.TAI`	International Atomic Time
`TimeScale.TCG`	Geocentric Coordinate Time
`TimeScale.TCB`	Barycentric Coordinate Time
`TimeScale.GPS`	GPS Time
`TimeScale.UnixTime`	Unix/POSIX Time
`TimeScale.UT`	Universal Time (Earth rotation)

Relationship with tempoch

tempoch-py is a thin Python interface over the tempoch Rust crate. Core astronomical time calculations remain implemented in Rust; the Python layer focuses on idiomatic Python types, exceptions, and interoperability.

Rust crate: crates.io/crates/tempoch
Rust API documentation: docs.rs/tempoch

Development

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate

python -m pip install --upgrade pip maturin pytest ruff
maturin develop

# Python tests
pytest tests/ -v

# Rust tests
cargo test --all-targets

# Formatting and linting checks used by CI
cargo fmt --check
cargo clippy --all-targets -- -D warnings
ruff format --check python tests examples
ruff check python tests examples

License

AGPL-3.0 — see LICENSE.

tempoch-py 0.2.1