add google-style docstrings for better IDE hints and API discoverability

Author: purificant

pyproject.toml

@@ -38,17 +38,20 @@ target-version = "py313"
 line-length = 120
 
 [tool.ruff.lint]
-extend-select = ["E", "F", "I", "FAST", "ASYNC", "TRY", "PERF", "UP", "FURB", "A", "B", "S", "C4", "PIE", "RUF", "TC"]
+extend-select = ["E", "F", "I", "FAST", "ASYNC", "TRY", "PERF", "UP", "FURB", "A", "B", "S", "C4", "PIE", "RUF", "TC", "D"]
 ignore = ["RUF022"]
 
 [tool.ruff.lint.per-file-ignores]
-"src/tests/**/*.py" = ["S101"]
-"*/test_*.py" = ["S101"]
+"src/tests/**/*.py" = ["S101", "D"]
+"*/test_*.py" = ["S101", "D"]
 
 [tool.ruff.lint.flake8-type-checking]
 runtime-evaluated-base-classes = ["pydantic.BaseModel"]
 runtime-evaluated-decorators = ["pydantic.validate_call"]
 
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 asyncio_mode = "auto"

src/bubble_data_api_client/__init__.py

@@ -1,3 +1,15 @@
+"""Python client for Bubble.io Data API with ORM-style models and async support.
+
+This library provides two ways to interact with Bubble's Data API:
+- BubbleModel: ORM-style base class for defining typed data models with CRUD operations
+- RawClient: Low-level async client for direct API access
+
+Quick start:
+    1. Configure credentials: configure(data_api_root_url="...", api_key="...")
+    2. Define a model: class User(BubbleModel, typename="user"): name: str
+    3. Use CRUD operations: await User.create(name="Alice")
+"""
+
 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 (

src/bubble_data_api_client/client/__init__.py

@@ -0,0 +1 @@
+"""Client layer providing ORM models and raw API access."""

src/bubble_data_api_client/client/client.py

@@ -1,3 +1,5 @@
+"""High-level client with data validation and transformation."""
+
 from pydantic import BaseModel, Field
 
 from bubble_data_api_client.client.raw_client import RawClient
@@ -19,27 +21,31 @@ class BubbleDataApiResponseBody(BaseModel):
 
 
 class CreateThingSuccessResponse(BaseModel):
+    """Response body returned when a thing is successfully created."""
+
     status: str
     id: str
 
 
 class Bubble404ResponseBody(BaseModel):
+    """Body content of a Bubble 404 not found response."""
+
     status: str
     message: str
 
 
 class Bubble404Response(BaseModel):
+    """Structured representation of a Bubble 404 response."""
+
     status_code: int = Field(404, alias="statusCode")
     body: Bubble404ResponseBody
 
 
 class Client:
-    """
-    Client layer focuses on providing a convenient interface.
-    - CRUD operations
-    - data validation
-    - data transformation
-    - error handling
+    """High-level Bubble API client with validation and error handling.
+
+    Provides CRUD operations with data validation and transformation.
+    Consider using BubbleModel for ORM-style access instead.
     """
 
     _data_api_root_url: str
@@ -50,6 +56,12 @@ def __init__(
         self,
         data_api_root_url: str,
         api_key: str,
-    ):
+    ) -> None:
+        """Initialize client with Bubble API credentials.
+
+        Args:
+            data_api_root_url: Base URL for the Bubble Data API.
+            api_key: API key for authentication.
+        """
         self._data_api_root_url = data_api_root_url
         self._api_key = api_key

src/bubble_data_api_client/client/orm.py

@@ -1,3 +1,19 @@
+"""ORM-style base class for Bubble data types.
+
+Define models by subclassing BubbleModel with a typename parameter:
+
+    class User(BubbleModel, typename="user"):
+        name: str
+        email: str | None = None
+
+Then use async CRUD operations:
+    user = await User.create(name="Alice")
+    user = await User.get("1234x5678")
+    users = await User.find(constraints=[constraint("name", ConstraintType.EQUALS, "Alice")])
+    await user.save()
+    await user.delete()
+"""
+
 import http
 import typing
 from collections.abc import AsyncIterator
@@ -44,6 +60,7 @@ class BubbleModel(PydanticBaseModel):
     )
 
     def __init_subclass__(cls, *, typename: str, **kwargs: typing.Any) -> None:
+        """Register the Bubble type name for this model subclass."""
         super().__init_subclass__(**kwargs)
         cls._typename = typename
 
@@ -63,6 +80,14 @@ def _resolve_aliases(cls, data: dict[str, typing.Any]) -> dict[str, typing.Any]:
 
     @classmethod
     async def create(cls, **data: typing.Any) -> typing.Self:
+        """Create a new thing in Bubble and return a model instance.
+
+        Args:
+            **data: Field values using Python field names (not Bubble aliases).
+
+        Returns:
+            A new model instance with the assigned Bubble UID.
+        """
         aliased_data = cls._resolve_aliases(data)
         async with _get_client() as client:
             response = await client.create(cls._typename, aliased_data)
@@ -94,6 +119,11 @@ async def get_many(cls, uids: list[str]) -> dict[str, typing.Self]:
         return {item.uid: item for item in items}
 
     async def save(self) -> None:
+        """Persist all field changes to Bubble.
+
+        Saves all model fields except uid and server-managed fields
+        (created_date, modified_date, slug).
+        """
         async with _get_client() as client:
             # exclude uid and server-managed fields
             data = self.model_dump(
@@ -112,6 +142,7 @@ async def update(cls, uid: str, **data: typing.Any) -> None:
             response.raise_for_status()
 
     async def delete(self) -> None:
+        """Delete this thing from Bubble."""
         async with _get_client() as client:
             response = await client.delete(self._typename, self.uid)
             response.raise_for_status()
@@ -128,6 +159,20 @@ async def find(
         exclude_remaining: bool | None = None,
         additional_sort_fields: list[AdditionalSortField] | None = None,
     ) -> list[typing.Self]:
+        """Search for things matching the given constraints.
+
+        Args:
+            constraints: Filter conditions (use constraint() helper to build).
+            cursor: Pagination offset (0-indexed).
+            limit: Maximum results to return (default 100, max varies by plan).
+            sort_field: Field name to sort by.
+            descending: Sort in descending order if True.
+            exclude_remaining: Skip counting remaining results for performance.
+            additional_sort_fields: Secondary sort fields after the primary.
+
+        Returns:
+            List of matching model instances.
+        """
         async with _get_client() as client:
             response = await client.find(
                 cls._typename,

src/bubble_data_api_client/client/raw_client.py

@@ -1,3 +1,9 @@
+"""Low-level async client for direct Bubble Data API access.
+
+Use RawClient when you need direct control over API calls without ORM overhead.
+For most use cases, prefer BubbleModel which provides a higher-level interface.
+"""
+
 import asyncio
 import http
 import json
@@ -16,13 +22,14 @@
 # in addition to 'sort_field' and 'descending', it is possible to have
 # multiple additional sort fields
 class AdditionalSortField(typing.TypedDict):
+    """Secondary sort field for multi-field sorting in find queries."""
+
     sort_field: str
     descending: bool
 
 
 class RawClient:
-    """
-    Raw Client layer focuses on bubble.io API endpoints.
+    """Raw Client layer focuses on bubble.io API endpoints.
 
     https://manual.bubble.io/core-resources/api/the-bubble-api/the-data-api/data-api-requests
     https://www.postman.com/bubbleapi/bubble/request/jigyk5v/
@@ -31,9 +38,10 @@ class RawClient:
     _transport: Transport
 
     def __init__(self) -> None:
-        pass
+        """Initialize the client (must be used as async context manager)."""
 
     async def __aenter__(self) -> typing.Self:
+        """Enter async context and initialize the HTTP transport."""
         self._transport = Transport()
         await self._transport.__aenter__()
         return self
@@ -44,27 +52,34 @@ async def __aexit__(
         exc_val: BaseException | None,
         exc_tb: types.TracebackType | None,
     ) -> None:
+        """Exit async context and close the HTTP transport."""
         await self._transport.__aexit__(exc_type, exc_val, exc_tb)
 
     async def retrieve(self, typename: str, uid: str) -> httpx.Response:
+        """Fetch a single thing by its unique ID."""
         return await self._transport.get(f"/{typename}/{uid}")
 
     async def create(self, typename: str, data: typing.Any) -> httpx.Response:
+        """Create a new thing with the given data."""
         return await self._transport.post(url=f"/{typename}", json=data)
 
     async def bulk_create(self, typename: str, data: list[typing.Any]) -> httpx.Response:
+        """Create multiple things in a single request using newline-delimited JSON."""
         return await self._transport.post_text(
             url=f"/{typename}/bulk",
             content="\n".join(json.dumps(item) for item in data),
         )
 
     async def delete(self, typename: str, uid: str) -> httpx.Response:
+        """Delete a thing by its unique ID."""
         return await self._transport.delete(f"/{typename}/{uid}")
 
     async def update(self, typename: str, uid: str, data: typing.Any) -> httpx.Response:
+        """Partially update a thing with PATCH, only modifying specified fields."""
         return await self._transport.patch(f"/{typename}/{uid}", json=data)
 
     async def replace(self, typename: str, uid: str, data: typing.Any) -> httpx.Response:
+        """Fully replace a thing's data with PUT, clearing unspecified fields."""
         return await self._transport.put(f"/{typename}/{uid}", json=data)
 
     # https://manual.bubble.io/core-resources/api/the-bubble-api/the-data-api/data-api-requests#get-a-list-of-things
@@ -80,6 +95,7 @@ async def find(
         exclude_remaining: bool | None = None,
         additional_sort_fields: list[AdditionalSortField] | None = None,
     ) -> httpx.Response:
+        """Search for things matching constraints with pagination and sorting."""
         params: dict[str, str] = {}
 
         if constraints is not None:

src/bubble_data_api_client/config.py

@@ -1,3 +1,14 @@
+"""Configuration management for Bubble Data API credentials and settings.
+
+Configure the client before making API calls:
+
+    # Option 1: Static configuration
+    configure(data_api_root_url="https://app.bubble.io/api/1.1/obj", api_key="...")
+
+    # Option 2: Dynamic configuration (e.g., for multi-tenant apps)
+    set_config_provider(lambda: get_config_for_current_user())
+"""
+
 from collections.abc import Callable
 from typing import NotRequired, TypedDict, TypeIs
 
@@ -10,6 +21,7 @@ class _NotSet:
     __slots__ = ()
 
     def __repr__(self) -> str:
+        """Return string representation for debugging."""
         return "NOT_SET"
 
 

src/bubble_data_api_client/constraints.py

@@ -1,15 +1,28 @@
+"""Query constraint types for filtering Bubble Data API results.
+
+Use the constraint() helper to build constraints for find() queries:
+
+    constraints = [
+        constraint("name", ConstraintType.EQUALS, "Alice"),
+        constraint("age", ConstraintType.GREATER_THAN, 18),
+    ]
+    users = await User.find(constraints=constraints)
+"""
+
 import typing
 from enum import StrEnum
 
 
-# all constraints are of the form:
 class BaseConstraint(typing.TypedDict):
+    """Base structure for all constraint types."""
+
     key: str
     constraint_type: str
 
 
-# some constraints have a value, some do not
 class Constraint(BaseConstraint, total=False):
+    """A query constraint with optional value for filtering results."""
+
     value: str
 
 

src/bubble_data_api_client/exceptions.py

@@ -1,3 +1,6 @@
+"""Exception types for Bubble Data API errors."""
+
+
 class BubbleError(Exception):
     """Base class for all exceptions raised by the library."""
 
@@ -6,6 +9,7 @@ class ConfigurationError(BubbleError):
     """Raised when required configuration is missing."""
 
     def __init__(self, key: str) -> None:
+        """Create error for missing configuration key."""
         super().__init__(f"{key} is not configured")
 
 
@@ -21,6 +25,7 @@ class InvalidBubbleUIDError(ValueError):
     """Raised when a string is not a valid Bubble UID."""
 
     def __init__(self, value: str) -> None:
+        """Create error for invalid UID format."""
         super().__init__(f"invalid Bubble UID format: {value}")
         self.value = value
 
@@ -29,6 +34,7 @@ class UnknownFieldError(BubbleError):
     """Raised when an unknown field name is passed to update()."""
 
     def __init__(self, field_name: str) -> None:
+        """Create error for unknown field name."""
         super().__init__(f"unknown field: {field_name}")
         self.field_name = field_name
 
@@ -37,6 +43,7 @@ class MultipleMatchesError(BubbleError):
     """Raised when create_or_update finds multiple matches with on_multiple='error'."""
 
     def __init__(self, typename: str, count: int, match: dict) -> None:
+        """Create error for unexpected multiple matches."""
         super().__init__(f"expected 0 or 1 matches for '{typename}', found {count} with match={match}")
         self.typename = typename
         self.count = count
@@ -47,6 +54,7 @@ class InvalidOnMultipleError(BubbleError):
     """Raised when an invalid on_multiple strategy is provided."""
 
     def __init__(self, value: str) -> None:
+        """Create error for invalid on_multiple strategy value."""
         super().__init__(f"invalid on_multiple strategy: '{value}'")
         self.value = value
 
@@ -60,6 +68,7 @@ def __init__(
         succeeded: list[str],
         failed: list[tuple[str, BaseException]],
     ) -> None:
+        """Create error with lists of succeeded and failed UIDs."""
         failed_count = len(failed)
         total = len(succeeded) + failed_count
         super().__init__(f"{operation}: {failed_count}/{total} operations failed")

src/bubble_data_api_client/settings.py

@@ -1,3 +1,5 @@
+"""Environment variable settings for Bubble API credentials."""
+
 import os
 
 BUBBLE_DATA_API_ROOT_URL = os.getenv("BUBBLE_DATA_API_ROOT_URL")