trellio-client 1.6.0

Async Trello API client for Python

Trellio - Async Trello API Client for Python

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

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

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

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:

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:

make
make deps
make test-pytest
make test-behave

Architecture Decisions

ADR	Title	Status
001	Custom Mock Server and Validation Strategy	Accepted
002	Mock Strategy: Custom Python vs. MockServer	Accepted
003	Failure Path Enumeration	Accepted

License

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