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

pip install reo-census

Usage

Each send uses a JSON body shaped like:

{
  "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.

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.