Preserve 'linked' sideload data in PaginatedList (fixes #709)

canvasapi/paginated_list.py

@@ -65,6 +65,10 @@ def __init__(
         self._request_method = request_method
         self._root = _root
         self._url_override = _url_override
+        # Compound-document sideloaded data (e.g. the "linked" section of the
+        # grade change log). Collected across every page so callers can resolve
+        # identifiers like sis_user_id without extra API calls. See issue #709.
+        self._linked = {}
 
     def __iter__(self) -> Iterator[T]:
         for element in self._elements:
@@ -115,6 +119,21 @@ def _get_next_page(self):
 
         content = []
 
+        # Collect compound-document sideloaded data (the "linked" section) before
+        # any _root extraction, so it is not discarded. See issue #709: the grade
+        # change log returns sideloaded users/courses/assignments that resolve
+        # identifiers such as sis_user_id without extra API calls.
+        if isinstance(data, dict) and "linked" in data:
+            for key, items in data["linked"].items():
+                if items is None:
+                    continue
+                self._linked.setdefault(key, [])
+                existing_ids = {i.get("id") for i in self._linked[key]}
+                for item in items:
+                    if item.get("id") not in existing_ids:
+                        self._linked[key].append(item)
+                        existing_ids.add(item.get("id"))
+
         if self._root:
             try:
                 data = data[self._root]
@@ -130,6 +149,20 @@ def _get_next_page(self):
 
         return content
 
+    @property
+    def linked(self):
+        """
+        Sideloaded data from the Canvas compound-document response.
+
+        For endpoints that return a ``linked`` section (e.g. the grade change
+        log), this is a dict keyed by type (``users``, ``courses``,
+        ``assignments``) containing every sideloaded object across all pages.
+        Returns an empty dict when the response had no ``linked`` section.
+
+        :rtype: dict
+        """
+        return self._linked
+
     def _get_up_to_index(self, index):
         while len(self._elements) <= index and self._has_next():
             self._grow()

tests/fixtures/paginated_list.json

@@ -175,5 +175,62 @@
 			}
 		}
 	},
+	"compound_linked_single_page": {
+		"method": "ANY",
+		"endpoint": "compound_linked",
+		"data": {
+			"events": [
+				{
+					"id": "1",
+					"event_type": "grade_change",
+					"sis_user_id": "U1"
+				},
+				{
+					"id": "2",
+					"event_type": "grade_change",
+					"sis_user_id": "U2"
+				}
+			],
+			"linked": {
+				"users": [
+					{"id": "U1", "name": "Alice"},
+					{"id": "U2", "name": "Bob"}
+				],
+				"courses": [
+					{"id": "C1", "name": "Math"}
+				]
+			}
+		},
+		"status_code": 200
+	},
+	"compound_linked_two_pages_p1": {
+		"method": "ANY",
+		"endpoint": "compound_linked_two_pages",
+		"data": {
+			"events": [
+				{"id": "1", "event_type": "grade_change", "sis_user_id": "U1"}
+			],
+			"linked": {
+				"users": [{"id": "U1", "name": "Alice"}]
+			}
+		},
+		"headers": {
+			"Link": "<https://example.com/api/v1/compound_linked_two_pages?page=2&per_page=2>; rel=\"next\""
+		},
+		"status_code": 200
+	},
+	"compound_linked_two_pages_p2": {
+		"method": "ANY",
+		"endpoint": "compound_linked_two_pages?page=2&per_page=2",
+		"data": {
+			"events": [
+				{"id": "2", "event_type": "grade_change", "sis_user_id": "U2"}
+			],
+			"linked": {
+				"users": [{"id": "U2", "name": "Bob"}]
+			}
+		},
+		"status_code": 200
+	},
 	"status_code": 200
 }

tests/test_paginated_list.py

@@ -233,3 +233,47 @@ def test_paginated_list_no_header_no_next(self, m):
         self.assertIsInstance(pag_list, PaginatedList)
         self.assertEqual(len(list(pag_list)), 2)
         self.assertIsInstance(pag_list[0], User)
+
+    def test_paginated_list_compound_linked_single_page(self, m):
+        # Issue #709: compound-document responses with a "linked" section must
+        # not discard the sideloaded data.
+        from canvasapi.grade_change_log import GradeChangeEvent
+
+        register_uris({"paginated_list": ["compound_linked_single_page"]}, m)
+
+        pag_list = PaginatedList(
+            GradeChangeEvent, self.requester, "GET", "compound_linked", _root="events"
+        )
+
+        self.assertIsInstance(pag_list, PaginatedList)
+        self.assertEqual(len(list(pag_list)), 2)
+        self.assertIsInstance(pag_list[0], GradeChangeEvent)
+        # linked data must be preserved
+        self.assertIn("users", pag_list.linked)
+        self.assertIn("courses", pag_list.linked)
+        user_names = {u["name"] for u in pag_list.linked["users"]}
+        self.assertEqual(user_names, {"Alice", "Bob"})
+        self.assertEqual(pag_list.linked["courses"][0]["name"], "Math")
+
+    def test_paginated_list_compound_linked_two_pages(self, m):
+        # Issue #709: linked data must be merged across all pages.
+        from canvasapi.grade_change_log import GradeChangeEvent
+
+        register_uris(
+            {"paginated_list": ["compound_linked_two_pages_p1", "compound_linked_two_pages_p2"]},
+            m,
+        )
+
+        pag_list = PaginatedList(
+            GradeChangeEvent,
+            self.requester,
+            "GET",
+            "compound_linked_two_pages",
+            _root="events",
+        )
+
+        self.assertEqual(len(list(pag_list)), 2)
+        # linked users from both pages merged, no duplicates
+        self.assertEqual(len(pag_list.linked["users"]), 2)
+        user_names = {u["name"] for u in pag_list.linked["users"]}
+        self.assertEqual(user_names, {"Alice", "Bob"})