Python SDK

The warmhub package provides synchronous and asynchronous Python clients for reading, writing, and navigating WarmHub repositories. It supports Python 3.10 and later.

pip install warmhub

Add the optional RE2 implementation when your application validates shape pattern constraints locally:

pip install "warmhub[re2]"

Choose a client

Use WarmHubClient in ordinary synchronous programs:

from warmhub import WarmHubClient

with WarmHubClient.from_env() as client:
    sensors = client.repository("acme/sensors")
    page = sensors.things.head(shape="Reading", limit=5)

Use AsyncWarmHubClient inside an async application:

from warmhub import AsyncWarmHubClient

async with AsyncWarmHubClient.from_env() as client:
    sensors = client.repository("acme/sensors")
    page = await sensors.things.head(shape="Reading", limit=5)

from_env() reads WH_TOKEN and WARMHUB_API_URL. The ordinary constructors do not read credentials from the environment; pass access_token= when explicit configuration is preferable.

Navigate the API

• Python SDK quickstart covers one read and one write.
• Python SDK reference lists every export in the package’s public warmhub.__all__ contract.
• Client thing methods take an organization and repository explicitly.
• Repository-bound thing methods omit those identifiers after client.repository("org/repo") binds them.

Sync and async namespace pages show both signatures together so that porting a call between execution models does not require comparing separate references.

Two data rules

Payload keys inside data are never renamed. If a stored field is called probeId, a typed Python payload must also call it probeId.

Optional parameters use UNSET for omission. Passing None is different: it serializes JSON null and can mean “set this field to null.”