Metadata-Version: 2.4
Name: things-sdk
Version: 0.3.1
Summary: Reusable Python SDK for Things Cloud sync — domain models, cloud client, sync engine, and task operations
Project-URL: Homepage, https://github.com/nkootstra/things/tree/main/packages/things-sdk
Project-URL: Repository, https://github.com/nkootstra/things
Project-URL: Issues, https://github.com/nkootstra/things/issues
Project-URL: Changelog, https://github.com/nkootstra/things/blob/main/CHANGELOG.md
Author-email: Niels Kootstra <niels.kootstra@pm.me>
License: Apache-2.0
Keywords: productivity,sdk,sync,things,things3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.21
Requires-Dist: httpx>=0.28
Requires-Dist: pydantic>=2.0
Requires-Dist: sqlalchemy[asyncio]>=2.0
Description-Content-Type: text/markdown

# Things SDK

[![things-sdk on PyPI](https://img.shields.io/pypi/v/things-sdk?label=things-sdk)](https://pypi.org/project/things-sdk/)
[![CI](https://github.com/nkootstra/things/actions/workflows/ci.yml/badge.svg)](https://github.com/nkootstra/things/actions/workflows/ci.yml)

Reusable Python SDK for Things Cloud sync.

> Looking for the HTTP service instead of the Python library? See the root [`README.md`](../../README.md) for `things-api`.

> **Changelog** — For a detailed history of changes, see [`CHANGELOG.md`](../../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

```bash
pip install things-sdk
```

## Quick Start

```python
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

| 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 |

## Examples

See the [`examples/sdk/`](../../examples/sdk/) directory for runnable examples:

| Example | Description |
|---|---|
| [`list_tasks.py`](../../examples/sdk/list_tasks.py) | Sync from Things Cloud, then print all pending tasks |
| [`sync_once.py`](../../examples/sdk/sync_once.py) | Run a single pull + push sync cycle |
| [`create_task.py`](../../examples/sdk/create_task.py) | Create a task locally and push it to Things Cloud |

All examples use the public `things_sdk` API:

```sh
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.
