Typing & Pydantic

By default, sub-client methods return plain dict payloads. For type safety, the SDK ships an opt-in Pydantic v2 integration under openapp_sdk.contrib.pydantic and a set of generated models under openapp_sdk.models.

Install the extra

pip install "openapp-sdk[pydantic]"

Parse responses

from pydantic import BaseModel
from openapp_sdk import Client
from openapp_sdk.contrib.pydantic import parse_as

class Org(BaseModel):
    id: str
    name: str
    created_at: str

client = Client.connect(api_key="...")
org = parse_as(Org, client.orgs.get("org_123"))
# org is a validated Pydantic model.

Serialize requests

dump converts a Pydantic model to the JSON-serializable dict the SDK expects:

from openapp_sdk.contrib.pydantic import dump

class OrgCreate(BaseModel):
    name: str
    address: str | None = None

payload = OrgCreate(name="Acme", address="1 Main St.")
client.orgs.create(body=dump(payload))

Generated models

The classes under openapp_sdk.models are Pydantic v2 BaseModel subclasses that mirror the OpenAPI schemas — same field names, same types. They ship with every SDK release, so you can trust them to be in sync with the backend contract.

from openapp_sdk.models import Org

for raw in client.orgs.list()["items"]:
    org = Org.model_validate(raw)
    print(org.id, org.name)

py.typed

The SDK ships py.typed, so mypy / pyright / Pylance will pick up the typed surface out of the box.

Type-checker configuration

If you rely on the Pydantic v2 integration, make sure your type checker loads Pydantic’s mypy plugin:

pyproject.toml

[tool.mypy]
plugins = ["pydantic.mypy"]

Opting out

The Pydantic integration is strictly opt-in. The core SDK has no runtime dependency on Pydantic; you only pay for it if you install the extra or import from openapp_sdk.contrib.pydantic / openapp_sdk.models.