core-sentry 2.0.0

A thin Python wrapper around the Sentry SDK providing a decorator for automatic initialization and standalone functions for the full event lifecycle.

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.

---

Installation

pip install core-sentry
uv pip install core-sentry

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

Quick Start

pip install core-sentry
pip install -e ".[dev]"    # For development

Decorator usage

The with_sentry decorator initializes Sentry before the wrapped function runs. For long-running services the defaults are sufficient:

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"

For ETLs and short-lived scripts running in containers, enable capture_exceptions and flush to guarantee delivery even when atexit handlers are skipped (e.g. SIGKILL or 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

Use the standalone API when you need explicit control over initialization, capture, and flush within a single process:

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

init_sentry(SentryConfig(
    dsn="https://...",
    env="production",
    tags={"service": "etl-pipeline"},
))

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

# Recoverable error mid-job
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"},
    )

# Guarantee delivery before process exit
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.

Links

• Documentation: https://core-sentry.readthedocs.io/en/latest/

• Repository: https://gitlab.com/bytecode-solutions/core/core-sentry

• Issues: https://gitlab.com/bytecode-solutions/core/core-sentry/-/issues

• Changelog: https://gitlab.com/bytecode-solutions/core/core-sentry/-/blob/master/CHANGELOG.md

• PyPI: https://pypi.org/project/core-sentry/

Support

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

Authors

• Alejandro Cora González - Initial work - [e-mail]