ORM model now provides built-in fields by default

Author: purificant

README.md

@@ -54,7 +54,7 @@ active_count = await User.count(constraints=[
 Models provide autocomplete and catch errors before runtime:
 
 ```python
-class User(BubbleBaseModel, typename="user"):
+class User(BubbleModel, typename="user"):
     name: str
     email: str
     age: int
@@ -76,7 +76,7 @@ user = User(_id="123x456", name="Ada", email="ada@example.com", age="twenty-five
 # ValidationError: Input should be a valid integer
 
 # Invalid Bubble UID caught at the model level
-class Order(BubbleBaseModel, typename="order"):
+class Order(BubbleModel, typename="order"):
     customer: BubbleUID
 
 order = Order(_id="123x456", customer="not-a-valid-uid")
@@ -158,14 +158,14 @@ set_config_provider(get_config)
 Define typed models with validation:
 
 ```python
-from bubble_data_api_client import BubbleBaseModel, BubbleUID, OptionalBubbleUID
+from bubble_data_api_client import BubbleModel, BubbleUID, OptionalBubbleUID
 
-class User(BubbleBaseModel, typename="user"):
+class User(BubbleModel, typename="user"):
     name: str
     email: str
     company: OptionalBubbleUID = None  # linked Bubble record
 
-class Company(BubbleBaseModel, typename="company"):
+class Company(BubbleModel, typename="company"):
     name: str
     industry: str
 ```
@@ -257,9 +257,9 @@ Available constraint types: `EQUALS`, `NOT_EQUAL`, `IS_EMPTY` (any field), `IS_N
 Validate Bubble record IDs at the type level:
 
 ```python
-from bubble_data_api_client import BubbleBaseModel, BubbleUID, OptionalBubbleUID, OptionalBubbleUIDs
+from bubble_data_api_client import BubbleModel, BubbleUID, OptionalBubbleUID, OptionalBubbleUIDs
 
-class Order(BubbleBaseModel, typename="order"):
+class Order(BubbleModel, typename="order"):
     customer: BubbleUID                    # required, validated
     referrer: OptionalBubbleUID = None     # optional, coerces invalid to None
     items: OptionalBubbleUIDs = None       # list of UIDs, filters invalid
@@ -316,9 +316,9 @@ This library is async-only, but you can use it in sync code:
 
 ```python
 import asyncio
-from bubble_data_api_client import BubbleBaseModel, constraint, ConstraintType
+from bubble_data_api_client import BubbleModel, constraint, ConstraintType
 
-class User(BubbleBaseModel, typename="user"):
+class User(BubbleModel, typename="user"):
     name: str
     email: str
     early_access_enabled: bool = False

src/bubble_data_api_client/__init__.py

@@ -1,4 +1,4 @@
-from bubble_data_api_client.client.orm import BubbleBaseModel
+from bubble_data_api_client.client.orm import BubbleModel
 from bubble_data_api_client.client.raw_client import RawClient
 from bubble_data_api_client.config import (
     BubbleConfig,
@@ -24,7 +24,7 @@
     "configure",
     "set_config_provider",
     # client classes
-    "BubbleBaseModel",
+    "BubbleModel",
     "RawClient",
     # query building
     "Constraint",

src/bubble_data_api_client/client/orm.py

@@ -1,5 +1,6 @@
 import http
 import typing
+from datetime import datetime
 
 import httpx
 from pydantic import BaseModel as PydanticBaseModel
@@ -15,10 +16,31 @@ def _get_client() -> RawClient:
     return RawClient()
 
 
-class BubbleBaseModel(PydanticBaseModel):
+class BubbleModel(PydanticBaseModel):
+    """Base class for Bubble data types with built-in fields and ORM operations."""
+
     _typename: typing.ClassVar[str]
 
-    uid: str = Field(..., alias=BubbleField.ID)
+    uid: str = Field(
+        ...,
+        alias=BubbleField.ID,
+        description="Unique ID in format '{timestamp}x{random}' that identifies this record.",
+    )
+    created_date: datetime | None = Field(
+        default=None,
+        alias=BubbleField.CREATED_DATE,
+        description="Creation date of this record. Never changes.",
+    )
+    modified_date: datetime | None = Field(
+        default=None,
+        alias=BubbleField.MODIFIED_DATE,
+        description="Automatically updated when any changes are made to this record.",
+    )
+    slug: str | None = Field(
+        default=None,
+        alias=BubbleField.SLUG,
+        description="User-friendly and SEO-optimized URL for this record.",
+    )
 
     def __init_subclass__(cls, *, typename: str, **kwargs: typing.Any) -> None:
         super().__init_subclass__(**kwargs)
@@ -72,7 +94,11 @@ async def get_many(cls, uids: list[str]) -> dict[str, typing.Self]:
 
     async def save(self) -> None:
         async with _get_client() as client:
-            data = self.model_dump(exclude={"uid"}, by_alias=True)
+            # exclude uid and server-managed fields
+            data = self.model_dump(
+                exclude={"uid", "created_date", "modified_date", "slug"},
+                by_alias=True,
+            )
             response = await client.update(self._typename, self.uid, data)
             response.raise_for_status()
 

src/bubble_data_api_client/models.py

@@ -1,11 +1,11 @@
 import pytest
 
-from bubble_data_api_client.client.orm import BubbleBaseModel
+from bubble_data_api_client.client.orm import BubbleModel
 from bubble_data_api_client.constraints import ConstraintType, constraint
 from bubble_data_api_client.types import BubbleField
 
 
-class IntegrationTestModel(BubbleBaseModel, typename="IntegrationTest"):
+class IntegrationTestModel(BubbleModel, typename="IntegrationTest"):
     text: str
 
 

src/tests/integration/test_orm.py

@@ -5,14 +5,14 @@
 import respx
 from pydantic import Field
 
-from bubble_data_api_client.client.orm import BubbleBaseModel
+from bubble_data_api_client.client.orm import BubbleModel
 from bubble_data_api_client.exceptions import UnknownFieldError
 
 
 def test_model_instantiation():
     """Tests that the Pydantic model can be instantiated."""
 
-    class User(BubbleBaseModel, typename="user"):
+    class User(BubbleModel, typename="user"):
         name: str
 
     # instantiate the model, no client is needed
@@ -26,7 +26,7 @@ class User(BubbleBaseModel, typename="user"):
 async def test_save_uses_field_aliases(configured_client: None) -> None:
     """Verify save() sends Bubble aliases, not Python field names."""
 
-    class Order(BubbleBaseModel, typename="order"):
+    class Order(BubbleModel, typename="order"):
         company: str = Field(alias="Buying company")
 
     order = Order(**{"Buying company": "Acme Corp", "_id": "abc123"})
@@ -44,7 +44,7 @@ class Order(BubbleBaseModel, typename="order"):
 async def test_update_single_field(configured_client: None) -> None:
     """Verify update() sends only the specified field."""
 
-    class User(BubbleBaseModel, typename="user"):
+    class User(BubbleModel, typename="user"):
         name: str
         email: str
 
@@ -61,7 +61,7 @@ class User(BubbleBaseModel, typename="user"):
 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"):
+    class Order(BubbleModel, typename="order"):
         company: str = Field(alias="Buying company")
         status: str
 
@@ -77,7 +77,7 @@ class Order(BubbleBaseModel, typename="order"):
 async def test_update_raises_for_unknown_field() -> None:
     """Verify update() raises UnknownFieldError for fields not in the model."""
 
-    class User(BubbleBaseModel, typename="user"):
+    class User(BubbleModel, typename="user"):
         name: str
 
     with pytest.raises(UnknownFieldError, match="unknown field: nonexistent"):
@@ -88,7 +88,7 @@ class User(BubbleBaseModel, typename="user"):
 async def test_create_translates_field_aliases(configured_client: None) -> None:
     """Verify create() translates Python field names to Bubble aliases."""
 
-    class Order(BubbleBaseModel, typename="order"):
+    class Order(BubbleModel, typename="order"):
         company: str = Field(alias="Buying company")
         status: str
 
@@ -109,7 +109,7 @@ class Order(BubbleBaseModel, typename="order"):
 async def test_create_raises_for_unknown_field() -> None:
     """Verify create() raises UnknownFieldError for fields not in the model."""
 
-    class User(BubbleBaseModel, typename="user"):
+    class User(BubbleModel, typename="user"):
         name: str
 
     with pytest.raises(UnknownFieldError, match="unknown field: nonexistent"):
@@ -121,7 +121,7 @@ async def test_create_or_update_translates_match_aliases(configured_client: None
     """Verify create_or_update() translates match field names to Bubble aliases."""
     from bubble_data_api_client.types import OnMultiple
 
-    class Order(BubbleBaseModel, typename="order"):
+    class Order(BubbleModel, typename="order"):
         external_id: str = Field(alias="External ID")
         company: str = Field(alias="Buying company")
 
@@ -156,7 +156,7 @@ async def test_create_or_update_translates_data_aliases(configured_client: None)
     """Verify create_or_update() translates data field names to Bubble aliases."""
     from bubble_data_api_client.types import OnMultiple
 
-    class Order(BubbleBaseModel, typename="order"):
+    class Order(BubbleModel, typename="order"):
         external_id: str = Field(alias="External ID")
         company: str = Field(alias="Buying company")
 
@@ -185,7 +185,7 @@ async def test_create_or_update_raises_for_unknown_match_field() -> None:
     """Verify create_or_update() raises UnknownFieldError for unknown match fields."""
     from bubble_data_api_client.types import OnMultiple
 
-    class User(BubbleBaseModel, typename="user"):
+    class User(BubbleModel, typename="user"):
         name: str
 
     with pytest.raises(UnknownFieldError, match="unknown field: nonexistent"):
@@ -200,7 +200,7 @@ async def test_create_or_update_raises_for_unknown_data_field() -> None:
     """Verify create_or_update() raises UnknownFieldError for unknown data fields."""
     from bubble_data_api_client.types import OnMultiple
 
-    class User(BubbleBaseModel, typename="user"):
+    class User(BubbleModel, typename="user"):
         name: str
 
     with pytest.raises(UnknownFieldError, match="unknown field: nonexistent"):