Hifitime

4.3.0 verified Sat May 09 auth: no python

Hifitime is a high-precision time and date library for Python, built on top of the Rust `hifitime` crate. It provides nanosecond-level precision, support for time scales (TAI, UTC, TT, etc.), durations, and astronomical time functions. Current version is 4.3.0, requiring Python >=3.9. Releases are frequent, with semver updates.

pip install hifitime

Common errors

error AttributeError: module 'hifitime' has no attribute 'Epoch' ↓

cause Importing incorrectly, e.g., `import hifitime` and then trying `hifitime.Epoch`.

fix

Use from hifitime import Epoch instead.

error ValueError: unknown time scale: GPS ↓

cause Using deprecated or removed time scale name.

fix

Use TimeScale.GPST instead of TimeScale.GPS.

error AttributeError: 'Epoch' object has no attribute 'to_datetime' ↓

cause Trying to convert to Python datetime; that method may not exist in v4.

fix

Use epoch.to_gregorian_str() or convert via seconds: datetime.utcfromtimestamp(epoch.to_unix_seconds()).

Warnings

gotcha By default, `Epoch` uses TAI (International Atomic Time) internally. All arithmetic and comparisons are in TAI. To work in UTC, explicitly specify the time scale. ↓

fix Use `Epoch.from_gregorian_str(s, TimeScale.UTC)` or pass the time scale parameter.

breaking Prior to version 3.0, the library used a different API (e.g., `epoch.tai_seconds()`). In v3+, methods are renamed and the internal representation changed. ↓

fix Update to use new API: e.g., `epoch.to_tai_seconds()`. Refer to the migration guide.

gotcha Leap seconds are handled automatically in conversions between TAI and UTC. However, the library does not expose historical leap second tables directly; it relies on the bundled data. Always update the library to get the latest leap second information. ↓

fix Keep hifitime updated to the latest version to ensure correct leap second handling.

deprecated The `TimeScale.GPS` is deprecated in favor of `TimeScale.GPST` (GPS Time). ↓

fix Use `TimeScale.GPST` instead of `TimeScale.GPS`.

Imports

Epoch
```
from hifitime import Epoch
```
Duration
```
from hifitime import Duration
```
TimeScale
```
from hifitime import TimeScale
```

Quickstart

Basic usage: create an epoch, perform time arithmetic, and convert to string.

from hifitime import Epoch, Duration, TimeScale

# Create an epoch from a UTC string
e = Epoch.from_gregorian_str("2023-10-01T00:00:00", TimeScale.UTC)
print(e)  # Epoch { ... }

# Add duration
d = Duration.from_hours(1.5)
epoch2 = e + d
print(epoch2)

# Convert to different time scale
print(epoch2.to_utc_str())