Enhance SKILL.md and examples with improved documentation and usage of QueryResult indexing

Author: Samson Gebre

.claude/skills/dataverse-sdk-use/SKILL.md

@@ -38,7 +38,8 @@ The SDK supports Dataverse's native bulk operations: Pass lists to `create()`, `
 - Returned by `records.list()`, `records.retrieve()`, `execute()`, and each page from `list_pages()` / `execute_pages()`
 - Iterable: `for record in result` — each item is a `dict`-like `Record`
 - `.to_dataframe()` — convert to pandas DataFrame
-- `.first()` — return the first record or `None`
+- `.first()` — return the first record or `None` (safe: returns `None` on empty result)
+- `result[n]` — index access returns a `Record`; `result[n:m]` returns a `QueryResult`
 - `len(result)` — number of records in this result/page
 
 ### DataFrame Support

examples/advanced/fetchxml.py

@@ -268,6 +268,10 @@ def _run_examples(client):
         print(f"[OK] {len(result)} projects:")
         for r in result:
             print(f"  {r.get('new_code', ''):<10s}  Budget={r.get('new_budget')}  Active={r.get('new_active')}")
+        # Index access and first() are equivalent; first() returns None on empty result
+        if result:
+            print(f"  First by index : {result[0].get('new_code')}")
+            print(f"  First by .first(): {result.first().get('new_code')}")
 
         # ===============================================================
         # 4. <condition> operators: eq, like, in, null, not-null, between

examples/basic/installation_example.py

@@ -239,9 +239,8 @@ def show_usage_examples():
                      select=["name", "telephone1"],
                      top=10)
 
-for page in accounts:
-    for account in page:
-        print(f"Account: {account['name']}")
+for account in accounts:
+    print(f"Account: {account['name']}")
 
 # SQL queries (if enabled)
 results = client.query.sql("SELECT TOP 5 name FROM account")

src/PowerPlatform/Dataverse/claude_skill/dataverse-sdk-use/SKILL.md

@@ -38,7 +38,8 @@ The SDK supports Dataverse's native bulk operations: Pass lists to `create()`, `
 - Returned by `records.list()`, `records.retrieve()`, `execute()`, and each page from `list_pages()` / `execute_pages()`
 - Iterable: `for record in result` — each item is a `dict`-like `Record`
 - `.to_dataframe()` — convert to pandas DataFrame
-- `.first()` — return the first record or `None`
+- `.first()` — return the first record or `None` (safe: returns `None` on empty result)
+- `result[n]` — index access returns a `Record`; `result[n:m]` returns a `QueryResult`
 - `len(result)` — number of records in this result/page
 
 ### DataFrame Support

src/PowerPlatform/Dataverse/models/query_builder.py

@@ -513,9 +513,9 @@ def execute(self, *, by_page=_BY_PAGE_UNSET) -> Union[QueryResult, Iterator[Quer
                 "Use build() and pass parameters to client.records.list() instead."
             )
 
-        if not self._select and not self._filter_parts and self._top is None:
+        if not self._select and not self._filter_parts and self._top is None and self._page_size is None:
             raise ValueError(
-                "At least one of select(), where(), or top() must be called before "
+                "At least one of select(), where(), top(), or page_size() must be called before "
                 "execute() to prevent accidental full-table scans."
             )
 
@@ -577,9 +577,9 @@ def execute_pages(self) -> Iterator[QueryResult]:
                 "Use build() and pass parameters to client.records.list() instead."
             )
 
-        if not self._select and not self._filter_parts and self._top is None:
+        if not self._select and not self._filter_parts and self._top is None and self._page_size is None:
             raise ValueError(
-                "At least one of select(), where(), or top() must be called before "
+                "At least one of select(), where(), top(), or page_size() must be called before "
                 "execute_pages() to prevent accidental full-table scans."
             )
 

src/PowerPlatform/Dataverse/models/record.py

@@ -141,6 +141,10 @@ def __bool__(self) -> bool:
     def __repr__(self) -> str:
         return f"QueryResult({len(self.records)} records)"
 
+    def __getitem__(self, index):
+        result = self.records[index]
+        return QueryResult(result) if isinstance(index, slice) else result
+
     def first(self) -> Optional[Record]:
         """Return the first record, or ``None`` if the result is empty."""
         return self.records[0] if self.records else None

src/PowerPlatform/Dataverse/operations/records.py

@@ -8,7 +8,6 @@
 import warnings
 from typing import Any, Dict, Iterable, Iterator, List, Optional, Union, overload, TYPE_CHECKING
 
-from ..models.protocol import DataverseModel
 from ..models.record import QueryResult, Record
 from ..models.upsert import UpsertItem
 
@@ -57,16 +56,10 @@ def create(self, table: str, data: Dict[str, Any]) -> str: ...
     @overload
     def create(self, table: str, data: List[Dict[str, Any]]) -> List[str]: ...
 
