Enable per-page telemetry access for paginated get() queries

Extends the fluent .with_response_details() API to support paginated
queries. Each page batch is now wrapped in OperationResult, allowing
telemetry access per page while maintaining backward compatibility.

Changes:
- Add __add__ and __radd__ to OperationResult for batch concatenation
- Modify _get_multiple to yield (batch, metadata) tuples
- Update get() to wrap each page in OperationResult
- Add per-page telemetry printing to walkthrough example
- Add tests for concatenation and per-page telemetry access

Backward compatibility:
- Existing iteration patterns work unchanged via OperationResult delegation
- Batch concatenation (batch1 + batch2) returns raw list as expected

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: tpellissier

examples/advanced/walkthrough.py

@@ -212,6 +212,7 @@ def main():
     records_iterator = backoff(lambda: client.get(table_name, filter="new_quantity gt 5"))
     for page in records_iterator:
         all_records.extend(page)
+        print_telemetry(page.with_response_details().telemetry)
     print(f"[OK] Found {len(all_records)} records with new_quantity > 5")
     for rec in all_records:
         print(f"  - new_Title='{rec.get('new_title')}', new_Quantity={rec.get('new_quantity')}")
@@ -266,6 +267,7 @@ def main():
     for page_num, page in enumerate(paging_iterator, start=1):
         record_ids = [r.get("new_walkthroughdemoid")[:8] + "..." for r in page]
         print(f"  Page {page_num}: {len(page)} records - IDs: {record_ids}")
+        print_telemetry(page.with_response_details().telemetry)
 
     # ============================================================================
     # 7. SQL QUERY

src/PowerPlatform/Dataverse/client.py

@@ -293,7 +293,7 @@ def get(
         top: Optional[int] = None,
         expand: Optional[List[str]] = None,
         page_size: Optional[int] = None,
-    ) -> Union[OperationResult[Dict[str, Any]], Iterable[List[Dict[str, Any]]]]:
+    ) -> Union[OperationResult[Dict[str, Any]], Iterable[OperationResult[List[Dict[str, Any]]]]]:
         """
         Fetch a single record by ID or query multiple records.
 
@@ -320,9 +320,11 @@ def get(
         :return: When ``record_id`` is provided, returns an OperationResult containing the record dict.
             The result supports dict-like access (e.g., ``result["name"]``) or call
             ``.with_response_details()`` to access telemetry data.
-            When querying multiple records, returns a generator yielding lists of record
-            dictionaries (one list per page).
-        :rtype: :class:`OperationResult` [:class:`dict`] or :class:`collections.abc.Iterable` of :class:`list` of :class:`dict`
+            When querying multiple records, returns a generator yielding OperationResult objects,
+            each containing a list of record dictionaries (one list per page). Each batch supports
+            iteration and indexing directly, or call ``.with_response_details()`` to access
+            that page's telemetry data.
+        :rtype: :class:`OperationResult` [:class:`dict`] or :class:`collections.abc.Iterable` of :class:`OperationResult` [:class:`list` of :class:`dict`]
 
         :raises TypeError: If ``record_id`` is provided but not a string.
 
@@ -368,6 +370,14 @@ def get(
                     page_size=50
                 ):
                     print(f"Batch size: {len(batch)}")
+
+            Query with per-page telemetry access::
+
+                for batch in client.get("account", filter="statecode eq 0"):
+                    response = batch.with_response_details()
+                    print(f"Page request ID: {response.telemetry['service_request_id']}")
+                    for account in response.result:
+                        print(account["name"])
         """
         if record_id is not None:
             if not isinstance(record_id, str):
@@ -380,17 +390,18 @@ def get(
                 )
                 return OperationResult(record, metadata)
 
-        def _paged() -> Iterable[List[Dict[str, Any]]]:
+        def _paged() -> Iterable[OperationResult[List[Dict[str, Any]]]]:
             with self._scoped_odata() as od:
-                yield from od._get_multiple(
+                for batch, metadata in od._get_multiple(
                     table_schema_name,
                     select=select,
                     filter=filter,
                     orderby=orderby,
                     top=top,
                     expand=expand,
                     page_size=page_size,
-                )
+                ):
+                    yield OperationResult(batch, metadata)
 
         return _paged()
 

