feat: cleanup & simplify timestamp handling

docs/reference/ts.md

@@ -0,0 +1 @@
+::: nominal.ts

justfile

@@ -14,6 +14,13 @@ test-e2e token:
 check-types:
     poetry run mypy
 
+# check static typing across all supported python versions
+check-types-all:
+    poetry run mypy --python-version 3.12
+    poetry run mypy --python-version 3.11
+    poetry run mypy --python-version 3.10
+    poetry run mypy --python-version 3.9
+
 # check code formatting | fix with `just fix-format`
 check-format:
     poetry run ruff format --check

mkdocs.yml

@@ -23,6 +23,7 @@ nav:
       - Examples: usage/examples.md
   - Reference:
       - High-level SDK: reference/toplevel.md
+      - Timestamps: reference/ts.md
       - Core SDK: reference/core.md
       - Exceptions: reference/exceptions.md
       - nom cli: reference/nom-cli.md

nominal/__init__.py

@@ -1,3 +1,4 @@
+from . import ts
 from .core import Attachment, Dataset, Log, LogSet, NominalClient, Run, Video
 from .nominal import (
     create_run,
@@ -19,27 +20,28 @@
 )
 
 __all__ = [
-    "set_base_url",
-    "get_default_client",
-    "upload_pandas",
-    "upload_polars",
-    "upload_csv",
-    "get_dataset",
-    "get_log_set",
+    "ts",
     "create_run",
     "create_run_csv",
+    "download_attachment",
+    "get_attachment",
+    "get_dataset",
+    "get_default_client",
+    "get_log_set",
     "get_run",
+    "get_video",
     "search_runs",
+    "set_base_url",
     "upload_attachment",
-    "get_attachment",
-    "download_attachment",
+    "upload_csv",
+    "upload_pandas",
+    "upload_polars",
     "upload_video",
-    "get_video",
     # classes: when adding a new class, also add a filter to "hide" it in docs/reference/toplevel.md
-    "Dataset",
-    "Run",
     "Attachment",
+    "Dataset",
     "NominalClient",
+    "Run",
     "Video",
     "LogSet",
     "Log",

nominal/_utils.py

@@ -4,139 +4,16 @@
 import mimetypes
 import os
 from contextlib import contextmanager
-from dataclasses import dataclass
-from datetime import datetime, timezone
 from pathlib import Path
-from typing import BinaryIO, Callable, Iterable, Iterator, Literal, NamedTuple, TypeVar, Union
+from typing import BinaryIO, Callable, Iterable, Iterator, Literal, NamedTuple, TypeVar
 
-import dateutil.parser
 from typing_extensions import ParamSpec, TypeAlias
 
-from ._api.combined import api, ingest_api, scout_run_api
-
 logger = logging.getLogger(__name__)
 
-IntegralNanosecondsUTC = int
 T = TypeVar("T")
 
 
-@dataclass
-class CustomTimestampFormat:
-    format: str
-    default_year: int = 0
-
-
-# Using Union rather than the "|" operator due to https://github.com/python/mypy/issues/11665.
-TimestampColumnType: TypeAlias = Union[
-    Literal[
-        "iso_8601",
-        "epoch_days",
-        "epoch_hours",
-        "epoch_minutes",
-        "epoch_seconds",
-        "epoch_milliseconds",
-        "epoch_microseconds",
-        "epoch_nanoseconds",
-        "relative_days",
-        "relative_hours",
-        "relative_minutes",
-        "relative_seconds",
-        "relative_milliseconds",
-        "relative_microseconds",
-        "relative_nanoseconds",
-    ],
-    CustomTimestampFormat,
-]
-
-
-def _flexible_time_to_global_conjure_api(
-    timestamp: datetime | IntegralNanosecondsUTC,
-) -> api.Timestamp:
-    seconds, nanos = _flexible_time_to_seconds_nanos(timestamp)
-    return api.Timestamp(seconds=seconds, nanos=nanos)
-
-
-def _global_conjure_api_to_integral_nanoseconds(
-    timestamp: api.Timestamp,
-) -> IntegralNanosecondsUTC:
-    return timestamp.seconds * 1_000_000_000 + timestamp.nanos
-
-
-def _timestamp_type_to_conjure_ingest_api(
-    ts_type: TimestampColumnType,
-) -> ingest_api.TimestampType:
-    if isinstance(ts_type, CustomTimestampFormat):
-        return ingest_api.TimestampType(
-            absolute=ingest_api.AbsoluteTimestamp(
-                custom_format=ingest_api.CustomTimestamp(format=ts_type.format, default_year=ts_type.default_year)
-            )
-        )
-    elif ts_type == "iso_8601":
-        return ingest_api.TimestampType(absolute=ingest_api.AbsoluteTimestamp(iso8601=ingest_api.Iso8601Timestamp()))
-    relation, unit = ts_type.split("_", 1)
-    time_unit = ingest_api.TimeUnit[unit.upper()]
-    if relation == "epoch":
-        return ingest_api.TimestampType(
-            absolute=ingest_api.AbsoluteTimestamp(epoch_of_time_unit=ingest_api.EpochTimestamp(time_unit=time_unit))
-        )
-    elif relation == "relative":
-        return ingest_api.TimestampType(relative=ingest_api.RelativeTimestamp(time_unit=time_unit))
-    raise ValueError(f"invalid timestamp type: {ts_type}")
-
-
-def _flexible_time_to_conjure_scout_run_api(timestamp: datetime | IntegralNanosecondsUTC) -> scout_run_api.UtcTimestamp:
-    seconds, nanos = _flexible_time_to_seconds_nanos(timestamp)
-    return scout_run_api.UtcTimestamp(seconds_since_epoch=seconds, offset_nanoseconds=nanos)
-
-
-def _flexible_time_to_conjure_ingest_api(
-    timestamp: datetime | IntegralNanosecondsUTC,
-) -> ingest_api.UtcTimestamp:
-    seconds, nanos = _flexible_time_to_seconds_nanos(timestamp)
-    return ingest_api.UtcTimestamp(seconds_since_epoch=seconds, offset_nanoseconds=nanos)
-
-
-def _flexible_time_to_seconds_nanos(
-    timestamp: datetime | IntegralNanosecondsUTC,
-) -> tuple[int, int]:
-    if isinstance(timestamp, datetime):
-        return _datetime_to_seconds_nanos(timestamp)
-    elif isinstance(timestamp, IntegralNanosecondsUTC):
-        return divmod(timestamp, 1_000_000_000)
-    raise TypeError(f"expected {datetime} or {IntegralNanosecondsUTC}, got {type(timestamp)}")
-
-
-def _flexible_time_to_integral_nanoseconds(
-    timestamp: datetime | IntegralNanosecondsUTC,
-) -> IntegralNanosecondsUTC:
-    seconds, nanos = _flexible_time_to_seconds_nanos(timestamp)
-    return seconds * 1_000_000_000 + nanos
-
-
-def _conjure_time_to_integral_nanoseconds(ts: scout_run_api.UtcTimestamp) -> IntegralNanosecondsUTC:
-    return ts.seconds_since_epoch * 1_000_000_000 + (ts.offset_nanoseconds or 0)
-
-
-def _datetime_to_seconds_nanos(dt: datetime) -> tuple[int, int]:
-    dt = dt.astimezone(timezone.utc)
-    seconds = int(dt.timestamp())
-    nanos = dt.microsecond * 1000
-    return seconds, nanos
-
-
-def _datetime_to_integral_nanoseconds(dt: datetime) -> IntegralNanosecondsUTC:
-    seconds, nanos = _datetime_to_seconds_nanos(dt)
-    return seconds * 1_000_000_000 + nanos
-
-
-def _parse_timestamp(ts: str | datetime | IntegralNanosecondsUTC) -> IntegralNanosecondsUTC:
-    if isinstance(ts, int):
-        return ts
-    if isinstance(ts, str):
-        ts = dateutil.parser.parse(ts)
-    return _datetime_to_integral_nanoseconds(ts)
-
-
 def construct_user_agent_string() -> str:
     """Constructs a user-agent string with system & Python metadata.
     E.g.: nominal-python/1.0.0b0 (macOS-14.4-arm64-arm-64bit) cpython/3.12.4
@@ -211,9 +88,6 @@ def reader_writer() -> Iterator[tuple[BinaryIO, BinaryIO]]:
         r.close()
 
 
-LogTimestampType: TypeAlias = Literal["absolute", "relative"]
-
-
 Param = ParamSpec("Param")
 
 

nominal/cli/dataset.py

@@ -5,6 +5,7 @@
 import click
 
 from ..nominal import _upload_csv
+from ..ts import _LiteralAbsolute
 from ._utils import BASE_URL_OPTION, TOKEN_OPTION, get_client
 
 
@@ -43,16 +44,7 @@ def upload_csv(
     name: str,
     file: str,
     timestamp_column: str,
-    timestamp_type: Literal[
-        "iso_8601",
-        "epoch_days",
-        "epoch_hours",
-        "epoch_minutes",
-        "epoch_seconds",
-        "epoch_milliseconds",
-        "epoch_microseconds",
-        "epoch_nanoseconds",
-    ],
+    timestamp_type: _LiteralAbsolute,
     desc: str | None,
     wait: bool,
     base_url: str,

nominal/cli/run.py

@@ -4,7 +4,7 @@
 
 import click
 
-from .._utils import _parse_timestamp
+from ..ts import _SecondsNanos
 from ._utils import BASE_URL_OPTION, TOKEN_OPTION, get_client
 
 
@@ -36,8 +36,8 @@ def create(
     client = get_client(base_url, token)
     run = client.create_run(
         name,
-        _parse_timestamp(start),
-        _parse_timestamp(end),
+        _SecondsNanos.from_flexible(start).to_nanoseconds(),
+        _SecondsNanos.from_flexible(end).to_nanoseconds(),
         desc,
         properties=dict(properties),
         labels=labels,