things-sdk 0.2.0

Reusable Python SDK for Things Cloud sync — domain models, cloud client, sync engine, and task operations

Things SDK

Reusable Python SDK for Things Cloud sync.

Installation

pip install things-sdk

Quick Start

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


class MySyncConfig:
    sync_retry_attempts = 3
    sync_retry_base_seconds = 0.25
    sync_circuit_breaker_failures = 3
    sync_circuit_breaker_cooldown_seconds = 60.0


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
    configure_sync(MySyncConfig())

    # 3. Sync from Things Cloud
    client = ThingsClient(email="[e-mail]", 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

Module	Description
ThingsClient	Async HTTP client for Things Cloud
pull_sync / push_sync	Sync engine with retry + circuit breaker
TaskService	CRUD operations for tasks, areas, tags
create_engine_and_session	SQLAlchemy async engine factory
Domain models	Task, Area, Tag, ChecklistItem, SyncState
CloudClientProtocol	Protocol for custom client implementations
SyncConfig	Protocol for sync configuration
EntityHandler	Strategy pattern for extending sync to new entity types