---
title: "Python SDK"
description: "Official Python SDK for TraceRTM - full API coverage with sync and async clients"
---

# Python SDK

The official Python SDK for TraceRTM provides a fully typed, Pythonic interface to all TraceRTM APIs. It supports both synchronous and asynchronous operations, automatic pagination, retry logic, and comprehensive error handling.

## Installation

```bash
pip install tracertm
```

Or with Poetry:

```bash
poetry add tracertm
```

## Quick Start

```python
from tracertm import TraceRTMClient

# Initialize the client
client = TraceRTMClient(api_key="rtm_live_sk_...")

# List all projects
projects = client.projects.list()
for project in projects.data:
    print(f"{project.key}: {project.name}")

# Create an item
item = client.items.create(
    project_id="proj_abc123",
    type="requirement",
    title="User Authentication",
    description="Implement secure user authentication",
    priority="high"
)
print(f"Created: {item.key}")
```

---

## Features

### Complete API Coverage

The SDK provides access to all TraceRTM resources:

| Resource | Methods |
|----------|---------|
| `projects` | list, create, get, update, delete, archive |
| `items` | list, create, get, update, delete, transition, comments, attachments |
| `links` | list, create, get, delete, bulk_create |
| `workflows` | list, create, get, update, transitions |
| `reports` | coverage, impact, audit, export |
| `webhooks` | list, create, get, update, delete |
| `search` | query, facets |

### Type Safety

Full type hints with Pydantic models:

```python
from tracertm import TraceRTMClient
from tracertm.models import CreateItemInput, Item

client = TraceRTMClient(api_key="rtm_live_sk_...")

# Type-checked input
input_data = CreateItemInput(
    project_id="proj_abc123",
    type="requirement",
    title="User Authentication",
    priority="high"
)

# Type-checked response
item: Item = client.items.create(**input_data.model_dump())

# IDE auto-completion works
print(item.id)
print(item.title)
print(item.status)
```

### Sync and Async Clients

```python
# Synchronous client
from tracertm import TraceRTMClient

client = TraceRTMClient(api_key="rtm_live_sk_...")
projects = client.projects.list()

# Asynchronous client
from tracertm import AsyncTraceRTMClient
import asyncio

async def main():
    client = AsyncTraceRTMClient(api_key="rtm_live_sk_...")
    projects = await client.projects.list()

asyncio.run(main())
```

### Automatic Pagination

```python
# Iterate through all items (handles pagination automatically)
for item in client.items.iterate(project_id="proj_abc123"):
    print(item.title)

# Or fetch pages manually
page = client.items.list(project_id="proj_abc123", limit=50)
while page.has_next:
    for item in page.data:
        process(item)
    page = page.next_page()
```

### Built-in Retry Logic

```python
client = TraceRTMClient(
    api_key="rtm_live_sk_...",
    max_retries=3,
    retry_delay=1.0,
    retry_on=[429, 500, 502, 503, 504]
)
```

---

## Configuration

### Client Options

```python
from tracertm import TraceRTMClient

client = TraceRTMClient(
    # Authentication
    api_key="rtm_live_sk_...",        # Or set TRACERTM_API_KEY env var

    # Base URL (default: production)
    base_url="https://api.tracertm.dev/v1",

    # Timeouts (seconds)
    timeout=30,
    connect_timeout=10,

    # Retry configuration
    max_retries=3,
    retry_delay=1.0,

    # Debug mode
    debug=False
)
```

### Environment Variables

```bash
export TRACERTM_API_KEY="rtm_live_sk_..."
export TRACERTM_BASE_URL="https://api.tracertm.dev/v1"
export TRACERTM_TIMEOUT="30"
```

```python
# Client automatically reads from environment
client = TraceRTMClient()
```

---

## Resources

### Projects

```python
# List projects
projects = client.projects.list()

# Create project
project = client.projects.create(
    name="My Project",
    key="PROJ",
    description="Project description"
)

# Get project
project = client.projects.get("proj_abc123")

# Update project
project = client.projects.update(
    "proj_abc123",
    name="Updated Name"
)

# Delete project
client.projects.delete("proj_abc123")
```

### Items

```python
# List items with filters
items = client.items.list(
    project_id="proj_abc123",
    type="requirement",
    status="approved",
    limit=50
)

# Create item
item = client.items.create(
    project_id="proj_abc123",
    type="requirement",
    title="User Authentication",
    description="Implement secure login",
    priority="high",
    custom_fields={"story_points": 5}
)

# Get item
item = client.items.get("item_req_001")

# Update item
item = client.items.update(
    "item_req_001",
    title="Updated Title",
    priority="critical"
)

# Transition item status
item = client.items.transition(
    "item_req_001",
    transition="approve",
    comment="Approved by tech lead"
)

# Delete item
client.items.delete("item_req_001")
```

### Links

```python
# List links
links = client.links.list(project_id="proj_abc123")

# Create link
link = client.links.create(
    source_id="item_req_001",
    target_id="item_tc_001",
    link_type="verified_by"
)

# Bulk create links
links = client.links.bulk_create([
    {"source_id": "item_req_001", "target_id": "item_tc_001", "link_type": "verified_by"},
    {"source_id": "item_req_001", "target_id": "item_tc_002", "link_type": "verified_by"},
])

# Delete link
client.links.delete("link_abc123")
```

### Workflows

```python
# List workflows
workflows = client.workflows.list(project_id="proj_abc123")

# Get workflow with states and transitions
workflow = client.workflows.get("wf_abc123")

# Get available transitions for an item
transitions = client.items.available_transitions("item_req_001")
```

---

## Error Handling

```python
from tracertm import TraceRTMClient
from tracertm.exceptions import (
    TraceRTMError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    RateLimitError,
    ConflictError,
    ServerError
)

client = TraceRTMClient(api_key="rtm_live_sk_...")

try:
    item = client.items.get("item_nonexistent")

except NotFoundError as e:
    print(f"Item not found: {e.resource_id}")
    print(f"Request ID: {e.request_id}")

except ValidationError as e:
    print(f"Validation failed:")
    for error in e.errors:
        print(f"  - {error['field']}: {error['message']}")

except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")

except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")

except ServerError as e:
    print(f"Server error: {e.message}")
    print(f"Request ID for support: {e.request_id}")

except TraceRTMError as e:
    print(f"API error: {e.code} - {e.message}")
```

---

## Async Usage

```python
from tracertm import AsyncTraceRTMClient
import asyncio

async def main():
    client = AsyncTraceRTMClient(api_key="rtm_live_sk_...")

    # Single request
    projects = await client.projects.list()

    # Concurrent requests
    item1, item2, item3 = await asyncio.gather(
        client.items.get("item_1"),
        client.items.get("item_2"),
        client.items.get("item_3")
    )

    # Async iteration
    async for item in client.items.iterate(project_id="proj_abc123"):
        print(item.title)

asyncio.run(main())
```

---

## Requirements

- Python 3.9+
- Dependencies: `httpx`, `pydantic`

---

## Related Documentation

- [Installation](/docs/api-reference/sdks/python/installation) - Detailed installation guide
- [Quickstart](/docs/api-reference/sdks/python/quickstart) - Get started quickly
- [API Reference](/docs/api-reference/sdks/python/api-reference) - Complete method reference
- [Examples](/docs/api-reference/sdks/python/examples) - Code examples
- [Error Handling](/docs/api-reference/sdks/python/error-handling) - Error handling guide
