core-sentry#

A thin Python wrapper around the Sentry SDK providing a decorator for automatic initialization and standalone functions for the full event lifecycle: initialization, exception capture, message capture, and flush.

Python Versions License Pipeline Status Docs Status Security

Documentation Contents#

Index:

Features#

  • Decorator-based initialization: wrap any function with @with_sentry to initialize the SDK before it runs

  • Duplicate initialization guard: skips sentry_sdk.init if the client is already configured

  • Tag management: set global tags via SentryConfig and per-event tags via SentryRuntimeConfig

  • Exception capture: capture_exception() sends errors with optional per-event tags and extra context using an isolated scope

  • Message capture: capture_message() sends informational/warning events with configurable severity

  • Event flush: flush_sentry() blocks until the event queue drains; essential for short-lived scripts and ETLs

  • Flexible decorator syntax: usable with or without parentheses

  • Fully typed: complete type annotations including Literal for severity levels

Installation#

pip install core-sentry
uv pip install core-sentry  # Or using UV...
pip install -e ".[dev]"     # For development...

Quick Start#

Decorator: initialize Sentry before a function runs:

from core_sentry.base import SentryConfig
from core_sentry.decorators.base import with_sentry

@with_sentry(config=SentryConfig(
    dsn="https://...",
    env="production",
    tags={"service": "my-api"},
))
def my_function():
    return "Hello World"

ETL / short-lived script: enable explicit capture and flush to guarantee delivery even when atexit is skipped (e.g. SIGKILL, OOM):

from core_sentry.base import SentryConfig
from core_sentry.decorators.base import SentryRuntimeConfig, with_sentry

@with_sentry(
    config=SentryConfig(
        dsn="https://...",
        env="production",
        tags={"service": "etl-pipeline", "version": "1.0.0"},
        traces_sample_rate=0.5,
    ),
    runtime_config=SentryRuntimeConfig(
        capture_exceptions=True,
        flush=True,
        flush_timeout=5.0,
        tags={"job": "daily-sync"},
        extra={"rows_processed": 9999},
    ),
)
def run_etl():
    pass

Standalone functions: explicit control over the full event lifecycle:

from core_sentry.base import (
    SentryConfig,
    init_sentry,
    capture_exception,
    capture_message,
    flush_sentry,
)

init_sentry(SentryConfig(dsn="https://...", env="production"))

capture_message("ETL job started", level="info", tags={"job": "daily-sync"})

try:
    raise ValueError("Unexpected null value in column 'amount'")

except ValueError as exc:
    capture_exception(
        exc,
        tags={"job": "daily-sync", "stage": "transform"},
        extra={"row_index": 1042, "column": "amount"},
    )

flushed = flush_sentry(timeout=5.0)
if not flushed:
    print("WARNING: some Sentry events may not have been delivered.")

Development#

# Create and activate virtual environment
virtualenv --python=python3.12 .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
python -m unittest discover -s tests -p "tests_*.py"
python manager.py run-tests
python manager.py run-coverage

# Lint and security scan
pylint core_sentry
bandit -r core_sentry

# Run across all supported Python versions
tox

Contributing#

Contributions are welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Write tests for new functionality

  4. Ensure all tests pass: python -m unittest discover -s tests -p "tests_*.py"

  5. Run linting: pylint core_sentry

  6. Run security checks: bandit -r core_sentry

  7. Submit a pull request

License#

This project is licensed under the MIT License. See the LICENSE file for details.

Support#

For questions or support, please open an issue on GitLab or contact the maintainers.

Authors#