Metadata-Version: 2.4
Name: reo-census
Version: 0.1.2
Summary: Custom telemetry client for Reo (POST JSON to telemetry.reo.dev)
Author-email: Saurabh <saurabh@reo.dev>
License-Expression: MIT
Keywords: telemetry,analytics,reo,census
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# reo-census (Python)

Send custom telemetry events to Reo’s ingestion API. Defaults to `https://telemetry.reo.dev/data` (same as the npm `reo-census` tracker).

## Install

```bash
pip install reo-census
```

## Usage

Each send uses a JSON body shaped like:

```json
{
  "activity_type": "pypi_download",
  "package": "<your_package>",
  "version": "1.0.0"
}
```

Set your package name and version on the logger; optional extra keys can be passed to `log_event` (they are merged in and override defaults where keys overlap). All values are sent as strings.

```python
from reo_census import ReoEventLogger

logger = ReoEventLogger(
    endpoint_url="https://telemetry.reo.dev/data",
    timeout=3.0,
    package_name="my-package",
    package_version="1.0.0",
)
# Default: non-blocking — HTTP runs in a background thread; returns True if queued.
ok = logger.log_event()

# Add or override fields:
ok = logger.log_event({"region": "us-east-1"})

# Wait for the HTTP round-trip (tests, debugging, or short-lived scripts):
ok = logger.log_event(blocking=True)
```

- **`blocking=False` (default):** returns `True` if the event was queued, `False` if opted out, URL rejected, or payload too large. Does **not** reflect HTTP success.
- **`blocking=True`:** returns `True` only after a successful HTTP 2xx (with retries), `False` on failure or opt-out.

Short-lived programs (one-shot CLI) should use **`blocking=True`** or the process may exit before the daemon thread finishes sending.

## Opt-out

Respected when any of these apply:

- `PACKAGE_TRACKER_ANALYTICS=false`
- `DO_NOT_TRACK` is `1`, `true`, or `yes` (case-insensitive)

## Endpoint override

Set `PACKAGE_TRACKER_ENDPOINT` to override the URL (same as the Node tracker). Only `http://` and `https://` URLs with a host are accepted.

## Verbose logging

Set `PACKAGE_TRACKER_VERBOSE=true` to print send details to stderr.
