Add match parameter to upsert method with prevent_create and prevent_update modes

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

Author: Copilot

dataverse_api/entity.py

@@ -699,17 +699,29 @@ def delete_columns(
         raise DataverseModeError(mode, "individual", "batch")
 
     def __upsert_singles(
-        self, data: Collection[Mapping[str, Any]], keys: Iterable[str], is_primary_id: bool, threading: bool
+        self,
+        data: Collection[Mapping[str, Any]],
+        keys: Iterable[str],
+        is_primary_id: bool,
+        threading: bool,
+        match: Literal["prevent_create", "prevent_update"] | None = None,
     ) -> list[requests.Response]:
         """
         Upsert row by individual requests.
         """
         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": "*"}
+
         calls = [
             APICommand(
                 method=RequestMethod.PATCH,
                 url=f"{self.entity_set_name}({key})",
                 json=payload,
+                headers=headers,
             )
             for key, payload in transform_upsert_data(data=data, keys=keys, is_primary_id=is_primary_id)
         ]
@@ -725,6 +737,7 @@ def upsert(
         mode: Literal["individual"] = "individual",
         altkey_name: str | None = None,
         threading: bool = False,
+        match: Literal["prevent_create", "prevent_update"] | None = None,
     ) -> list[requests.Response]: ...
 
     @overload
@@ -736,6 +749,7 @@ 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(
@@ -746,6 +760,7 @@ 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]:
         """
         Upsert data into Entity.
@@ -764,6 +779,11 @@ def upsert(
         batch_size : int
             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:
+            - 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 altkey_name is not None:
             try:
@@ -782,7 +802,9 @@ def upsert(
 
         if mode == "individual":
             logging.debug("%d rows to upsert. Using individual upserts.", len(data))
-            return self.__upsert_singles(data=data, keys=key_columns, is_primary_id=is_primary_id, threading=threading)
+            return self.__upsert_singles(
+                data=data, keys=key_columns, is_primary_id=is_primary_id, threading=threading, match=match
+            )
 
         if mode == "batch":
             logging.debug("%d rows to upsert. Using batch upserts.", len(data))
@@ -791,6 +813,7 @@ 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, Mapping, MutableMapping, TypeVar
+from typing import Any, Collection, Generator, Literal, Mapping, MutableMapping, TypeVar
 from urllib.parse import urljoin
 
 from dataverse_api.errors import DataverseError
@@ -209,6 +209,7 @@ 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.
@@ -223,15 +224,27 @@ 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

@@ -716,6 +716,100 @@ def test_entity_upsert_bad_altkey(entity: DataverseEntity):
         entity.upsert([{"data": 1}], altkey_name="foo")
 
 
+def test_entity_upsert_individual_prevent_create(
+    entity: DataverseEntity,
+    primary_id: str,
+    mocked_responses: responses.RequestsMock,
+):
+    """Test 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)]
+
+    for row in data:
+        id = row[primary_id]
+        payload = {k: v for k, v in row.items() if k != primary_id}
+
+        mocked_responses.patch(
+            url=f"{entity._endpoint}{entity.entity_set_name}({id})",
+            match=[json_params_matcher(payload), header_matcher({"If-Match": "*"})],
+            status=204,
+        )
+
+    resp = entity.upsert(data, mode="individual", match="prevent_create")
+
+    for row in resp:
+        assert row.status_code == 204
+
+
+def test_entity_upsert_individual_prevent_update(
+    entity: DataverseEntity,
+    primary_id: str,
+    mocked_responses: responses.RequestsMock,
+):
+    """Test 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)]
+
+    for row in data:
+        id = row[primary_id]
+        payload = {k: v for k, v in row.items() if k != primary_id}
+
+        mocked_responses.patch(
+            url=f"{entity._endpoint}{entity.entity_set_name}({id})",
+            match=[json_params_matcher(payload), header_matcher({"If-None-Match": "*"})],
+            status=204,
+        )
+
+    resp = entity.upsert(data, mode="individual", match="prevent_update")
+
+    for row in resp:
+        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_pandas_dataframe(
     entity: DataverseEntity, mocked_responses: responses.RequestsMock, primary_id: str
 ):