Things SDK

Reusable Python SDK for Things Cloud sync.

Looking for the HTTP service instead of the Python library? See the root README.md for things-api.

Changelog — For a detailed history of changes, see CHANGELOG.md.

When should I use this?

Use things-sdk when you want to build Python-native tooling on top of Things Cloud, such as:

• CLI tools
• automation scripts
• background workers
• MCP servers
• custom internal integrations

If you want a ready-made HTTP/HTTPS service instead, use things-api from the repository root.

Installation

pip install things-sdk

Quick Start

import asyncio
from things_sdk import (
    ThingsClient,
    TaskService,
    DefaultSyncConfig,
    configure_sync,
    create_engine_and_session,
    init_db,
    pull_sync,
    push_sync,
)

async def main():
    # 1. Database setup
    engine, session_factory = create_engine_and_session(
        "sqlite+aiosqlite:///data/things.db"
    )
    await init_db(engine)

    # 2. Configure sync engine (use built-in defaults or pass your own config)
    configure_sync(DefaultSyncConfig())

    # 3. Sync from Things Cloud
    client = ThingsClient(email="you@example.com", password="your-password")
    async with session_factory() as session:
        result = await pull_sync(client, session)
        print(f"Pulled: {result}")
    await client.close()

    # 4. Query tasks
    svc = TaskService()
    async with session_factory() as session:
        tasks = await svc.list_tasks(session)
        for t in tasks:
            print(f"  - {t['title']} ({t['status']})")

    await engine.dispose()


asyncio.run(main())

What's included

Examples

See the examples/sdk/ directory for runnable examples:

All examples use the public things_sdk API:

THINGS_EMAIL=you@example.com THINGS_PASSWORD=secret uv run examples/sdk/list_tasks.py

Smoke-tested release artifacts

Releases validate that the SDK is not just built, but actually installable and usable:

• build wheel + sdist
• install wheel into a clean virtualenv
• import things_sdk
• create a SQLAlchemy engine/session factory
• after publish, install things-sdk==<version> from PyPI and repeat the basic checks

That means a published things-sdk release has already passed both a build-time smoke test and a post-publish verification in CI.