Metadata-Version: 2.4
Name: reo-census
Version: 0.1.0
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

```python
from reo_census import ReoEventLogger

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

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

Event property values are sent as strings.

- **`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.

## Security notes

- **TLS:** Use `https://` endpoints in production. The default is HTTPS to [telemetry.reo.dev](https://telemetry.reo.dev/data).
- **Endpoint control:** `endpoint_url` and `PACKAGE_TRACKER_ENDPOINT` should only be set by operators or trusted config. Arbitrary schemes (`file:`, etc.) are rejected.
- **Payload size:** JSON bodies larger than 256 KiB are not sent (guardrail against accidental huge posts).
- **Secrets:** Do not put API keys or tokens in `log_event` properties; verbose mode logs the body to stderr when enabled.