src/PowerPlatform/Dataverse/core/results.py

@@ -240,5 +240,29 @@ def __contains__(self, item: Any) -> bool:
         """
         return item in self._result  # type: ignore[operator]
 
+    def __add__(self, other: Any) -> Any:
+        """
+        Support concatenation with + operator.
+
+        When combining OperationResults (e.g., concatenating batches), returns
+        the raw combined result since there's no meaningful single telemetry
+        to preserve for the combined value.
+
+        :param other: Value to concatenate with.
+        :return: Combined result (raw value, not wrapped in OperationResult).
+        """
+        if isinstance(other, OperationResult):
+            return self._result + other._result  # type: ignore[operator]
+        return self._result + other  # type: ignore[operator]
+
+    def __radd__(self, other: Any) -> Any:
+        """
+        Support right-hand concatenation (e.g., [] + result).
+
+        :param other: Left-hand value to concatenate with.
+        :return: Combined result (raw value, not wrapped in OperationResult).
+        """
+        return other + self._result  # type: ignore[operator]
+
 
 __all__ = ["RequestTelemetryData", "DataverseResponse", "OperationResult"]

src/PowerPlatform/Dataverse/data/_odata.py

@@ -629,8 +629,8 @@ def _get_multiple(
         top: Optional[int] = None,
         expand: Optional[List[str]] = None,
         page_size: Optional[int] = None,
-    ) -> Iterable[List[Dict[str, Any]]]:
-        """Iterate records from an entity set, yielding one page (list of dicts) at a time.
+    ) -> Iterable[_ODataRequestResult]:
+        """Iterate records from an entity set, yielding one page with telemetry at a time.
 
         :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
@@ -647,12 +647,8 @@ def _get_multiple(
         :param page_size: Per-page size hint via ``Prefer: odata.maxpagesize``.
         :type page_size: ``int`` | ``None``
 
-        :return: Iterator yielding pages (each page is a ``list`` of record dicts).
-        :rtype: ``Iterable[list[dict[str, Any]]]``
-
-        .. note::
-           This method is a generator and does not return metadata directly.
-           For paginated queries, metadata is captured per-request but not surfaced.
+        :return: Iterator yielding tuples of (page records, telemetry) for each page.
+        :rtype: ``Iterable[tuple[list[dict[str, Any]], RequestTelemetryData]]``
         """
 
         extra_headers: Dict[str, str] = {}
