fix docs and add error handling for instances/inspect (#2058)

Co-authored-by: Håkon V. Treider <[email protected]>
cognitedata · Dec 5, 2024 · bc8ae8a · bc8ae8a
1 parent fa7f991
commit bc8ae8a
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 16 deletions.
diff --git a/cognite/client/_api/data_modeling/instances.py b/cognite/client/_api/data_modeling/instances.py
@@ -718,22 +718,31 @@ def inspect(
         Args:
             nodes (NodeId | Sequence[NodeId] | tuple[str, str] | Sequence[tuple[str, str]] | None): Node IDs.
             edges (EdgeId | Sequence[EdgeId] | tuple[str, str] | Sequence[tuple[str, str]] | None): Edge IDs.
-            involved_views (InvolvedViews | None): Whether to include involved views.
-            involved_containers (InvolvedContainers | None): Whether to include involved containers.
+            involved_views (InvolvedViews | None): Whether to include involved views. Must pass at least one of involved_views or involved_containers.
+            involved_containers (InvolvedContainers | None): Whether to include involved containers. Must pass at least one of involved_views or involved_containers.
 
         Returns:
             InstanceInspectResults: List of instance inspection results.
 
         Examples:
 
-            Look up the involved views and containers for a given node and edge:
+            Look up the involved views for a given node and edge:
 
                 >>> from cognite.client import CogniteClient
-                >>> from cognite.client.data_classes.data_modeling import NodeId, EdgeId
+                >>> from cognite.client.data_classes.data_modeling import NodeId, EdgeId, InvolvedViews
                 >>> client = CogniteClient()
                 >>> res = client.data_modeling.instances.inspect(
                 ...     nodes=NodeId("my-space", "foo1"),
                 ...     edges=EdgeId("my-space", "bar2"),
+                ...     involved_views=InvolvedViews(all_versions=False),
+                ... )
+
+            Look up the involved containers:
+
+                >>> from cognite.client.data_classes.data_modeling import InvolvedContainers
+                >>> res = client.data_modeling.instances.inspect(
+                ...     nodes=[("my-space", "foo1"), ("my-space", "foo2")],
+                ...     involved_containers=InvolvedContainers(),
                 ... )
         """
         identifiers = self._load_node_and_edge_ids(nodes, edges)
@@ -744,24 +753,21 @@ def inspect(
             inspect_operations["involvedViews"] = {"allVersions": involved_views.all_versions}
         if involved_containers:
             inspect_operations["involvedContainers"] = {}
-        options = {"inspectionOperations": inspect_operations}
+        if not inspect_operations:
+            raise ValueError("Must pass at least one of 'involved_views' or 'involved_containers'")
+
         items = list(
             itertools.chain.from_iterable(
-                self._post(self._RESOURCE_PATH + "/inspect", json={"items": chunk.as_dicts(), **options}).json()[
-                    "items"
-                ]
+                self._post(
+                    self._RESOURCE_PATH + "/inspect",
+                    json={"items": chunk.as_dicts(), "inspectionOperations": inspect_operations},
+                ).json()["items"]
                 for chunk in identifiers.chunked(1000)
             )
         )
-        node_res = InstanceInspectResultList._load(
-            [node for node in items if node["instanceType"] == "node"], cognite_client=self._cognite_client
-        )
-        edge_res = InstanceInspectResultList._load(
-            [node for node in items if node["instanceType"] == "edge"], cognite_client=self._cognite_client
-        )
         return InstanceInspectResults(
-            nodes=node_res,
-            edges=edge_res,
+            nodes=InstanceInspectResultList._load([node for node in items if node["instanceType"] == "node"]),
+            edges=InstanceInspectResultList._load([edge for edge in items if edge["instanceType"] == "edge"]),
         )
 
     def subscribe(

diff --git a/docs/source/data_modeling.rst b/docs/source/data_modeling.rst
@@ -139,6 +139,10 @@ Query instances
 ^^^^^^^^^^^^^^^^^
 .. automethod:: cognite.client._api.data_modeling.instances.InstancesAPI.query
 
+Inspect instances
+^^^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.data_modeling.instances.InstancesAPI.inspect
+
 Sync instances
 ^^^^^^^^^^^^^^^^^
 .. automethod:: cognite.client._api.data_modeling.instances.InstancesAPI.sync

diff --git a/tests/tests_integration/test_api/test_data_modeling/test_instances.py b/tests/tests_integration/test_api/test_data_modeling/test_instances.py
@@ -1138,6 +1138,16 @@ def test_listing_global_nodes(self, cognite_client: CogniteClient) -> None:
         )
         assert len(nodes) == 5
 
+    def test_inspecting_instances__no_involved_arg(
+        self, cognite_client: CogniteClient, movie_nodes: NodeList, movie_edges: EdgeList
+    ) -> None:
+        exp_err = "Must pass at least one of 'involved_views' or 'involved_containers'"
+        with pytest.raises(ValueError, match=exp_err):
+            cognite_client.data_modeling.instances.inspect(
+                nodes=movie_nodes[0].as_id(),
+                edges=movie_edges[:5].as_ids(),
+            )
+
     def test_inspecting_instances(
         self, cognite_client: CogniteClient, movie_nodes: NodeList, movie_edges: EdgeList
     ) -> None: