# Python SDK

The official server-side Python SDK. The API mirrors `mixpanel-python`, so migrating existing code is mostly a matter of swapping the import and pointing at your Cohorly server. Python 3.8+, zero runtime dependencies, fully typed.

## Install

```bash
pip install cohorly
```

## Initialize

```python
from cohorly import Cohorly

ch = Cohorly("YOUR_PROJECT_TOKEN", api_host="https://cohorly-service.velloalabs.com")

# Track an event (distinct_id passed per call, server-side style)
ch.track("user-1", "Signed Up", {"plan": "pro", "source": "landing"})

# Link an alias to an existing distinct_id
ch.alias("user-1", "anon-7f3a")

# Update a user profile
ch.people_set("user-1", {"$first_name": "Ada", "plan": "pro"})
```

## API

| Member                                                                           | Notes                                                                                                                      |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `Cohorly(token, api_host=..., consumer=None)`                                    | Main class. Optionally pass a shared consumer (the token travels per-message, so one consumer can serve several projects). |
| `track(distinct_id, event, properties=None)`                                     | Stamps `time` (unix ms), `$insert_id`, `$lib`, `$lib_version`; your properties win (e.g. custom `$insert_id` for dedup).   |
| `import_data(distinct_id, event, timestamp_ms, props)`                           | Historical events with an explicit timestamp. Same /track pipeline - no separate secret or 5-day cutoff.                   |
| `people_set / people_set_once / people_increment / people_unset / people_delete` | Profile updates mapped to /engage ops.                                                                                     |
| `alias(alias_id, original)`                                                      | POST /alias.                                                                                                               |

## Consumers

By default every call sends immediately via the synchronous
`Consumer` (bounded inline retries). For higher throughput
use `BufferedConsumer`, which batches messages (default 50
per request, server max 500) and implements the shared Cohorly retry
contract - exponential backoff honoring `Retry-After`,
batch halving on 413, permanent drop on 400, queue capped at 1000.

```python
from cohorly import Cohorly, BufferedConsumer

consumer = BufferedConsumer(max_size=50, api_host="https://cohorly-service.velloalabs.com")
ch = Cohorly("YOUR_PROJECT_TOKEN", consumer=consumer)

for user in users:
    ch.track(user.id, "Backfill Event", {"batch": True})

consumer.flush()  # IMPORTANT: drain remaining messages before exit
```

Delivery failures raise `cohorly.CohorlyException`.
`datetime` values serialize to ISO-8601 automatically.