@@ -661,13 +657,13 @@ def _get_multiple(
             if ps > 0:
                 extra_headers["Prefer"] = f"odata.maxpagesize={ps}"
 
-        def _do_request(url: str, *, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        def _do_request(url: str, *, params: Optional[Dict[str, Any]] = None) -> Tuple[Dict[str, Any], RequestTelemetryData]:
             headers = extra_headers if extra_headers else None
-            r, _ = self._request("get", url, headers=headers, params=params)
+            r, metadata = self._request("get", url, headers=headers, params=params)
             try:
-                return r.json()
+                return r.json(), metadata
             except ValueError:
-                return {}
+                return {}, metadata
 
         entity_set = self._entity_set_from_schema_name(table_schema_name)
         base_url = f"{self.api}/{entity_set}"
@@ -687,20 +683,20 @@ def _do_request(url: str, *, params: Optional[Dict[str, Any]] = None) -> Dict[st
         if top is not None:
             params["$top"] = int(top)
 
-        data = _do_request(base_url, params=params)
+        data, metadata = _do_request(base_url, params=params)
         items = data.get("value") if isinstance(data, dict) else None
         if isinstance(items, list) and items:
-            yield [x for x in items if isinstance(x, dict)]
+            yield [x for x in items if isinstance(x, dict)], metadata
 
         next_link = None
         if isinstance(data, dict):
             next_link = data.get("@odata.nextLink") or data.get("odata.nextLink")
 
         while next_link:
-            data = _do_request(next_link)
+            data, metadata = _do_request(next_link)
             items = data.get("value") if isinstance(data, dict) else None
             if isinstance(items, list) and items:
-                yield [x for x in items if isinstance(x, dict)]
+                yield [x for x in items if isinstance(x, dict)], metadata
             next_link = data.get("@odata.nextLink") or data.get("odata.nextLink") if isinstance(data, dict) else None
 
     # --------------------------- SQL Custom API -------------------------

tests/unit/data/test_logical_crud.py

@@ -119,7 +119,13 @@ def test_get_multiple_paging():
     ]
     c = MockableClient(responses)
     pages = list(c._get_multiple("account", select=["accountid"], page_size=1))
-    assert pages == [[{"accountid": "1"}], [{"accountid": "2"}]]
+    # _get_multiple now returns (batch, metadata) tuples
+    assert len(pages) == 2
+    assert pages[0][0] == [{"accountid": "1"}]
+    assert pages[1][0] == [{"accountid": "2"}]
+    # Each page has telemetry metadata
+    assert pages[0][1].client_request_id is not None
+    assert pages[1][1].client_request_id is not None
 
 
 def test_unknown_table_schema_name_raises():

tests/unit/test_client.py

@@ -158,9 +158,10 @@ def test_get_single(self):
 
     def test_get_multiple(self):
         """Test get method for querying multiple records."""
-        # Setup mock return value (iterator)
+        # Setup mock return value (iterator of (batch, metadata) tuples)
         expected_batch = [{"accountid": "1", "name": "A"}, {"accountid": "2", "name": "B"}]
-        self.client._odata._get_multiple.return_value = iter([expected_batch])
+        mock_metadata = RequestTelemetryData(client_request_id="test-page-1")
+        self.client._odata._get_multiple.return_value = iter([(expected_batch, mock_metadata)])
 
         # Execute query
         result_iterator = self.client.get("account", filter="statecode eq 0", top=10)
@@ -177,4 +178,63 @@ def test_get_multiple(self):
             expand=None,
             page_size=None,
         )
-        self.assertEqual(results, [expected_batch])
+        # Each batch is now wrapped in OperationResult
+        self.assertEqual(len(results), 1)
+        # Can iterate/index the batch directly (OperationResult delegates)
+        self.assertEqual(results[0][0], {"accountid": "1", "name": "A"})
+        self.assertEqual(list(results[0]), expected_batch)
+        # Can access telemetry via with_response_details()
+        response = results[0].with_response_details()
+        self.assertEqual(response.telemetry["client_request_id"], "test-page-1")
+
+    def test_get_multiple_pagination_with_telemetry(self):
+        """Test get method returns per-page telemetry for paginated results."""
+        # Setup mock with multiple pages
+        batch1 = [{"accountid": "1"}, {"accountid": "2"}]
+        batch2 = [{"accountid": "3"}, {"accountid": "4"}]
+        metadata1 = RequestTelemetryData(client_request_id="page-1", service_request_id="svc-1")
+        metadata2 = RequestTelemetryData(client_request_id="page-2", service_request_id="svc-2")
+        self.client._odata._get_multiple.return_value = iter([
+            (batch1, metadata1),
+            (batch2, metadata2),
+        ])
+
+        # Execute query
+        results = list(self.client.get("account"))
+
+        # Verify we got two pages
+        self.assertEqual(len(results), 2)
+
+        # First page telemetry
+        response1 = results[0].with_response_details()
+        self.assertEqual(response1.result, batch1)
+        self.assertEqual(response1.telemetry["client_request_id"], "page-1")
+        self.assertEqual(response1.telemetry["service_request_id"], "svc-1")
+
+        # Second page telemetry
+        response2 = results[1].with_response_details()
+        self.assertEqual(response2.result, batch2)
+        self.assertEqual(response2.telemetry["client_request_id"], "page-2")
+        self.assertEqual(response2.telemetry["service_request_id"], "svc-2")
+
+    def test_get_multiple_batch_concatenation(self):
+        """Test that batches can be concatenated with + operator."""
+        # Setup mock with multiple pages
+        batch1 = [{"id": "1"}, {"id": "2"}]
+        batch2 = [{"id": "3"}, {"id": "4"}]
+        metadata = RequestTelemetryData()
+        self.client._odata._get_multiple.return_value = iter([
+            (batch1, metadata),
+            (batch2, metadata),
+        ])
+
+        # Execute query and concatenate batches
+        batches = list(self.client.get("account"))
+        all_records = batches[0] + batches[1]
+
+        # Verify concatenation works
+        self.assertEqual(len(all_records), 4)
+        self.assertEqual(all_records[0]["id"], "1")
+        self.assertEqual(all_records[3]["id"], "4")
+        # Result is raw list, not OperationResult
+        self.assertIsInstance(all_records, list)

tests/unit/test_results.py

@@ -347,3 +347,81 @@ def test_telemetry_access(self, sample_telemetry_data):
         assert response.telemetry["client_request_id"] == "client-123"
         assert response.telemetry["correlation_id"] == "corr-456"
         assert response.telemetry["service_request_id"] == "svc-789"
+
+
+class TestOperationResultConcatenation:
+    """Tests for OperationResult concatenation with + operator."""
+
+    @pytest.fixture
+    def sample_telemetry_data(self):
+        return RequestTelemetryData(
+            client_request_id="client-123",
+            correlation_id="corr-456",
+            service_request_id="svc-789",
+        )
+
+    def test_add_two_operation_results(self, sample_telemetry_data):
+        """Adding two OperationResults should concatenate their results."""
+        result1 = OperationResult(result=["a", "b"], telemetry_data=sample_telemetry_data)
+        result2 = OperationResult(result=["c", "d"], telemetry_data=sample_telemetry_data)
+        combined = result1 + result2
+        assert combined == ["a", "b", "c", "d"]
+        # Result should be raw list, not OperationResult
+        assert isinstance(combined, list)
+
+    def test_add_operation_result_with_list(self, sample_telemetry_data):
+        """Adding OperationResult with a list should work."""
+        result = OperationResult(result=["a", "b"], telemetry_data=sample_telemetry_data)
+        combined = result + ["c", "d"]
+        assert combined == ["a", "b", "c", "d"]
+        assert isinstance(combined, list)
+
+    def test_radd_list_with_operation_result(self, sample_telemetry_data):
+        """Right-hand addition: list + OperationResult should work."""
+        result = OperationResult(result=["c", "d"], telemetry_data=sample_telemetry_data)
+        combined = ["a", "b"] + result
+        assert combined == ["a", "b", "c", "d"]
+        assert isinstance(combined, list)
+
+    def test_add_empty_lists(self, sample_telemetry_data):
+        """Adding empty OperationResults should return empty list."""
+        result1 = OperationResult(result=[], telemetry_data=sample_telemetry_data)
+        result2 = OperationResult(result=[], telemetry_data=sample_telemetry_data)
+        combined = result1 + result2
+        assert combined == []
+        assert isinstance(combined, list)
+
+    def test_add_with_empty_list(self, sample_telemetry_data):
+        """Adding OperationResult with empty list should work."""
+        result = OperationResult(result=["a", "b"], telemetry_data=sample_telemetry_data)
+        combined = result + []
+        assert combined == ["a", "b"]
+
+    def test_radd_empty_list(self, sample_telemetry_data):
+        """Right-hand addition with empty list should work."""
+        result = OperationResult(result=["a", "b"], telemetry_data=sample_telemetry_data)
+        combined = [] + result
+        assert combined == ["a", "b"]
+
+    def test_concatenate_multiple_batches(self, sample_telemetry_data):
+        """Simulate combining multiple page batches."""
+        batch1 = OperationResult(result=[{"id": "1"}, {"id": "2"}], telemetry_data=sample_telemetry_data)
+        batch2 = OperationResult(result=[{"id": "3"}, {"id": "4"}], telemetry_data=sample_telemetry_data)
+        batch3 = OperationResult(result=[{"id": "5"}], telemetry_data=sample_telemetry_data)
+
+        all_records = batch1 + batch2 + batch3
+        assert len(all_records) == 5
+        assert all_records[0]["id"] == "1"
+        assert all_records[4]["id"] == "5"
+
+    def test_string_concatenation(self, sample_telemetry_data):
+        """String concatenation should work."""
+        result = OperationResult(result="Hello ", telemetry_data=sample_telemetry_data)
+        combined = result + "World"
+        assert combined == "Hello World"
+
+    def test_radd_string_concatenation(self, sample_telemetry_data):
+        """Right-hand string concatenation should work."""
+        result = OperationResult(result="World", telemetry_data=sample_telemetry_data)
+        combined = "Hello " + result
+        assert combined == "Hello World"