oblidog-client

Python client for the Oblidog integration API.

Use the handwritten OblidogClient facade in application code. The oblidog_client.generated namespace is OpenAPI-generated transport code and is an implementation detail, not the recommended SDK API.

Installation

pip install oblidog-client

Usage

Set OBLIDOG_BASE_URL to your server root and OBLIDOG_API_KEY through your secret store or environment. This example assumes an active category schema accepting meter_reading_kwh.

import datetime
import os

from oblidog_client import OblidogClient

with OblidogClient(
    base_url=os.environ["OBLIDOG_BASE_URL"],
    api_key=os.environ["OBLIDOG_API_KEY"],
) as client:
    with client.integrations.run() as run:
        client.category_data.create(
            observed_at=datetime.datetime.now(datetime.UTC),
            data={"meter_reading_kwh": 1234.5},
        )
        run.finish_success(changes_detected=True)

The integration API key selects its integration and category. Use client.integrations.run() around synchronization work: it reads context and starts a run before the block, then reports a sanitized failure if the block raises.

Documentation

The full documentation is published at oblidog.github.io/oblidog-client-python. It includes a quickstart, task-oriented guides, public API reference, and supported API boundary; it intentionally excludes generated endpoints and transport classes.

Start with configuration, then follow the obligation import, category observations, and lifecycle and failure handling guides.

Development

This project uses uv for dependency and environment management. The low-level client is generated from the Oblidog Ledger integration OpenAPI contract; generated code should not be edited manually.

Use Commitizen to create Conventional Commit messages interactively, or to validate one non-interactively:

uv run cz commit
uv run cz check -m "feat: add a new capability"

Run the same distribution verification used by CI locally:

./scripts/verify-package.sh

The command builds the wheel and source distribution, validates their metadata and contents, installs the wheel into a clean environment, and checks the installed public API. It does not publish any artifacts.

Release maintainers should follow the Trusted Publishing setup and release procedure.