add Bubble UID validation types and utilities

Author: purificant

src/bubble_data_api_client/__init__.py

@@ -5,12 +5,27 @@
     set_config_provider,
 )
 from bubble_data_api_client.pool import client_scope, close_clients
+from bubble_data_api_client.types import (
+    BubbleUID,
+    OptionalBubbleUID,
+    OptionalBubbleUIDs,
+)
+from bubble_data_api_client.validation import filter_bubble_uids, is_bubble_uid
 
 __all__ = [
+    # config
     "BubbleConfig",
     "ConfigProvider",
     "configure",
     "set_config_provider",
+    # client lifecycle
     "client_scope",
     "close_clients",
+    # types
+    "BubbleUID",
+    "OptionalBubbleUID",
+    "OptionalBubbleUIDs",
+    # validation
+    "filter_bubble_uids",
+    "is_bubble_uid",
 ]

src/bubble_data_api_client/exceptions.py

@@ -19,3 +19,11 @@ class BubbleNotFoundError(BubbleHttpError):
 
 class BubbleUnauthorizedError(BubbleHttpError):
     """Raised when the user is not authorized to access a resource."""
+
+
+class InvalidBubbleUIDError(ValueError):
+    """Raised when a string is not a valid Bubble UID."""
+
+    def __init__(self, value: str) -> None:
+        super().__init__(f"invalid Bubble UID format: {value}")
+        self.value = value

src/bubble_data_api_client/models.py

@@ -12,8 +12,7 @@ class BubbleThing(BaseModel):
     id: str = Field(
         ...,
         alias="_id",
-        description="The Unique ID is a 32-character alphanumeric string "
-        "that identifies a specific thing in the database.",
+        description="The Unique ID in format '{timestamp}x{random}' that identifies a specific thing in the database.",
     )
     created_date: datetime = Field(
         ...,

src/bubble_data_api_client/types.py

@@ -0,0 +1,46 @@
+"""Bubble platform types for use with Pydantic models."""
+
+from typing import Annotated, Any
+
+from pydantic import AfterValidator, BeforeValidator
+
+from bubble_data_api_client.exceptions import InvalidBubbleUIDError
+from bubble_data_api_client.validation import is_bubble_uid
+
+
+def _validate_bubble_uid(value: str) -> str:
+    """Validate that a string is a valid Bubble UID."""
+    if not is_bubble_uid(value):
+        raise InvalidBubbleUIDError(value)
+    return value
+
+
+BubbleUID = Annotated[str, AfterValidator(_validate_bubble_uid)]
+"""A string validated as a Bubble UID (format: digits + 'x' + digits)."""
+
+
+def _coerce_optional_bubble_uid(value: Any) -> str | None:
+    """Coerce to valid Bubble UID or None. Invalid values silently become None."""
+    if value is None or value == "":
+        return None
+    if not isinstance(value, str):
+        return None
+    if not is_bubble_uid(value):
+        return None
+    return value
+
+
+OptionalBubbleUID = Annotated[str | None, BeforeValidator(_coerce_optional_bubble_uid)]
+"""A Bubble UID that silently coerces invalid values (including empty string) to None."""
+
+
+def _coerce_optional_bubble_uids(value: object) -> list[str] | None:
+    """Coerce to list of valid Bubble UIDs or None. Empty/invalid becomes None."""
+    if not isinstance(value, list):
+        return None
+    result = [x for x in value if isinstance(x, str) and is_bubble_uid(x)]
+    return result or None
+
+
+OptionalBubbleUIDs = Annotated[list[str] | None, BeforeValidator(_coerce_optional_bubble_uids)]
+"""A list of Bubble UIDs that silently coerces invalid/empty to None."""

src/bubble_data_api_client/validation.py

@@ -0,0 +1,16 @@
+"""Validation utilities for Bubble platform data."""
+
+import re
+from collections.abc import Iterable
+
+_BUBBLE_UID_PATTERN: re.Pattern[str] = re.compile(r"^[0-9]+x[0-9]+$")
+
+
+def is_bubble_uid(value: str) -> bool:
+    """Check if a string matches the Bubble UID format (e.g., '1767090310181x452059685440531200')."""
+    return _BUBBLE_UID_PATTERN.fullmatch(value) is not None
+
+
+def filter_bubble_uids(values: Iterable[str]) -> list[str]:
+    """Return only valid Bubble UIDs from an iterable, filtering out invalid ones."""
+    return [v for v in values if is_bubble_uid(v)]