Metadata-Version: 2.5
Name: apphelm
Version: 0.5.0
Summary: Official Python server SDK for Apphelm: events, identify, fail-closed feature flags, errors and tracing.
Project-URL: Homepage, https://apphelm.dev
Project-URL: Documentation, https://apphelm.dev/docs
Author-email: SansaVision <support@sansavision.com>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Keywords: analytics,apphelm,error-monitoring,feature-flags,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Apphelm Python SDK

The official Python client for [Apphelm](https://apphelm.dev), 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.

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

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

```py
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

```py
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

```py
# 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

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