Metadata-Version: 2.4
Name: trellio-client
Version: 1.7.0
Summary: Async Trello API client for Python
Author: scaratec
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/scaratec/trellio
Project-URL: Repository, https://github.com/scaratec/trellio
Project-URL: Issues, https://github.com/scaratec/trellio/issues
Keywords: trello,api,async,httpx,pydantic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Framework :: AsyncIO
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: behave>=1.2.6; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Dynamic: license-file

# Trellio - Async Trello API Client for Python

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

**Trellio** is a production-ready, asynchronous Python client for the Trello API, built on `httpx` and `pydantic`. Designed for use in long-running services like MCP servers, it provides retry with backoff, request timeouts, structured logging, and full CRUD coverage across 10 Trello resource types.

## Features

### Infrastructure
- **Async I/O** -- built on `httpx.AsyncClient`, non-blocking
- **Retry with exponential backoff** -- automatic retry on 429/5xx, respects `Retry-After` header, configurable `max_retries`, `initial_delay`, `backoff_factor`
- **Request timeout** -- configurable per-client, raises `TrelloAPIError` on timeout
- **Pagination** -- `list_boards(limit, since)` for single pages, `list_all_boards(page_size)` async generator for auto-pagination
- **Structured logging** -- `trellio` logger with DEBUG (every request), WARNING (retries), ERROR (failures)
- **Typed exceptions** -- `TrelloAPIError(status_code, message)` for all API errors
- **Pydantic models** -- type-safe response objects with alias support for Trello's camelCase API

### Resources (46 client methods)

| Resource    | Methods |
|-------------|---------|
| Auth        | `get_me` |
| Boards      | `list_boards`, `list_all_boards`, `create_board`, `get_board`, `update_board`, `delete_board` |
| Lists       | `list_lists`, `create_list`, `get_list`, `update_list` |
| Cards       | `list_cards`, `create_card`, `get_card`, `update_card`, `delete_card`, `add_label_to_card`, `remove_label_from_card` |
| Labels      | `list_board_labels`, `create_label`, `update_label`, `delete_label` |
| Checklists  | `list_card_checklists`, `create_checklist`, `get_checklist`, `delete_checklist`, `create_check_item`, `update_check_item`, `delete_check_item` |
| Comments    | `add_comment`, `list_comments`, `update_comment`, `delete_comment` |
| Members     | `list_board_members`, `get_member` |
| Attachments | `list_attachments`, `create_attachment`, `get_attachment`, `upload_attachment`, `download_attachment`, `delete_attachment` |
| Webhooks    | `create_webhook`, `list_webhooks`, `get_webhook`, `update_webhook`, `delete_webhook` |
| Search      | `search` |

### Models

`TrelloMember`, `TrelloBoard`, `TrelloList`, `TrelloCard`, `TrelloLabel`, `TrelloChecklist`, `TrelloCheckItem`, `TrelloComment`, `TrelloAttachment`, `TrelloWebhook`, `TrelloSearchResult`

## Quick Start

```python
import asyncio
from trellio import TrellioClient

async def main():
    async with TrellioClient(
        api_key="your_key",
        token="your_token",
        max_retries=3,
        timeout=30.0,
    ) as client:
        boards = await client.list_boards()
        for board in boards:
            print(board.name)

        results = await client.search("project")
        for card in results.cards:
            print(card.name)

asyncio.run(main())
```

## MCP Server Usage

```python
from trellio import TrellioClient, TrelloAPIError

client = TrellioClient(
    api_key=os.environ["TRELLO_API_KEY"],
    token=os.environ["TRELLO_TOKEN"],
    max_retries=3,
    initial_delay=1.0,
    timeout=30.0,
)

# Use in MCP tool handlers:
async def handle_create_card(list_id: str, name: str):
    try:
        card = await client.create_card(list_id, name)
        return {"id": card.id, "name": card.name}
    except TrelloAPIError as e:
        return {"error": e.message, "status": e.status_code}
```

## Philosophy: BDD & Single Source of Truth

This project follows strict **Behavior-Driven Development (BDD)** where Gherkin feature files are the **Single Source of Truth** for business logic. All implementation is derivative of the specifications.

## Test Coverage

The BDD suite covers **19 features, 144 scenarios, 1048 steps**:

| Feature             | Scenarios |
|---------------------|-----------|
| Authentication      | 6         |
| Boards              | 11        |
| Cards               | 13        |
| Lists               | 10        |
| Labels              | 9         |
| Checklists          | 13        |
| Comments            | 9         |
| Members             | 4         |
| Attachments         | 10        |
| Upload Attachment   | 6         |
| Download Attachment | 5         |
| Webhooks            | 13        |
| Retry               | 7         |
| Pagination          | 4         |
| Connection          | 2         |
| Timeout             | 2         |
| Search              | 4         |
| Logging             | 3         |
| Large Payload       | 4         |
| **Total**           | **144**   |

## Development Setup

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt

# Run BDD suite
PYTHONPATH=src python -m behave

# Run mock validation
PYTHONPATH=src pytest tests/validation/
```

## Quick Start with Make

For a fresh checkout, the simplest path is:

```bash
make test
```

This will:
- create `.venv` if it does not exist
- install dependencies if they are not available yet
- run the validation tests with `pytest`
- run the BDD suite with `behave`

You can also use:

```bash
make
make deps
make test-pytest
make test-behave
```

## Architecture Decisions

| ADR | Title | Status |
|-----|-------|--------|
| [001](docs/adr/001-custom-mock-server.md) | Custom Mock Server and Validation Strategy | Accepted |
| [002](docs/adr/002-mock-server-selection.md) | Mock Strategy: Custom Python vs. MockServer | Accepted |
| [003](docs/adr/003-failure-path-enumeration.md) | Failure Path Enumeration | Accepted |

## License

This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
