Restrict match parameter to individual mode only, remove from batch mode

Co-authored-by: MarcusRisanger <69350948+MarcusRisanger@users.noreply.github.com>

Author: Copilot

UPSERT_MATCH_EXAMPLE.md

@@ -2,6 +2,8 @@
 
 The `match` parameter in the `upsert` method allows you to control whether the operation should only create new records or only update existing ones.
 
+**Note:** The `match` parameter is only supported for **individual mode**, not batch mode.
+
 ## Usage
 
 ### Standard Upsert (Default Behavior)
@@ -14,25 +16,31 @@ entity.upsert(data, mode="individual")
 ```python
 # Only updates existing records, will fail if record doesn't exist
 # Uses If-Match: * header
+# Only works with mode="individual"
 entity.upsert(data, mode="individual", match="prevent_create")
 ```
 
 ### Prevent Update (Only Create)
 ```python
 # Only creates new records, will fail if record already exists
 # Uses If-None-Match: * header
+# Only works with mode="individual"
 entity.upsert(data, mode="individual", match="prevent_update")
 ```
 
-## Batch Mode Support
-The `match` parameter works with both individual and batch modes:
+## Batch Mode
+The `match` parameter is **not supported** for batch mode operations. Attempting to use it will raise a `DataverseError`:
 
 ```python
-# Batch mode with prevent_create
-entity.upsert(data, mode="batch", match="prevent_create")
+# This will raise an error
+entity.upsert(data, mode="batch", match="prevent_create")  # Error!
+```
 
-# Batch mode with prevent_update
-entity.upsert(data, mode="batch", match="prevent_update")
+For batch operations, use standard upsert behavior without the `match` parameter:
+
+```python
+# Standard batch upsert (create or update)
+entity.upsert(data, mode="batch")
 ```
 
 ## Reference

dataverse_api/entity.py

@@ -749,7 +749,6 @@ def upsert(
         altkey_name: str | None = None,
         threading: bool = False,
         batch_size: int | None = None,
-        match: Literal["prevent_create", "prevent_update"] | None = None,
     ) -> list[requests.Response]: ...
 
     def upsert(
@@ -780,11 +779,15 @@ def upsert(
             Optional override if batch mode is specified, useful for tuning workloads
             if 429s or timeouts occur.
         match : Literal["prevent_create", "prevent_update"] | None
-            Controls upsert behavior using If-Match headers:
+            Controls upsert behavior using If-Match headers.
+            Only supported for individual mode, not batch mode.
             - None (default): Standard upsert behavior (create or update)
             - "prevent_create": Only update existing records (If-Match: *)
             - "prevent_update": Only create new records (If-None-Match: *)
         """
+        if match is not None and mode == "batch":
+            raise DataverseError("The 'match' parameter is only supported for individual mode, not batch mode.")
+
         if altkey_name is not None:
             try:
                 key_columns = self.alternate_keys[altkey_name]
@@ -813,7 +816,6 @@ def upsert(
                 data=data,
                 keys=key_columns,
                 is_primary_id=is_primary_id,
-                match=match,
             )
             return self._batch_api_call(
                 batch_commands=batch_commands,

dataverse_api/utils/batching.py

@@ -4,7 +4,7 @@
 from dataclasses import dataclass, field
 from enum import StrEnum
 from textwrap import dedent
-from typing import Any, Collection, Generator, Literal, Mapping, MutableMapping, TypeVar
+from typing import Any, Collection, Generator, Mapping, MutableMapping, TypeVar
 from urllib.parse import urljoin
 
 from dataverse_api.errors import DataverseError
@@ -209,7 +209,6 @@ def transform_to_batch_for_upsert(
     data: Collection[MutableMapping[str, Any]],
     keys: Iterable[str],
     is_primary_id: bool = False,
-    match: Literal["prevent_create", "prevent_update"] | None = None,
 ) -> list[BatchCommand]:
     """
     Transform data payload to upsert batch data.
@@ -224,27 +223,15 @@ def transform_to_batch_for_upsert(
         The keys used to identify unique rows in the dataset.
     is_id : bool
         Whether the supplied singular key is the Entity primary ID attribute.
-    match : Literal["prevent_create", "prevent_update"] | None
-        Controls upsert behavior using If-Match headers:
-        - None (default): Standard upsert behavior (create or update)
-        - "prevent_create": Only update existing records (If-Match: *)
-        - "prevent_update": Only create new records (If-None-Match: *)
     """
     check_altkey_support(keys=keys, data=data)
-    headers: dict[str, str] | None = None
-    if match == "prevent_create":
-        headers = {"If-Match": "*"}
-    elif match == "prevent_update":
-        headers = {"If-None-Match": "*"}
-
     commands = []
     for keys, payload in transform_upsert_data(data, keys, is_primary_id):
         commands.append(
             BatchCommand(
                 url=f"{url}({keys})",
                 method=RequestMethod.PATCH,
                 data=payload,
-                headers=headers,
             )
         )
 

tests/test_entity.py

@@ -766,48 +766,15 @@ def test_entity_upsert_individual_prevent_update(
         assert row.status_code == 204
 
 
-def test_entity_upsert_batch_prevent_create(
-    entity: DataverseEntity,
-    primary_id: str,
-    mocked_responses: responses.RequestsMock,
-):
-    """Test batch upsert with prevent_create (If-Match: *) - only update existing records."""
-    # Setup
-    data = [{primary_id: str(uuid4()), "test_val": random.randint(1, 10)} for _ in range(4)]
-
-    mocked_responses.post(url=f"{entity._endpoint}$batch")
-
-    resp = entity.upsert(data=data, mode="batch", match="prevent_create")
-
-    assert isinstance(resp[0].request.body, str)  # type checking
-    elements = resp[0].request.body.split("--batch")[1:-1]
-
-    for out, expected in zip(elements, data):
-        assert f"{entity.entity_set_name}({expected.pop(primary_id)})" in out
-        assert "If-Match: *" in out
-        assert serialize_json(expected) in out
-
-
-def test_entity_upsert_batch_prevent_update(
-    entity: DataverseEntity,
-    primary_id: str,
-    mocked_responses: responses.RequestsMock,
-):
-    """Test batch upsert with prevent_update (If-None-Match: *) - only create new records."""
-    # Setup
-    data = [{primary_id: str(uuid4()), "test_val": random.randint(1, 10)} for _ in range(4)]
-
-    mocked_responses.post(url=f"{entity._endpoint}$batch")
-
-    resp = entity.upsert(data=data, mode="batch", match="prevent_update")
-
-    assert isinstance(resp[0].request.body, str)  # type checking
-    elements = resp[0].request.body.split("--batch")[1:-1]
-
-    for out, expected in zip(elements, data):
-        assert f"{entity.entity_set_name}({expected.pop(primary_id)})" in out
-        assert "If-None-Match: *" in out
-        assert serialize_json(expected) in out
+def test_entity_upsert_batch_match_not_supported(entity: DataverseEntity, primary_id: str):
+    """Test that using match parameter with batch mode raises an error."""
+    data = [{primary_id: str(uuid4()), "test_val": 1}]
+    
+    with pytest.raises(DataverseError, match=r".*match.*only supported for individual mode.*"):
+        entity.upsert(data=data, mode="batch", match="prevent_create")  # type: ignore
+    
+    with pytest.raises(DataverseError, match=r".*match.*only supported for individual mode.*"):
+        entity.upsert(data=data, mode="batch", match="prevent_update")  # type: ignore
 
 
 def test_entity_upsert_pandas_dataframe(