add orm level update() for targeted data changes

Author: purificant

src/bubble_data_api_client/client/orm.py

@@ -7,6 +7,7 @@
 
 from bubble_data_api_client.client.raw_client import RawClient
 from bubble_data_api_client.constraints import Constraint, ConstraintType, constraint
+from bubble_data_api_client.exceptions import UnknownFieldError
 from bubble_data_api_client.types import BubbleField, OnMultiple
 
 
@@ -60,6 +61,23 @@ async def save(self) -> None:
             response = await client.update(self._typename, self.uid, data)
             response.raise_for_status()
 
+    @classmethod
+    async def update(cls, uid: str, **data: typing.Any) -> None:
+        """Update specific fields on a thing by its unique ID."""
+        aliased_data: dict[str, typing.Any] = {}
+        for field_name, value in data.items():
+            field_info = cls.model_fields.get(field_name)
+            if field_info is None:
+                raise UnknownFieldError(field_name)
+            if field_info.alias:
+                aliased_data[field_info.alias] = value
+            else:
+                aliased_data[field_name] = value
+
+        async with _get_client() as client:
+            response = await client.update(cls._typename, uid, aliased_data)
+            response.raise_for_status()
+
     async def delete(self) -> None:
         async with _get_client() as client:
             response = await client.delete(self._typename, self.uid)

src/bubble_data_api_client/exceptions.py

@@ -25,6 +25,14 @@ def __init__(self, value: str) -> None:
         self.value = value
 
 
+class UnknownFieldError(BubbleError):
+    """Raised when an unknown field name is passed to update()."""
+
+    def __init__(self, field_name: str) -> None:
+        super().__init__(f"unknown field: {field_name}")
+        self.field_name = field_name
+
+
 class MultipleMatchesError(BubbleError):
     """Raised when create_or_update finds multiple matches with on_multiple='error'."""
 

src/tests/unit/client/test_orm.py

@@ -1,10 +1,12 @@
 import json
 
 import httpx
+import pytest
 import respx
 from pydantic import Field
 
 from bubble_data_api_client.client.orm import BubbleBaseModel
+from bubble_data_api_client.exceptions import UnknownFieldError
 
 
 def test_model_instantiation():
@@ -36,3 +38,47 @@ class Order(BubbleBaseModel, typename="order"):
     assert route.call_count == 1
     request_body = json.loads(route.calls[0].request.content)
     assert request_body == {"Buying company": "Acme Corp"}
+
+
+@respx.mock
+async def test_update_single_field(configured_client: None) -> None:
+    """Verify update() sends only the specified field."""
+
+    class User(BubbleBaseModel, typename="user"):
+        name: str
+        email: str
+
+    route = respx.patch("https://example.com/user/abc123").mock(return_value=httpx.Response(204))
+
+    await User.update(uid="abc123", name="New Name")
+
+    assert route.call_count == 1
+    request_body = json.loads(route.calls[0].request.content)
+    assert request_body == {"name": "New Name"}
+
+
+@respx.mock
+async def test_update_translates_field_aliases(configured_client: None) -> None:
+    """Verify update() translates Python field names to Bubble aliases."""
+
+    class Order(BubbleBaseModel, typename="order"):
+        company: str = Field(alias="Buying company")
+        status: str
+
+    route = respx.patch("https://example.com/order/xyz789").mock(return_value=httpx.Response(204))
+
+    await Order.update(uid="xyz789", company="Acme Corp", status="active")
+
+    assert route.call_count == 1
+    request_body = json.loads(route.calls[0].request.content)
+    assert request_body == {"Buying company": "Acme Corp", "status": "active"}
+
+
+async def test_update_raises_for_unknown_field() -> None:
+    """Verify update() raises UnknownFieldError for fields not in the model."""
+
+    class User(BubbleBaseModel, typename="user"):
+        name: str
+
+    with pytest.raises(UnknownFieldError, match="unknown field: nonexistent"):
+        await User.update(uid="abc123", nonexistent="value")