-    @overload
-    def create(self, table_or_entity: DataverseModel, data: None = None) -> str: ...
-
-    @overload
-    def create(self, table_or_entity: List[DataverseModel], data: None = None) -> List[str]: ...
-
     def create(
         self,
-        table_or_entity: Union[str, DataverseModel, List[DataverseModel]],
-        data: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = None,
+        table: str,
+        data: Union[Dict[str, Any], List[Dict[str, Any]]],
     ) -> Union[str, List[str]]:
         """Create one or more records in a Dataverse table.
 
@@ -87,49 +80,19 @@ def create(
         :raises TypeError: If ``data`` is not a dict or list[dict].
 
         Example:
-            Create a single record (dict form)::
+            Create a single record::
 
                 guid = client.records.create("account", {"name": "Contoso"})
                 print(f"Created: {guid}")
 
-            Create multiple records (dict form)::
+            Create multiple records::
 
                 guids = client.records.create("account", [
                     {"name": "Contoso"},
                     {"name": "Fabrikam"},
                 ])
                 print(f"Created {len(guids)} accounts")
-
-            Create from a DataverseModel instance::
-
-                guid = client.records.create(Account(name="Contoso"))
         """
-        # DataverseModel dispatch: list of entities
-        if isinstance(table_or_entity, list) and table_or_entity and isinstance(table_or_entity[0], DataverseModel):
-            entities = table_or_entity
-            table = entities[0].__entity_logical_name__
-            data_list = [e.to_dict() for e in entities]
-            with self._client._scoped_odata() as od:
-                entity_set = od._entity_set_from_schema_name(table)
-                ids = od._create_multiple(entity_set, table, data_list)
-                if not isinstance(ids, list) or not all(isinstance(x, str) for x in ids):
-                    raise TypeError("_create (multi) did not return list[str]")
-                return ids
-
-        # DataverseModel dispatch: single entity
-        if isinstance(table_or_entity, DataverseModel):
-            entity = table_or_entity
-            table = entity.__entity_logical_name__
-            record_data = entity.to_dict()
-            with self._client._scoped_odata() as od:
-                entity_set = od._entity_set_from_schema_name(table)
-                rid = od._create(entity_set, table, record_data)
-                if not isinstance(rid, str):
-                    raise TypeError("_create (single) did not return GUID string")
-                return rid
-
-        # Existing str/dict path
-        table = table_or_entity  # type: ignore[assignment]
         with self._client._scoped_odata() as od:
             entity_set = od._entity_set_from_schema_name(table)
             if isinstance(data, dict):
