Metadata-Version: 2.4
Name: core-sentry
Version: 2.0.2
Summary: A thin Python wrapper around the Sentry SDK providing a decorator for automatic initialization and standalone functions for the full event lifecycle.
Author-email: Alejandro Cora González <alek.cora.glez@gmail.com>
Maintainer: Alejandro Cora González
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/bytecode-solutions/core/core-sentry
Project-URL: Repository, https://gitlab.com/bytecode-solutions/core/core-sentry
Project-URL: Documentation, https://core-sentry.readthedocs.io/en/latest/
Project-URL: Issues, https://gitlab.com/bytecode-solutions/core/core-sentry/-/issues
Project-URL: Changelog, https://gitlab.com/bytecode-solutions/core/core-sentry/-/blob/master/CHANGELOG.md
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: sentry-sdk>=2.29.1
Provides-Extra: dev
Requires-Dist: core-dev-tools>=1.2.1; extra == "dev"
Requires-Dist: core-tests>=2.0.1; extra == "dev"
Dynamic: license-file

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.

===============================================================================

.. image:: https://img.shields.io/pypi/pyversions/core-sentry.svg
    :target: https://pypi.org/project/core-sentry/
    :alt: Python Versions

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-sentry/-/blob/main/LICENSE
    :alt: License

.. image:: https://gitlab.com/bytecode-solutions/core/core-sentry/badges/release/pipeline.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-sentry/-/pipelines
    :alt: Pipeline Status

.. image:: https://readthedocs.org/projects/core-sentry/badge/?version=latest
    :target: https://readthedocs.org/projects/core-sentry/
    :alt: Docs Status

.. image:: https://img.shields.io/badge/security-bandit-yellow.svg
    :target: https://github.com/PyCQA/bandit
    :alt: Security

|


Installation
===============================================================================

.. code-block:: bash

    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
===============================================================================

.. code-block:: bash

    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:

.. code-block:: python

    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):

.. code-block:: python

    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:

.. code-block:: python

    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
===============================================================================

.. code-block:: bash

    # 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* - alek.cora.glez@gmail.com
