add sorting stuff

qiskit_ibm_runtime/execution_span.py

@@ -33,6 +33,9 @@ class ExecutionSpan(abc.ABC):
     A pub is said to have dependence on an execution span if the corresponding execution includes
     data that forms any part of the pub's results.
 
+    Execution spans are equality checkable, and they implement a comparison operator based on
+    the tuple ``(start, stop)``, so can be sorted.
+
     Args:
         start: The start time of the span, in UTC.
         stop: The stop time of the span, in UTC.
@@ -43,9 +46,12 @@ def __init__(self, start: datetime, stop: datetime):
         self._stop = stop
 
     @abc.abstractmethod
-    def __eq__(self, other):
+    def __eq__(self, other) -> bool:
         pass
 
+    def __lt__(self, other: ExecutionSpan) -> bool:
+        return (self.start, self.stop) < (other.start, other.stop)
+
     def __repr__(self):
         attrs = [
             f"start='{self.start:%Y-%m-%d %H:%M:%S}'",
@@ -258,3 +264,18 @@ def filter_by_pub(self, pub_idx: int | Iterable[int]) -> "ExecutionSpans":
             pub_idx: One or more pub indices to filter.
         """
         return ExecutionSpans(span.filter_by_pub(pub_idx) for span in self)
+
+    def sort(self, inplace: bool = True) -> "ExecutionSpans":
+        """Return the same execution spans, sorted.
+
+        Sorting is done by the :attr:`~.ExecutionSpan.start` timestamp of each execution span.
+
+        Args:
+            inplace: Whether to sort this instance in place, or return a copy.
+
+        Returns:
+            This instance if ``inplace``, a new instance otherwise, sorted.
+        """
+        obj = self if inplace else ExecutionSpans(self)
+        obj._spans.sort()
+        return obj

test/unit/test_execution_span.py

@@ -13,7 +13,7 @@
 """Tests SliceSpan and ExecutionSpans classes."""
 
 
-from datetime import datetime
+from datetime import datetime, timedelta
 import ddt
 
 import numpy as np
@@ -53,6 +53,17 @@ def test_equality(self):
         self.assertNotEqual(self.span1, self.span2)
         self.assertNotEqual(self.span1, "aoeu")
 
+    def test_comparison(self):
+        """Test the comparison method."""
+        self.assertLess(self.span1, self.span2)
+
+        dt = timedelta(seconds=1)
+        span1_plus = SliceSpan(self.start1, self.stop1 + dt, self.slices1)
+        self.assertLess(self.span1, span1_plus)
+
+        span1_minus = SliceSpan(self.start1, self.stop1 - dt, self.slices1)
+        self.assertGreater(self.span1, span1_minus)
+
     def test_duration(self):
         """Test the duration property"""
         self.assertEqual(self.span1.duration, 7)
@@ -170,3 +181,17 @@ def test_sequence_methods(self):
         self.assertEqual(self.spans[0], self.span1)
         self.assertEqual(self.spans[1], self.span2)
         self.assertEqual(self.spans[1, 0], ExecutionSpans([self.span2, self.span1]))
+
+    def test_sort(self):
+        """Test the sort method."""
+        spans = ExecutionSpans([self.span2, self.span1])
+        self.assertLess(spans[1], spans[0])
+        inplace_sort = spans.sort()
+        self.assertIs(inplace_sort, spans)
+        self.assertLess(spans[0], spans[1])
+
+        spans = ExecutionSpans([self.span2, self.span1])
+        new_sort = spans.sort(inplace=False)
+        self.assertIsNot(inplace_sort, spans)
+        self.assertLess(spans[1], spans[0])
+        self.assertLess(new_sort[0], new_sort[1])