@@ -148,9 +111,9 @@ def create(
 
     def update(
         self,
-        table_or_entity: Union[str, DataverseModel],
-        ids: Optional[Union[str, List[str]]] = None,
-        changes: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = None,
+        table: str,
+        ids: Union[str, List[str]],
+        changes: Union[Dict[str, Any], List[Dict[str, Any]]],
     ) -> None:
         """Update one or more records in a Dataverse table.
 
@@ -191,28 +154,7 @@ def update(
                     [{"name": "Name A"}, {"name": "Name B"}],
                 )
 
-            Update from a DataverseModel instance::
-
-                client.records.update(Account(name="Contoso Updated"), account_id)
         """
-        # DataverseModel dispatch: entity provides table + changes
-        if isinstance(table_or_entity, DataverseModel):
-            entity = table_or_entity
-            table = entity.__entity_logical_name__
-            record_data = entity.to_dict()
-            if ids is None:
-                raise TypeError("record_id must be provided when updating from a DataverseModel")
-            with self._client._scoped_odata() as od:
-                if isinstance(ids, str):
-                    od._update(table, ids, record_data)
-                    return None
-                if isinstance(ids, list):
-                    od._update_by_ids(table, ids, record_data)
-                    return None
-            return None
-
-        # Existing str/dict path
-        table: str = table_or_entity  # type: ignore[assignment]
         with self._client._scoped_odata() as od:
             if isinstance(ids, str):
                 if not isinstance(changes, dict):

tests/unit/test_phase2_ga.py

@@ -84,6 +84,37 @@ def test_first_returns_first_record(self):
     def test_first_returns_none_when_empty(self):
         self.assertIsNone(QueryResult([]).first())
 
+    # ----- __getitem__
+
+    def test_getitem_int_returns_record(self):
+        recs = self._records(3)
+        qr = QueryResult(recs)
+        self.assertIs(qr[0], recs[0])
+        self.assertIs(qr[2], recs[2])
+
+    def test_getitem_negative_index(self):
+        recs = self._records(3)
+        qr = QueryResult(recs)
+        self.assertIs(qr[-1], recs[-1])
+
+    def test_getitem_out_of_range_raises(self):
+        qr = QueryResult(self._records(2))
+        with self.assertRaises(IndexError):
+            _ = qr[99]
+
+    def test_getitem_slice_returns_query_result(self):
+        recs = self._records(5)
+        qr = QueryResult(recs)
+        sliced = qr[1:3]
+        self.assertIsInstance(sliced, QueryResult)
+        self.assertEqual(list(sliced), recs[1:3])
+
+    def test_getitem_slice_empty(self):
+        qr = QueryResult(self._records(3))
+        sliced = qr[10:]
+        self.assertIsInstance(sliced, QueryResult)
+        self.assertEqual(len(sliced), 0)
+
     # ----- to_dataframe()
 
     def test_to_dataframe_nonempty(self):

tests/unit/test_phase3_ga.py

@@ -7,11 +7,12 @@
 - records.get() deprecation (DeprecationWarning, still functional)
 - records.retrieve() — single record, None on 404
 - records.list() — QueryResult, accepts str/FilterExpression filter
-- DataverseModel Protocol and isinstance() check
-- records.create(DataverseModel) dispatch
-- records.update(DataverseModel, record_id) dispatch
+- DataverseModel Protocol definition and isinstance() check
 - DataverseModel exported from models and package root
 - execute() emits zero DeprecationWarning (internal records.get() suppressed)
+
+Note: records.create(DataverseModel) and records.update(DataverseModel) dispatch
+are deferred to post-GA and are not covered here.
 """
 
 import unittest
@@ -310,88 +311,6 @@ def test_list_result_to_dataframe(self):
         self.assertEqual(len(df), 2)
 
 
-class TestCreateWithDataverseModel(unittest.TestCase):
-    """records.create() accepts DataverseModel."""
-
-    def setUp(self):
-        self.client = _make_client()
-        self.client._odata._create.return_value = "new-guid-123"
-        self.client._odata._create_multiple.return_value = ["guid-1", "guid-2"]
-
-    def test_create_single_entity(self):
-        account = _Account(name="Contoso", telephone1="555-0100")
-        result = self.client.records.create(account)
-        self.assertEqual(result, "new-guid-123")
-
-    def test_create_single_entity_uses_logical_name(self):
-        account = _Account(name="Contoso")
-        self.client.records.create(account)
-        self.client._odata._entity_set_from_schema_name.assert_called_with("account")
-
-    def test_create_single_entity_calls_to_dict(self):
-        account = _Account(name="Contoso", telephone1="555-0100")
-        self.client.records.create(account)
-        self.client._odata._create.assert_called_once()
-        call_args = self.client._odata._create.call_args
-        self.assertEqual(call_args[0][2]["name"], "Contoso")
-
-    def test_create_list_of_entities(self):
-        entities = [_Account(name="A"), _Account(name="B")]
-        result = self.client.records.create(entities)
-        self.assertEqual(result, ["guid-1", "guid-2"])
-
-    def test_create_list_uses_first_entity_logical_name(self):
-        entities = [_Account(name="A"), _Account(name="B")]
-        self.client.records.create(entities)
-        self.client._odata._entity_set_from_schema_name.assert_called_with("account")
-
-    def test_create_entity_no_deprecation_warning(self):
-        with warnings.catch_warnings(record=True) as caught:
-            warnings.simplefilter("always")
-            self.client.records.create(_Account(name="Contoso"))
-        dep = [w for w in caught if issubclass(w.category, DeprecationWarning)]
-        self.assertEqual(dep, [])
-
-    def test_create_dict_path_still_works(self):
-        result = self.client.records.create("account", {"name": "Contoso"})
-        self.assertEqual(result, "new-guid-123")
-
-    def test_create_list_dict_path_still_works(self):
-        result = self.client.records.create("account", [{"name": "A"}, {"name": "B"}])
-        self.assertEqual(result, ["guid-1", "guid-2"])
-
-
-class TestUpdateWithDataverseModel(unittest.TestCase):
-    """records.update() accepts DataverseModel as first arg."""
-
-    def setUp(self):
-        self.client = _make_client()
-
-    def test_update_single_entity_with_id(self):
-        account = _Account(name="Updated Name")
-        self.client.records.update(account, "guid-abc")
-        self.client._odata._update.assert_called_once_with(
-            "account", "guid-abc", {"name": "Updated Name", "telephone1": ""}
-        )
-
-    def test_update_entity_no_id_raises(self):
-        account = _Account(name="Updated")
-        with self.assertRaises(TypeError):
-            self.client.records.update(account)
-
-    def test_update_entity_no_deprecation_warning(self):
-        account = _Account(name="Updated")
-        with warnings.catch_warnings(record=True) as caught:
-            warnings.simplefilter("always")
-            self.client.records.update(account, "guid-abc")
-        dep = [w for w in caught if issubclass(w.category, DeprecationWarning)]
-        self.assertEqual(dep, [])
-
-    def test_update_dict_path_still_works(self):
-        self.client.records.update("account", "guid-1", {"name": "New Name"})
-        self.client._odata._update.assert_called_with("account", "guid-1", {"name": "New Name"})
-
-
 class TestExecuteNoDeprecationFromRecordsGet(unittest.TestCase):
     """execute() suppresses DeprecationWarning from the internal records.get() call."""
 

tests/unit/test_records_operations.py

@@ -2,7 +2,6 @@
 # Licensed under the MIT license.
 
 import unittest
-import warnings
 from unittest.mock import MagicMock
 
 from azure.core.credentials import TokenCredential