Metadata-Version: 2.4
Name: qurvo-python
Version: 0.1.0
Summary: Qurvo analytics SDK for Python — zero-dependency event tracking
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# qurvo-python

Python SDK for [Qurvo](https://qurvo.pro) analytics. Zero runtime dependencies -- uses only the Python standard library.

## Installation

```bash
pip install qurvo-python
```

## Quick Start

```python
from qurvo import Qurvo

qurvo = Qurvo(api_key="qk_...")

# Track a custom event
qurvo.track("user-123", "purchase", {"amount": 99.99, "currency": "USD"})

# Identify a user
qurvo.identify("user-123", {"name": "John", "plan": "pro"})

# Set user properties (overwrites existing)
qurvo.set("user-123", {"plan": "enterprise"})

# Set user properties only if not already set
qurvo.set_once("user-123", {"first_seen": "2026-01-01"})

# Track a screen view
qurvo.screen("user-123", "HomeScreen", {"tab": "overview"})

# Gracefully flush and shut down
qurvo.shutdown()
```

## Configuration

```python
qurvo = Qurvo(
    api_key="qk_...",                           # Required
    endpoint="https://ingest.qurvo.pro",        # Default
    flush_interval=5.0,                         # Seconds between flushes
    flush_size=20,                              # Max events per batch
    max_queue_size=1000,                        # Max queued events
    timeout=30.0,                               # HTTP timeout in seconds
    logger=lambda msg: print(f"[qurvo] {msg}"),  # Optional debug logger
)
```

## API Reference

### `Qurvo(api_key, **kwargs)`

Create a new client instance. Starts a background thread that periodically flushes queued events to the ingest endpoint.

### `.track(distinct_id, event, properties=None)`

Track a custom event.

### `.identify(distinct_id, user_properties, anonymous_id=None)`

Identify a user and set their properties. Optionally merge an anonymous ID.

### `.set(distinct_id, properties)`

Set user properties (overwrites existing values). Uses the `$set` envelope pattern.

### `.set_once(distinct_id, properties)`

Set user properties only if they are not already set. Uses the `$set_once` envelope pattern.

### `.screen(distinct_id, screen_name, properties=None)`

Track a screen view event. The `screen_name` is added as `$screen_name` in properties.

### `.shutdown(timeout=30.0)`

Gracefully flush all remaining events and stop the background thread. Call this before your application exits.

## Requirements

- Python >= 3.9
- No runtime dependencies

## License

MIT
