ursa.time

Canonical timestamp helpers for Ursa.

Absolute timestamps in the catalog are int64 nanoseconds since the Unix epoch (1970-01-01T00:00:00 UTC). This is the native unit for pa.timestamp( "ns", tz="UTC"), numpy.datetime64[ns], and pandas.Timestamp, and int64 covers 1677-09-21 through 2262-04-11.

See the Constellation Research Stack architecture plan §6.12 for the cross-package convention.

Module Contents

Functions

now_ns	Current wall-clock time as int64 nanoseconds since the Unix epoch.
ns_to_datetime	Convert int64 ns since Unix epoch to an aware UTC datetime.
datetime_to_ns	Convert an aware datetime to int64 ns since Unix epoch.

Data

__all__
INT64_MIN
INT64_MAX
_EPOCH

API

ursa.time.__all__

[‘INT64_MAX’, ‘INT64_MIN’, ‘datetime_to_ns’, ‘now_ns’, ‘ns_to_datetime’]

ursa.time.INT64_MIN

None

ursa.time.INT64_MAX

None

ursa.time.now_ns() → int

Current wall-clock time as int64 nanoseconds since the Unix epoch.

ursa.time.ns_to_datetime(ns: int) → datetime.datetime

Convert int64 ns since Unix epoch to an aware UTC datetime.

Lossy past microsecond precision: Python’s datetime cannot represent sub-microsecond values, so the final 3 digits of ns are truncated. For the ns-exact view, work with the integer directly.

ursa.time._EPOCH

‘datetime(…)’

ursa.time.datetime_to_ns(dt: datetime.datetime) → int

Convert an aware datetime to int64 ns since Unix epoch.

Naive datetimes are rejected. Any aware timezone is normalized to UTC before the multiply. Pre-1970 datetimes produce negative ns values.