---
sidebar:
  label: roboto.time
  order: 27
title: roboto.time
---
## Module Contents

### MAX_32BIT_EPOCH_SECONDS

```python
roboto.time.MAX_32BIT_EPOCH_SECONDS = 2147483647
```

`from roboto.time import MAX_32BIT_EPOCH_SECONDS`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/time.py#L22-L22)

### NSEC_PER_MS

```python
roboto.time.NSEC_PER_MS = 1000000
```

`from roboto.time import NSEC_PER_MS`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/time.py#L24-L24)

### NSEC_PER_SEC

```python
roboto.time.NSEC_PER_SEC = 1000000000
```

`from roboto.time import NSEC_PER_SEC`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/time.py#L23-L23)

### NSEC_PER_US

```python
roboto.time.NSEC_PER_US = 1000
```

`from roboto.time import NSEC_PER_US`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/time.py#L25-L25)

### Time

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

`from roboto.time import Time`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/time.py#L31-L31)

### TimeUnit

```python
class roboto.time.TimeUnit
```

`from roboto.time import TimeUnit`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/time.py#L34-L56)

Bases: `roboto.compat.StrEnum`

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

**Attributes**

- **TimeUnit.Microseconds** = `'us'`
- **TimeUnit.Milliseconds** = `'ms'`
- **TimeUnit.Nanoseconds** = `'ns'`
- **TimeUnit.Seconds** = `'s'`

#### TimeUnit.nano_multiplier()

```python
def nano_multiplier() -> int
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/time.py#L47-L56)

**Returns**

- `int`

### log

```python
roboto.time.log
```

`from roboto.time import log`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/time.py#L19-L19)

### to_epoch_nanoseconds()

```python
def roboto.time.to_epoch_nanoseconds(value: Time, unit: Optional[TimeUnit] = None)
```

`from roboto.time import to_epoch_nanoseconds`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/time.py#L59-L138)

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`](/reference/python-sdk/roboto/time#roboto.time.TimeUnit.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`](/reference/python-sdk/roboto/time#roboto.time.TimeUnit.Seconds).
- **`decimal.Decimal` formatted `value`:**

  - If not provided, `unit` defaults to [`Seconds`](/reference/python-sdk/roboto/time#roboto.time.TimeUnit.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`](/reference/python-sdk/roboto/time#roboto.time.TimeUnit.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.

**Parameters**

- **value** (`Time`)
- **unit** (`Optional[TimeUnit]`)

**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"`.

### utcnow()

```python
def roboto.time.utcnow() -> datetime.datetime
```

`from roboto.time import utcnow`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/time.py#L168-L170)

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

**Returns**

- `datetime.datetime`