llms.txt

# Aptabase Python SDK

> Privacy-first, open-source analytics for Python applications. Fully async, built with httpx and asyncio. Requires Python 3.11+. GDPR-compliant. No personal data collection.

Package: `aptabase` on PyPI
Repository: https://github.com/aptabase/aptabase-python

## Installation

```bash
pip install aptabase
# or
uv add aptabase
```

## Quick Start (Context Manager)

```python
import asyncio
from aptabase import Aptabase

async def main():
    async with Aptabase("A-EU-1234567890") as client:
        await client.track("app_started")
        await client.track("user_action", {"button": "login", "screen": "home"})

asyncio.run(main())
```

## Quick Start (Manual Lifecycle)

```python
client = Aptabase("A-EU-1234567890")
await client.start()
try:
    await client.track("app_started")
finally:
    await client.stop()  # Flushes remaining events
```

## Track Events

```python
# Simple event
await client.track("page_view")

# Event with properties (str, int, float values)
await client.track("purchase", {
    "product_id": "abc123",
    "price": 29.99,
    "currency": "USD"
})
```

## Configuration

```python
client = Aptabase(
    app_key="A-EU-1234567890",    # Required. Format: A-{EU|US|SH}-{ID}
    app_version="1.2.3",          # App version string (default: "1.0.0")
    is_debug=False,               # Enable debug mode (default: False)
    max_batch_size=25,            # Max events per batch, max 25 (default: 25)
    flush_interval=10.0,          # Auto-flush interval in seconds (default: 10.0)
    timeout=30.0,                 # HTTP request timeout in seconds (default: 30.0)
    base_url="https://self.host", # Required for self-hosted (A-SH-* keys)
)
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| app_key | str | (required) | App key from Aptabase dashboard |
| app_version | str | "1.0.0" | Your application version |
| is_debug | bool | False | Debug mode flag |
| max_batch_size | int | 25 | Max events per flush batch (hard max: 25) |
| flush_interval | float | 10.0 | Seconds between auto-flushes |
| timeout | float | 30.0 | HTTP request timeout in seconds |
| base_url | str | None | Custom API URL (required for A-SH-* keys) |

## Error Handling

```python
from aptabase import Aptabase, AptabaseError, NetworkError, ConfigurationError

try:
    async with Aptabase("A-EU-1234567890") as client:
        await client.track("event")
except NetworkError as e:
    print(f"Network error: {e}, status: {e.status_code}")
except ConfigurationError as e:
    print(f"Config error: {e}")
except AptabaseError as e:
    print(f"Aptabase error: {e}")
```

## Platform Notes

- Fully async — all methods are `async`/`await`
- Requires Python 3.11+
- Uses `httpx` for HTTP requests
- Events are auto-batched and flushed every `flush_interval` seconds
- Sessions auto-rotate after 1 hour of inactivity
- Use context manager (`async with`) for automatic start/stop lifecycle
- `flush()` can be called manually to force-send queued events
- `stop()` flushes remaining events and closes the HTTP client
- App key region determines API endpoint: `A-EU-*` → EU servers, `A-US-*` → US servers, `A-SH-*` → self-hosted (requires `base_url`)

## Cross-Discovery

For all Aptabase SDKs and documentation, see: https://aptabase.com/llms.txt