extra overload for VisibletimeRanges and accompanying tests

Author: Wumpf

docs/content/reference/migration/migration-0-23.md

@@ -240,13 +240,29 @@ After:
 # …
 overrides={
     "helix/structure/scaffolding/beads": rrb.VisibleTimeRanges(
+            timeline="stable_time",
+            start=rrb.TimeRangeBoundary.cursor_relative(seconds=-0.3),
+            end=rrb.TimeRangeBoundary.cursor_relative(seconds=0.3)
+        ),
+}
+# …
+```
+… or respectively for multiple timelines:
+```py
+# …
+overrides={
+    "helix/structure/scaffolding/beads": rrb.VisibleTimeRanges([
+        rrb.VisibleTimeRange(
+            timeline="stable_time",
+            start=rrb.TimeRangeBoundary.cursor_relative(seconds=-0.3),
+            end=rrb.TimeRangeBoundary.cursor_relative(seconds=0.3)
+        ),
         rrb.VisibleTimeRange(
-            timelines="stable_time",
-            starts=rrb.TimeRangeBoundary.cursor_relative(seconds=-0.3),
-            ends=rrb.TimeRangeBoundary.cursor_relative(seconds=0.3),
+            timeline="index",
+            start=rrb.TimeRangeBoundary.absolute(seq=10),
+            end=rrb.TimeRangeBoundary.absolute(seq=100)
         ),
-    ),
+    ])
 }
 # …
 ```
-

examples/python/dna/dna.py

@@ -78,11 +78,9 @@ def main() -> None:
                 origin="/",
                 overrides={
                     "helix/structure/scaffolding/beads": rrb.VisibleTimeRanges(
-                        rrb.VisibleTimeRange(
-                            timeline="stable_time",
-                            start=rrb.TimeRangeBoundary.cursor_relative(seconds=-0.3),
-                            end=rrb.TimeRangeBoundary.cursor_relative(seconds=0.3),
-                        ),
+                        timeline="stable_time",
+                        start=rrb.TimeRangeBoundary.cursor_relative(seconds=-0.3),
+                        end=rrb.TimeRangeBoundary.cursor_relative(seconds=0.3),
                     ),
                 },
             ),

rerun_py/rerun_sdk/rerun/blueprint/archetypes/visible_time_ranges_ext.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, overload
+
+from rerun.datatypes.visible_time_range import VisibleTimeRange
 
 from ... import datatypes
 from ...error_utils import _send_warning_or_raise, catch_and_log_exceptions
@@ -9,32 +11,83 @@
 class VisibleTimeRangesExt:
     """Extension for [VisibleTimeRanges][rerun.blueprint.archetypes.VisibleTimeRanges]."""
 
-    def __init__(self: Any, ranges: datatypes.VisibleTimeRangeArrayLike) -> None:
+    @overload
+    def __init__(self: Any, ranges: datatypes.VisibleTimeRangeArrayLike) -> None: ...
+
+    @overload
+    def __init__(
+        self: Any,
+        *,
+        timeline: datatypes.Utf8Like,
+        range: datatypes.TimeRangeLike,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self: Any,
+        *,
+        timeline: datatypes.Utf8Like,
+        start: datatypes.TimeRangeBoundary,
+        end: datatypes.TimeRangeBoundary,
+    ) -> None: ...
+
+    def __init__(
+        self: Any,
+        ranges: datatypes.VisibleTimeRangeArrayLike | None = None,
+        *,
+        timeline: datatypes.Utf8Like | None = None,
+        range: datatypes.TimeRangeLike | None = None,
+        start: datatypes.TimeRangeBoundary | None = None,
+        end: datatypes.TimeRangeBoundary | None = None,
+    ) -> None:
         """
         Create a new instance of the VisibleTimeRanges archetype.
 
+        Either from a list of `VisibleTimeRange` objects, or from a single `timeline`-name plus either `range` or `start` & `end`.
+
         Parameters
         ----------
         ranges:
             The time ranges to show for each timeline unless specified otherwise on a per-entity basis.
 
             If a timeline is listed twice, a warning will be issued and the first entry will be used.
 
+        timeline:
+            The name of the timeline to show.
+            Mutually exclusive with `ranges`.
+        range:
+            The range of the timeline to show.
+            Requires `timeline` to be set. Mutually exclusive with `start` & `end`.
+        start:
+            The start of the timeline to show.
+            Requires `timeline` to be set. Mutually exclusive with `range`.
+        end:
+            The end of the timeline to show.
+            Requires `timeline` to be set. Mutually exclusive with `range`.
+
         """
 
-        if isinstance(ranges, datatypes.VisibleTimeRange):
-            ranges = [ranges]
+        with catch_and_log_exceptions(context=self.__class__.__name__):
+            if timeline is not None:
+                if ranges is not None:
+                    raise ValueError("`timeline` and `ranges` are mutually exclusive.")
+                ranges = [VisibleTimeRange(timeline=timeline, range=range, start=start, end=end)]
+            elif ranges is None:
+                raise ValueError("Either `ranges` or `timeline` must be set.")
 
-        timelines = set()
-        for range in ranges:
-            if range.timeline in timelines:
-                _send_warning_or_raise(
-                    f"Warning: Timeline {range.timeline} is listed twice in the list of visible time ranges. Only the first entry will be used.",
-                    1,
-                )
-            timelines.add(range.timeline)
+            if isinstance(ranges, datatypes.VisibleTimeRange):
+                ranges = [ranges]
+
+            timelines = set()
+            for visible_time_range in ranges:
+                if visible_time_range.timeline in timelines:
+                    _send_warning_or_raise(
+                        f"Warning: Timeline {visible_time_range.timeline} is listed twice in the list of visible time ranges. Only the first entry will be used.",
+                        1,
+                    )
+                timelines.add(visible_time_range.timeline)
 
-        with catch_and_log_exceptions(context=self.__class__.__name__):
             self.__attrs_init__(ranges=ranges)
             return
+
         self.__attrs_clear__()

rerun_py/tests/unit/test_visible_time_ranges.py

@@ -27,3 +27,40 @@ def test_visible_time_ranges_from_single() -> None:
     assert rr.blueprint.archetypes.VisibleTimeRanges(time_range) == rr.blueprint.archetypes.VisibleTimeRanges([
         time_range,
     ])
+
+    assert rr.blueprint.archetypes.VisibleTimeRanges(time_range) == rr.blueprint.archetypes.VisibleTimeRanges(
+        timeline="timeline",
+        start=rr.TimeRangeBoundary.cursor_relative(),
+        end=rr.TimeRangeBoundary.absolute(seconds=1.0),
+    )
+
+    assert rr.blueprint.archetypes.VisibleTimeRanges(time_range) == rr.blueprint.archetypes.VisibleTimeRanges(
+        timeline="timeline",
+        range=rr.TimeRange(rr.TimeRangeBoundary.cursor_relative(), rr.TimeRangeBoundary.absolute(seconds=1.0)),
+    )
+
+
+def test_visible_time_ranges_invalid_parameters() -> None:
+    time_range = rr.VisibleTimeRange(
+        "timeline",
+        start=rr.TimeRangeBoundary.cursor_relative(),
+        end=rr.TimeRangeBoundary.absolute(seconds=1.0),
+    )
+
+    with pytest.raises(ValueError):
+        # Numpy correctly flags this as an invalid overload, make sure it also throws.
+        rr.blueprint.archetypes.VisibleTimeRanges(
+            ranges=[time_range],
+            timeline="timeline",
+            start=rr.TimeRangeBoundary.cursor_relative(),
+            end=rr.TimeRangeBoundary.absolute(seconds=1.0),
+        )  # type: ignore[call-overload]
+
+    with pytest.raises(ValueError):
+        # Numpy correctly flags this as an invalid overload, make sure it also throws.
+        rr.blueprint.archetypes.VisibleTimeRanges(
+            timeline="timeline",
+            start=rr.TimeRangeBoundary.cursor_relative(),
+            end=rr.TimeRangeBoundary.absolute(seconds=1.0),
+            range=rr.TimeRange(rr.TimeRangeBoundary.cursor_relative(), rr.TimeRangeBoundary.absolute(seconds=1.0)),
+        )  # type: ignore[call-overload]