Split create() into create() and create_multiple()

Author: tpellissier

README.md

@@ -119,7 +119,7 @@ for r in rows:
 
 ## Bulk create (CreateMultiple)
 
-Pass a list of payloads to `create(entity_set, payloads)` to invoke the collection-bound `Microsoft.Dynamics.CRM.CreateMultiple` action. The method returns a `list[str]` of created record IDs.
+Call `create_multiple(entity_set, payloads)` to invoke the collection-bound `Microsoft.Dynamics.CRM.CreateMultiple` action. The method returns a `list[str]` of created record IDs.
 
 ```python
 # Bulk create accounts (returns list of GUIDs)
@@ -128,7 +128,7 @@ payloads = [
 	{"name": "Fabrikam"},
 	{"name": "Northwind"},
 ]
-ids = client.create("accounts", payloads)
+ids = client.create_multiple("accounts", payloads)
 assert isinstance(ids, list) and all(isinstance(x, str) for x in ids)
 print({"created_ids": ids})
 ```
@@ -268,7 +268,7 @@ client.delete_table("SampleItem")        # delete the table
 
 Notes:
 - `create/update` return the full record using `Prefer: return=representation`.
-- Passing a list of payloads to `create` triggers bulk create and returns `list[str]` of IDs.
+- Use `create_multiple` for bulk create; single `create` only accepts a dict payload.
 - Use `get_multiple` for paging through result sets; prefer `select` to limit columns.
 - For CRUD methods that take a record id, pass the GUID string (36-char hyphenated). Parentheses around the GUID are accepted but not required.
 * SQL queries are executed directly against entity set endpoints using the `?sql=` parameter. Supported subset only (single SELECT, optional WHERE/TOP/ORDER BY, alias). Unsupported constructs will be rejected by the service.

examples/quickstart.py

@@ -188,9 +188,9 @@ def print_line_summaries(label: str, summaries: list[dict]) -> None:
 	if rid1:
 		record_ids.append(rid1)
 
-	# Multi create (list) now returns list[str] of IDs
-	log_call(f"client.create('{entity_set}', multi_payloads)")
-	multi_ids = backoff_retry(lambda: client.create(entity_set, multi_payloads))
+	# Multi create via create_multiple now returns list[str] of IDs
+	log_call(f"client.create_multiple('{entity_set}', multi_payloads)")
+	multi_ids = backoff_retry(lambda: client.create_multiple(entity_set, multi_payloads))
 	if isinstance(multi_ids, list):
 		for mid in multi_ids:
 			if isinstance(mid, str):

src/dataverse_sdk/client.py

@@ -63,33 +63,19 @@ def _get_odata(self) -> ODataClient:
         return self._odata
 
     # CRUD
-    def create(self, entity: str, record_data: Union[Dict[str, Any], List[Dict[str, Any]]]) -> Union[Dict[str, Any], List[str]]:
-        """Create one or more records.
+    def create(self, entity: str, record_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Create a single record.
 
-        Behaviour:
-        - Single: returns the created record (dict) using Prefer: return=representation.
-        - Multiple: uses bound CreateMultiple action and returns list[str] of created record IDs.
+        Returns the created record representation (if provided by the service).
+        """
+        return self._get_odata().create(entity, record_data)
 
-        Parameters
-        ----------
-        entity : str
-            Entity set name (plural logical name), e.g., ``"accounts"``.
-        record_data : dict | list[dict]
-            Single record payload or list of records for multi-create.
+    def create_multiple(self, entity: str, records: List[Dict[str, Any]]) -> List[str]:
+        """Create multiple records via the bound CreateMultiple action.
 
-        Returns
-        -------
-        dict | list[str]
-            Dict for single create, list of GUID strings for multi-create.
-
-        Raises
-        ------
-        requests.exceptions.HTTPError
-            If the request fails.
-        TypeError
-            If ``record_data`` is not a dict or list of dict.
+        Returns list of created record GUID strings.
         """
-        return self._get_odata().create(entity, record_data)
+        return self._get_odata().create_multiple(entity, records)
 
     def update(self, entity: str, record_id: str, record_data: dict) -> dict:
         """Update a record and return its full representation.

src/dataverse_sdk/odata.py

@@ -48,37 +48,30 @@ def _request(self, method: str, url: str, **kwargs):
         return self._http.request(method, url, **kwargs)
 
     # ----------------------------- CRUD ---------------------------------
-    def create(self, entity_set: str, data: Union[Dict[str, Any], List[Dict[str, Any]]]) -> Union[Dict[str, Any], List[str]]:
-        """Create one or many records.
+    def create(self, entity_set: str, record: Dict[str, Any]) -> Dict[str, Any]:
+        """Create a single record and return its representation.
 
-        Parameters
-        ----------
-        entity_set : str
-            Entity set (plural logical name), e.g. "accounts".
-        data : dict | list[dict]
-            Single entity payload or list of payloads for batch create.
+        POST /{entity_set} with Prefer: return=representation.
+        """
+        if not isinstance(record, dict):
+            raise TypeError("record must be a dict for single create")
+        return self._create_single(entity_set, record)
 
-        Behaviour
-        ---------
-        - Single (dict): POST /{entity_set} with Prefer: return=representation. Returns created record (dict).
-        - Multiple (list[dict]): POST /{entity_set}/Microsoft.Dynamics.CRM.CreateMultiple. Returns list[str] of created GUIDs.
+    def create_multiple(self, entity_set: str, records: List[Dict[str, Any]]) -> List[str]:
+        """Create multiple records via the bound CreateMultiple action.
 
-        Multi-create logical name resolution
-        ------------------------------------
-        - If any payload omits ``@odata.type`` the client performs a metadata lookup (once per entity set, cached)
-          to resolve the logical name and stamps ``Microsoft.Dynamics.CRM.<logical>`` into missing payloads.
-        - If all payloads already include ``@odata.type`` no lookup or modification occurs.
+        POST /{entity_set}/Microsoft.Dynamics.CRM.CreateMultiple
 
-        Returns
-        -------
-        dict | list[str]
-            Created entity (single) or list of created IDs (multi).
+        Returns list[str] of created GUIDs.
+
+        Multi-create logical name resolution:
+        - If any payload omits @odata.type the client performs metadata lookup (cached per entity set)
+          to resolve the logical name and injects Microsoft.Dynamics.CRM.<logical>.
+        - If all payloads include @odata.type no lookup occurs.
         """
-        if isinstance(data, dict):
-            return self._create_single(entity_set, data)
-        if isinstance(data, list):
-            return self._create_multiple(entity_set, data)
-        raise TypeError("data must be dict or list[dict]")
+        if not isinstance(records, list) or not all(isinstance(r, dict) for r in records):
+            raise TypeError("records must be list[dict] for create_multiple")
+        return self._create_multiple(entity_set, records)
 
     # --- Internal helpers ---
     def _create_single(self, entity_set: str, record: Dict[str, Any]) -> Dict[str, Any]: