Timestamp

SUMMARY

A point in time relative to a clock epoch.

from telekinesis import datatypes
stamp = datatypes.Timestamp(sec=42, nanosec=250_000_000)

API Reference

Complete API documentation for Timestamp, including parameters, attributes, and methods.

View Reference →

Parameters

Parameter	Type	Default	Description
sec	int	Required	Whole seconds relative to the clock epoch. The epoch may represent system time, simulation time, or another source defined by the producer.
nanosec	int	0	Nanoseconds within the current second, in [0, 1_000_000_000).

Raises

Exception	Condition
TypeError	sec or nanosec is not an int, or is a bool
ValueError	nanosec is outside [0, 1_000_000_000)

Attributes

Attribute	Type	Description
sec	int	Whole-second offset relative to the clock epoch. Read-only — there is no setter; construct a new Timestamp to change the value.
nanosec	int	Nanosecond offset within the current second, in [0, 1_000_000_000). Read-only, same as sec.

Methods

Method	Type	Description
Timestamp.coerce(value, name="value")	Timestamp	Converts a (sec, nanosec) tuple into a Timestamp. If value is already a Timestamp, it is returned unchanged. The optional name is only used to make validation error messages more descriptive. sec/nanosec must be plain integers (not booleans), and nanosec must fall within [0, 1_000_000_000).

Operators

Operation	Returns
a == b	bool
a != b	bool

==/!= only accept another Timestamp on the right-hand side; any other type (including a raw (sec, nanosec) tuple) returns NotImplemented. Timestamp has no ordering support — there is no __lt__, so <, <=, >, and >= all raise TypeError. Timestamp exposes only sec/nanosec; derived quantities such as elapsed time must be computed by the caller from the raw fields (e.g. (b.sec + b.nanosec / 1e9) - (a.sec + a.nanosec / 1e9)).

Visualization

import rerun as rr

# Your code block
# ....

rr.init("timestamp_example", spawn=True)
datatypes.visualize(stamp, entity_path="/stamp", label="Timestamp")

Example

"""Demonstrates the Telekinesis Timestamp datatype."""

import time

import rerun as rr
from loguru import logger

from telekinesis import datatypes

def timestamp_example():
    """Demonstrate creation, inspection, operations, visualization, and serialization."""

    # ======================= Create ============================================
    timestamp = datatypes.Timestamp(sec=42, nanosec=250_000_000)
    logger.info(f"Created Timestamp: {timestamp}")

    coerced = datatypes.Timestamp.coerce((43, 0))
    logger.info(f"Timestamp coerced from tuple: {coerced}")

    # ======================= Inspect ===========================================
    logger.info(f"sec={timestamp.sec}")
    logger.info(f"nanosec={timestamp.nanosec}")

    # ======================= Operations ========================================
    # Timestamp is immutable; build a new instance rather than mutating in place.
    later = datatypes.Timestamp(sec=43, nanosec=0)
    logger.info(f"Later Timestamp: {later}")

    same = datatypes.Timestamp(sec=42, nanosec=250_000_000)
    logger.info(f"EQ: {timestamp} == {same} = {timestamp == same}")
    logger.info(f"EQ: {timestamp} == {later} = {timestamp == later}")

    # Timestamp exposes only sec/nanosec and equality; derived quantities such
    # as elapsed time are computed by the caller from the raw fields.
    diff_sec = (later.sec + later.nanosec / 1e9) - (timestamp.sec + timestamp.nanosec / 1e9)
    logger.info(f"Difference between timestamps: {diff_sec:.3f} s")

    # ======================= Visualize =========================================
    rr.init("timestamp_example", spawn=True)
    datatypes.visualize(timestamp, entity_path="/timestamp/original")
    datatypes.visualize(later, entity_path="/timestamp/later")

    # ======================= Serialize / Deserialize ===========================
    start = time.perf_counter()
    serialized = datatypes.serialize(timestamp)
    serialization_ms = (time.perf_counter() - start) * 1000

    start = time.perf_counter()
    deserialized = datatypes.deserialize(serialized)["param_0"]
    deserialization_ms = (time.perf_counter() - start) * 1000

    logger.info(f"Deserialized Timestamp: {deserialized}")
    logger.info(f"Round-trip successful: {timestamp == deserialized}")
    logger.info(f"Serialization time: {serialization_ms:.3f} ms")
    logger.info(f"Deserialization time: {deserialization_ms:.3f} ms")


if __name__ == "__main__":
    timestamp_example()