add refresh() method, use model_validate for external data validation

Author: purificant

src/bubble_data_api_client/client/orm.py

@@ -91,15 +91,15 @@ async def create(cls, **data: typing.Any) -> typing.Self:
         async with _get_client() as client:
             response = await client.create(cls._typename, aliased_data)
             uid = response.json()["id"]
-            return cls(**aliased_data, **{BubbleField.ID: uid})
+            return cls.model_validate({**aliased_data, BubbleField.ID: uid})
 
     @classmethod
     async def get(cls, uid: str) -> typing.Self | None:
         """Retrieve a single thing by its unique ID."""
         async with _get_client() as client:
             try:
                 response = await client.retrieve(cls._typename, uid)
-                return cls(**response.json()["response"])
+                return cls.model_validate(response.json()["response"])
             except BubbleAPIError as e:
                 if e.status_code == http.HTTPStatus.NOT_FOUND:
                     return None
@@ -141,6 +141,26 @@ async def delete(self) -> None:
         async with _get_client() as client:
             await client.delete(self._typename, self.uid)
 
+    async def refresh(self) -> typing.Self:
+        """Fetch latest data from Bubble and update this instance in place.
+
+        Useful after create_or_update() to get server-computed fields like
+        Modified Date, or fields set by Bubble workflows.
+
+        Returns:
+            Self, for method chaining.
+
+        Raises:
+            BubbleAPIError: If the record no longer exists (404) or other API error.
+        """
+        async with _get_client() as client:
+            response = await client.retrieve(self._typename, self.uid)
+            cls = type(self)
+            fresh = cls.model_validate(response.json()["response"])
+            for field_name in cls.model_fields:
+                setattr(self, field_name, getattr(fresh, field_name))
+            return self
+
     @classmethod
     async def find(
         cls,
@@ -178,7 +198,7 @@ async def find(
                 exclude_remaining=exclude_remaining,
                 additional_sort_fields=additional_sort_fields,
             )
-            return [cls(**item) for item in response.json()["response"]["results"]]
+            return [cls.model_validate(item) for item in response.json()["response"]["results"]]
 
     @classmethod
     async def find_iter(
@@ -205,7 +225,7 @@ async def find_iter(
                 )
                 body = response.json()["response"]
                 for item in body["results"]:
-                    yield cls(**item)
+                    yield cls.model_validate(item)
                 if body["remaining"] == 0:
                     break
                 cursor += len(body["results"])
@@ -273,4 +293,5 @@ async def create_or_update(
             # construct instance from aliased data
             # server-side fields like Modified Date won't be populated
             instance_data = (aliased_create_data or {}) if result["created"] else (aliased_update_data or {})
-            return cls(**aliased_match, **instance_data, **{BubbleField.ID: result["uids"][0]}), result["created"]
+            model_data = {**aliased_match, **instance_data, BubbleField.ID: result["uids"][0]}
+            return cls.model_validate(model_data), result["created"]

src/tests/unit/client/test_orm.py

@@ -1,12 +1,13 @@
 import json
+from datetime import UTC, datetime
 
 import httpx
 import pytest
 import respx
 from pydantic import Field
 
 from bubble_data_api_client.client.orm import BubbleModel
-from bubble_data_api_client.exceptions import UnknownFieldError
+from bubble_data_api_client.exceptions import BubbleAPIError, UnknownFieldError
 
 
 def test_model_instantiation():
@@ -347,3 +348,81 @@ class User(BubbleModel, typename="user"):
     assert len(users) == 2
     assert users[0].name == "Alice"
     assert users[1].name == "Bob"
+
+
+@respx.mock
+async def test_refresh_updates_instance_in_place(configured_client: None) -> None:
+    """Verify refresh() fetches data and updates the instance in place."""
+
+    class User(BubbleModel, typename="user"):
+        name: str
+        email: str | None = None
+
+    user = User(_id="abc123", name="Old Name", email=None)
+
+    respx.get("https://example.com/user/abc123").mock(
+        return_value=httpx.Response(
+            200,
+            json={"response": {"_id": "abc123", "name": "New Name", "email": "new@example.com"}},
+        )
+    )
+
+    result = await user.refresh()
+
+    # verify instance was updated in place
+    assert user.name == "New Name"
+    assert user.email == "new@example.com"
+    # verify returns self for chaining
+    assert result is user
+
+
+@respx.mock
+async def test_refresh_updates_server_computed_fields(configured_client: None) -> None:
+    """Verify refresh() populates server-computed fields like modified_date."""
+
+    class User(BubbleModel, typename="user"):
+        name: str
+
+    user = User(_id="abc123", name="Test")
+    assert user.modified_date is None
+
+    respx.get("https://example.com/user/abc123").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "response": {
+                    "_id": "abc123",
+                    "name": "Test",
+                    "Created Date": "2024-01-15T10:30:00.000Z",
+                    "Modified Date": "2024-01-16T14:20:00.000Z",
+                }
+            },
+        )
+    )
+
+    await user.refresh()
+
+    assert user.created_date == datetime(2024, 1, 15, 10, 30, 0, tzinfo=UTC)
+    assert user.modified_date == datetime(2024, 1, 16, 14, 20, 0, tzinfo=UTC)
+
+
+@respx.mock
+async def test_refresh_raises_on_not_found(configured_client: None) -> None:
+    """Verify refresh() raises BubbleAPIError when record no longer exists."""
+
+    class User(BubbleModel, typename="user"):
+        name: str
+
+    user = User(_id="deleted123", name="Ghost")
+
+    respx.get("https://example.com/user/deleted123").mock(
+        return_value=httpx.Response(
+            404,
+            json={"body": {"status": "NOT_FOUND", "message": "Thing not found"}},
+        )
+    )
+
+    with pytest.raises(BubbleAPIError) as exc_info:
+        await user.refresh()
+
+    assert exc_info.value.status_code == 404