Metadata-Version: 2.4
Name: aperioflow
Version: 0.1.0
Summary: Report errors from Python to AperioFlow. No dependencies.
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# AperioFlow for Python

Report errors from Python 3.8 or later to an AperioFlow project. No dependencies: events go to your project's ingest URL with
`urllib`.

Not on PyPI yet. Until it is, copy the `aperioflow` folder into your project.

## Set up

Open the project in AperioFlow, choose **Set up reporting** and copy the ingest URL.

```python
import aperioflow

aperioflow.init(
    "https://app.aperioflow.co.uk/ingest/YOUR_KEY",
    release="1.4.0",          # optional, groups events by release and finds regressions
    environment="production",  # optional
)
```

After `init`, uncaught exceptions are reported through `sys.excepthook`; the previous hook still runs, so the traceback is printed and
the program exits as before (`capture_uncaught=False` turns that off).

## Report errors yourself

```python
try:
    charge_card(order)
except Exception as exc:
    aperioflow.capture_exception(exc, fingerprint="card-charge", extra={"order_id": order.id})

aperioflow.capture_message("Queue is backing up", level="warning")
aperioflow.add_breadcrumb("Started nightly import", category="job")
aperioflow.set_tag("region", "eu-west-2")
aperioflow.set_user(id=user.id)  # only the id is sent
```

`capture_exception()` with no argument reports the exception being handled. Sends wait for the answer (5 seconds at most); pass
`background=True` to `init` to send on a thread, and call `aperioflow._client.flush()` before the program exits.

## Options

| Option | What it does |
| --- | --- |
| `ingest_url` | Required. The project's ingest URL. |
| `release`, `environment` | Sent with every event. |
| `sample_rate` | 0 to 1 (default 1). The share of events sent. |
| `before_send(event)` | Change an event, or return `None` to drop it. |
| `capture_uncaught` | Default `True`. |
| `timeout`, `background` | How long one send may take (default 5 seconds), and whether to send on a thread. |

## Privacy

- Nothing about the user, the machine or its IP address is collected on its own. A user id is sent only when you call `set_user`, and
  only the id, whatever else you pass.
- Before an event leaves the process, values of keys that name a secret (password, token, cookie, authorization, api_key and the like),
  Bearer and Basic credentials, email addresses and card numbers are replaced with `[redacted]` markers. The server scrubs again before
  it stores anything.
- Breadcrumbs are limited to the latest 50, and the event's extra data to the server's 20 KB.
- A failed send never raises into your app.

## Tests

```bash
python3 -m unittest
```
