Apphelm Python SDK

The official Python client for Apphelm, for server-side code: product events, identify, fail-closed feature flags, error and message reporting, cron check-ins and tracing. One module, standard library only, Python 3.10 or later.

pip install apphelm

Use a server API key (ahl_…) from your Apphelm workspace and keep it secret. Never ship it in a browser or mobile app.

import os
from apphelm import Apphelm

apphelm = Apphelm(api_key=os.environ["APPHELM_API_KEY"])

# A product event for one person.
apphelm.capture("org_…", "prd_…", distinct_id=customer.id, event_name="invoice_sent")

# Feature flags fail closed: any network, timeout or API error evaluates to False.
if apphelm.is_enabled("new-checkout", customer.id, product_id="prd_…"):
    render_new_checkout()
variant = apphelm.get_feature_flag("org_…", "prd_…", "pricing-test", customer.id)  # variant, True or False

Identify

Every trait needs provenance. A trait without a matching trait_sources entry raises ValueError before anything is sent, because the API would reject it.

apphelm.identify("org_…", "prd_…", external_user_id=account.id,
                 traits={"plan": "builder"},
                 trait_sources={"plan": {"sourceType": "auth", "sourceId": "session", "verification": "integration_verified"}})

Errors and messages

try:
    charge(order)
except Exception as error:
    apphelm.capture_exception("org_…", "prd_…", error, release=os.environ.get("RELEASE"),
                              environment="production", tags={"route": "/charges"}, user_id=account.id)

# Report uncaught exceptions (main thread and other threads) as unhandled issues.
# The previous hooks still run, so the traceback prints and the process exits as before.
restore = apphelm.capture_unhandled("org_…", "prd_…", release=os.environ.get("RELEASE"), environment="production")

apphelm.capture_message("org_…", "prd_…", "Payment provider fell back to retries", level="warning")

Tracebacks are scrubbed of email addresses, keys and query strings before they are sent, and user_id is sent only as a hash. Pass before_send= to the constructor to change or drop exceptions and messages: return the properties (changed or not), or None to drop the event. A hook that raises drops the event.

Tracing

# Continue the caller's trace (from the browser or another service), or start a new one.
with apphelm.start_transaction("org_…", "prd_…", "POST /charges", traceparent=request.headers.get("traceparent")) as tx:
    with tx.start_span("db.query", "select order"):
        ...

Apphelm(api_key, traces_sample_rate=0.2) keeps a share of new transactions; a transaction that continues an incoming traceparent keeps the caller's sampling decision.

Cron check-ins

apphelm.check_in("prd_…", monitor="nightly-export", status="ok", duration_ms=5400)

Errors from the client

Failed requests raise ApphelmError with status and code. Flag checks (is_enabled, get_feature_flag) never raise for a failed request; they return False.

Licence

Proprietary. See LICENSE: use requires an active Apphelm service agreement.

Releasing this package: docs/SDK-RELEASING.md in the Apphelm repository.