Metadata-Version: 2.4
Name: stacktrace-sdk-python
Version: 0.2.0
Summary: Python SDK for sending error and event reports to the Artim Stacktrace backend.
License: MIT
Project-URL: Homepage, https://github.com/Artim-Industries/stacktrace-sdk-python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# stacktrace-sdk-python

Python SDK for the Artim Stacktrace backend. This package provides basic error reporting and event capture utilities similar to the existing React SDK.

## Usage

```python
from bug_sdk_python import ArtimStacktrace

ArtimStacktrace.init(
    api_key="your-api-key",
    project_id="your-project-id",
)

ArtimStacktrace.capture_message("Something went wrong", level="warn")

try:
    1 / 0
except Exception as error:
    ArtimStacktrace.capture_exception(error)

ArtimStacktrace.set_user({"id": "123", "email": "user@example.com"})

# Or identify by callback
ArtimStacktrace.identify(lambda: {"id": "123", "email": "user@example.com"})
```

## Features

- `init` sets API key, project id, environment, release, and backend endpoint
- `capture_exception` sends exception details and stacktrace
- `capture_message` sends simple event messages
- `set_user` and `identify` attach user context to events
- default backend endpoint: `https://stacktrace-backend.artim-industries.com/api/events`

# Using with FastAPI

add this to main.py

```

@app.middleware("http")
async def artim_middleware(request: Request, call_next):
    try:
        response = await call_next(request)
        return response
    except Exception as e:
        capture_exception(e)
        raise

```
## Environment detection

One project holds several environments (`development`, `staging`, `production`,
plus any custom ones). `environment` and `release` are detected automatically and
only need to be passed to `init()` to override the detection.

Environment is resolved in this order:

1. `environment` passed to `init()`
2. `ARTIM_ENV`, then `ENVIRONMENT`, `ENV`, `APP_ENV`, `STAGE`, `DJANGO_ENV`,
   `FLASK_ENV`, `RAILS_ENV`
3. Debug flags — `ARTIM_DEBUG`, `DEBUG`, `FLASK_DEBUG`, `DJANGO_DEBUG` set to a
   truthy value, or Django's `settings.DEBUG` → `development`
4. otherwise `production`

Aliases are normalized: `dev`, `local`, `debug` → `development`; `stage`, `stg`,
`preview` → `staging`; `prod`, `live` → `production`. Any other value is kept as
a custom environment and registered on the project automatically.

## Release detection

1. `release` passed to `init()`
2. `ARTIM_RELEASE`, then `APP_VERSION`, `RELEASE`, `SOURCE_VERSION`,
   `HEROKU_SLUG_COMMIT`, `RAILWAY_GIT_COMMIT_SHA`, `FLY_MACHINE_VERSION`,
   `GIT_COMMIT`, `GITHUB_SHA`
3. Installed package version, when `distribution` names your package:
   ```python
   ArtimStacktrace.init(api_key="...", distribution="my-service")
   ```
4. `version` from `pyproject.toml` in the working directory
5. Short git SHA of `HEAD`
6. `"unknown"` plus a warning

To check what the SDK resolved:

```python
ArtimStacktrace.get_environment()
ArtimStacktrace.get_release()
```
