Metadata-Version: 2.5
Name: uptic
Version: 0.1.1
Summary: Report errors and structured logs to Uptic from Python scripts and services
Project-URL: Homepage, https://uptic.run
Project-URL: Repository, https://github.com/thevedus/uptic
Project-URL: Issues, https://github.com/thevedus/uptic/issues
Author-email: Vedus <thevedus@gmail.com>
License: MIT
License-File: LICENSE
Keywords: error-tracking,logging,observability,uptic
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# uptic

Report errors and structured logs to Uptic from Python.

No runtime dependencies — one `urllib` POST.

## Install

```bash
pip install uptic
```

## Inside an Uptic script

The script runner injects credentials, so there is nothing to configure:

```python
from uptic import uptic

def fetch(payload, context):
    client = uptic()

    client.info("starting", {"trigger": context.get("type")})

    with client.catching():
        result = do_the_work(payload)

    client.info("done", {"count": len(result)})
    return result
```

`catching()` reports whatever is raised and then re-raises, so the execution is
still recorded as failed. Pass `reraise=False` to swallow it instead.

## In a service

There is no injected environment, so pass a **public ingest key** (`pk_…`,
created under Settings → API Keys → Public Ingest Keys). Never use an `sk_` API
key here — it carries full workspace permissions.

```python
from uptic import UpticClient

client = UpticClient(
    base_url="https://app.uptic.run",
    ingest_key="pk_your_public_key",
    service="billing-worker",
    environment="production",
    release=os.environ.get("GIT_SHA"),
)

try:
    charge(order)
except Exception as err:
    client.capture_error(err, tags={"order": order.id})
    raise
```

## API

| Method | What it does |
| --- | --- |
| `uptic(**config)` | Get (and configure) the shared client |
| `capture_error(error, **options)` | Report one error. Returns `True` if accepted |
| `capture_batch(events)` | Report several in one request |
| `catching(reraise=True, **options)` | Context manager: report, then re-raise |
| `log(level, message, meta=None)` | One JSON line to stdout/stderr |
| `debug` / `info` / `warn` / `error` | Shorthands for `log` |
| `config(name, fallback=None)` | Read an injected env value |

`capture_error` accepts an exception or a plain string, plus `level`, `tags`,
`context`, `fingerprint` and `service`.

### Config

Every field falls back to an environment variable, which is what the script
runner sets:

| Argument | Env var |
| --- | --- |
| `base_url` | `UPTIC_BASE_URL` |
| `ingest_key` | `UPTIC_INGEST_KEY` |
| `service` | `UPTIC_WORKER_ID` (else `"default"`) |
| `environment` | `UPTIC_ENVIRONMENT` |
| `release` | `UPTIC_RELEASE` |

## Two guarantees

**Reporting never raises.** `capture_error` returns `False` on a network
failure. A monitoring call that takes down the thing it monitors is worse than
a missing data point.

**Logging makes no network call.** `log()` writes one JSON line to
stdout/stderr; the script runner already captures both into the execution
record, so logging works offline and costs nothing.

## Development

```bash
python -m pytest packages/python-sdk/tests -q
```
