daktela 1.0.0
Python SDK for Daktela V6 REST API
Requires Python: >=3.9
Keywords: api, contact-center, daktela, rest, sdk

# Daktela V6 Python SDK

A Python SDK for the Daktela V6 REST API.

## Installation

```bash
pip install daktela
```

## Quick Start

```python
from daktela import DaktelaClient, DaktelaConfig, DaktelaQuery, DaktelaFilter, DaktelaSort

# Initialize the client
client = DaktelaClient(
    DaktelaConfig(
        url="my.daktela.com",
        access_token="your-access-token"
    )
)

# Simple GET request
response = client.get("tickets")
print(f"Found {response.total} tickets")

# Query with filters, sorting, and pagination
query = (DaktelaQuery()
    .fields("name", "title", "stage")
    .filter(DaktelaFilter.eq("stage", "OPEN"))
    .sort(DaktelaSort.desc("created"))
    .take(50))

response = client.get("tickets", query)

for ticket in response:
    print(f"{ticket['name']}: {ticket['title']}")

# Iterate through large datasets efficiently
for ticket in client.iterate("tickets", query):
    print(ticket["name"])

# Close the client when done
client.close()
```

## Features

- Full CRUD operations (GET, POST, PUT, DELETE)
- Fluent query builder with filters, sorting, and pagination
- Memory-efficient pagination iterator
- Automatic retry with exponential backoff
- Rate limit handling with Retry-After support
- Type hints for IDE support
- Comprehensive exception hierarchy

## Configuration

```python
from daktela import DaktelaClient, DaktelaConfig, AuthMethod, RetryConfig, RateLimitConfig

config = DaktelaConfig(
    url="my.daktela.com",
    access_token="your-token",
    auth_method=AuthMethod.HEADER,  # or QUERY, COOKIE
    timeout=30.0,
    user_agent="MyApp/1.0",
    verify_ssl=True,
)

client = DaktelaClient(
    config,
    retry_config=RetryConfig(max_retries=5),
    rate_limit_config=RateLimitConfig(max_wait=120.0),
)
```

## Query Building

### Filters

```python
from daktela import DaktelaFilter

# Comparison operators
DaktelaFilter.eq("field", "value")      # equals
DaktelaFilter.neq("field", "value")     # not equals
DaktelaFilter.gt("field", 5)            # greater than
DaktelaFilter.gte("field", 5)           # greater than or equal
DaktelaFilter.lt("field", 10)           # less than
DaktelaFilter.lte("field", 10)          # less than or equal
DaktelaFilter.like("field", "partial")  # contains

# List operators
DaktelaFilter.in_("status", ["A", "B", "C"])
DaktelaFilter.not_in("status", ["X", "Y"])

# OR combinations
DaktelaFilter.or_(
    DaktelaFilter.eq("stage", "OPEN"),
    DaktelaFilter.eq("stage", "PENDING")
)
```

### Sorting

```python
from daktela import DaktelaSort

DaktelaSort.asc("name")
DaktelaSort.desc("created")
```

### Complete Query

```python
from daktela import DaktelaQuery, DaktelaFilter, DaktelaSort

query = (DaktelaQuery()
    .fields("name", "title", "stage")
    .filter(DaktelaFilter.eq("stage", "OPEN"))
    .filter(DaktelaFilter.gte("priority", 5))
    .sort(DaktelaSort.desc("priority"))
    .sort(DaktelaSort.asc("created"))
    .take(100)
    .skip(0))
```

## Error Handling

```python
from daktela import (
    DaktelaException,
    DaktelaUnauthorizedException,
    DaktelaNotFoundException,
    DaktelaRateLimitException,
)

try:
    response = client.get("tickets/123")
except DaktelaNotFoundException:
    print("Ticket not found")
except DaktelaUnauthorizedException:
    print("Invalid access token")
except DaktelaRateLimitException as e:
    print(f"Rate limited, retry after {e.retry_after} seconds")
except DaktelaException as e:
    print(f"API error: {e.message}")
```

## Pagination

```python
# Automatic pagination through large datasets
for ticket in client.iterate("tickets", query, page_size=100):
    process(ticket)

# Limit total results
for ticket in client.iterate("tickets", query, max_items=500):
    process(ticket)

# Manual pagination
from daktela import DaktelaPagination

page = DaktelaPagination.page(page_number=2, page_size=25)
query = DaktelaQuery().pagination(pagination=page)
```

## Health Check

```python
# Simple ping
if client.ping():
    print("API is healthy")

# Detailed health check
health = client.health_check()
print(f"Healthy: {health['healthy']}")
print(f"Latency: {health['latency_ms']}ms")
```

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/

# Linting
ruff check src/
```

## License

MIT License - see LICENSE file for details.