roboto.time

Module Contents

roboto.time.MAX_32BIT_EPOCH_SECONDS = 2147483647

roboto.time.NSEC_PER_MS = 1000000

roboto.time.NSEC_PER_SEC = 1000000000

roboto.time.NSEC_PER_US = 1000

type roboto.time.Time = Union[int, float, decimal.Decimal, str, datetime.datetime]

class roboto.time.TimeUnit

Bases: roboto.compat.StrEnum

Well-known time units supported for timestamps in recording data.

Microseconds = 'us'

Milliseconds = 'ms'

Nanoseconds = 'ns'

Seconds = 's'

nano_multiplier()

Return type:

int

roboto.time.log

roboto.time.to_epoch_nanoseconds(value, unit=None)

Convert a time value to nanoseconds since Unix epoch (1970-01-01 00:00:00 UTC). Accepts various input formats (int, float, Decimal, str, datetime) and time units (seconds, milliseconds, microseconds, nanoseconds).

Notes

• int formatted value:

  • If not provided, unit defaults to Nanoseconds.

  • Any integer type is accepted, such as a numpy.int64 read out of a pandas or numpy column.

  • A bool is refused: it is an int in Python, and True would otherwise read as 1.

• float formatted value:

  • Not recommended due to potential for precision loss. If possible, pass value as str or decimal.Decimal instead.

  • If not provided, unit defaults to Seconds.

• decimal.Decimal formatted value:

  • If not provided, unit defaults to Seconds.

  • E.g., a ROS formatted timestamp in the form of decimal.Decimal(“<sec>.<nsec>”)).

• str formatted value:

  • If not provided, unit defaults to Seconds.

  • E.g., a ROS formatted timestamp in the form of “<sec>.<nsec>”).

  • ISO8601 timestamp strings (e.g. "2024-05-16T10:25:47Z") are also accepted; they are parsed via datetime.datetime.fromisoformat() and treated as the datetime branch below. The unit argument is ignored for ISO8601 input.

• datetime.datetime formatted value:

  • unit, if provided, is ignored. Datetimes are always converted from seconds to nanoseconds.

  • A datetime before 1970 converts to a negative number of nanoseconds.

Raises:

• TypeError – value is not one of the types above.

• ValueError – value is a boolean, a negative int, float, Decimal, or numeric string, or a string that is neither a number of seconds nor an ISO 8601 timestamp.

• OverflowError – value is an infinite float, Decimal, or string, such as "inf".

Parameters:

• value (Time)

• unit (Optional[TimeUnit])

roboto.time.utcnow()

Return timezone aware datetime.datetime object, now in UTC.

Return type:

datetime.datetime