Install on Python · Sankofa Docs

The Sankofa Python SDK is published to PyPI as sankofa-catch. Import it as sankofa_catch. It captures errors, breadcrumbs, transactions, and ships WSGI and ASGI middleware adapters for any Python web framework.

Requirements

Python 3.9+ (3.11+ recommended)
pip 22+

1. Install the package

bash

pip install sankofa-catch

2. Initialize at startup

Call sankofa_catch.init once, before any imports that may throw — typically the very first thing in wsgi.py, asgi.py, or your CLI entry point.

Pythonapp.py

import os
import sankofa_catch

sankofa_catch.init(
  api_key=os.environ["SANKOFA_KEY"],
  endpoint="https://api.sankofa.dev",
  release=os.environ.get("RELEASE_SHA"),
  environment=os.environ.get("ENV", "production"),
)

Common init options

api_keystrRequired

Your project's server-side API key.

endpointstrRequired

Server base URL.

releasestr

Commit SHA or version tag — used to group source-mapped errors.

environmentstrdefault production

Free-form label (development, staging, production).

app_versionstr

Your app's user-facing version string.

traces_sample_ratefloatdefault 0.1

Distributed-tracing sample rate (0.0–1.0).

autocapture_consolebooldefault True

Capture print() / logging.error as breadcrumbs.

capture_unhandledbooldefault True

Auto-capture sys.excepthook.

3. Wire your framework

Pythonapp.py

import os
from flask import Flask
import sankofa_catch
from sankofa_catch.wsgi import SankofaWSGI

sankofa_catch.init(api_key=os.environ["SANKOFA_KEY"], endpoint="https://api.sankofa.dev")

app = Flask(__name__)
app.wsgi_app = SankofaWSGI(app.wsgi_app)

@app.route("/")
def home():
  return "ok"

Pythonwsgi.py

import os
import sankofa_catch
from sankofa_catch.wsgi import SankofaWSGI
from django.core.wsgi import get_wsgi_application

sankofa_catch.init(api_key=os.environ["SANKOFA_KEY"], endpoint="https://api.sankofa.dev")

application = SankofaWSGI(get_wsgi_application())

Pythonmain.py

import os
from fastapi import FastAPI
import sankofa_catch
from sankofa_catch.asgi import SankofaASGI

sankofa_catch.init(api_key=os.environ["SANKOFA_KEY"], endpoint="https://api.sankofa.dev")

app = FastAPI()
app.add_middleware(SankofaASGI)

@app.get("/")
async def home():
  return {"ok": True}

Pythonworker.py

import os
import sankofa_catch

sankofa_catch.init(api_key=os.environ["SANKOFA_KEY"], endpoint="https://api.sankofa.dev")

try:
  do_work()
except Exception as exc:
  sankofa_catch.capture_exception(exc)
  raise

4. Verify the install

Python

sankofa_catch.capture_message("install_check")

Open app.sankofa.dev → Live events. The message should appear with a python source label and the interpreter version captured under default properties.

What's next

Send your first event

Multi-platform first-event walkthrough.

Reference

Python SDK reference

Capture, transactions, profiling, WSGI + ASGI middleware.

Catch

Server error tracking

Capture exceptions, breadcrumbs, source maps.