API reference

Component

class asphalt.exceptions.component.ExceptionReporterComponent(reporters=None, install_default_handler=True, **default_args)

Creates one or more ExceptionReporter resources.

These resources are used by report_exception() which calls each one of them to report the exception.

Optionally (and by default), a default exception handler is also installed for the event loop which calls report_exception() for all exceptions that occur in the event loop machinery or in tasks which are garbage collected without ever having been awaited on.

Exception reporters can be configured in two ways:

a single reporter, with configuration supplied directly as keyword arguments to this
component’s constructor
multiple reporters, by providing the reporters option where each key is the resource
name and each value is a dictionary containing that reporter’s configuration

Each exception reporter configuration has one special option that is not passed to the constructor of the backend class:

backend: entry point name of the reporter backend class (required)

Parameters:

reporters – a dictionary of resource name ⭢ constructor arguments for the chosen reporter class
install_default_handler – True to install a new default exception handler for the event loop when the component starts
default_args – default values for constructor keyword arguments

async start(ctx)

Perform any necessary tasks to start the services provided by this component.

In this method, components typically use the context to:

add resources and/or resource factories to it (add_resource() and add_resource_factory())
request resources from it asynchronously (request_resource())

It is advisable for Components to first add all the resources they can to the context before requesting any from it. This will speed up the dependency resolution and prevent deadlocks.

Parameters:: ctx (Context) – the containing context for this component
Return type:: AsyncIterator[None]

Functions

asphalt.exceptions.report_exception(ctx, message, exception=None, *, logger=True)

Report an exception to all exception reporters in the given context (and optionally log it too)

Parameters:

ctx (Context) – context object to use for adding tags and other contextual information to the report, as well as for retrieving the sentry client object
message (str) – a free-form message to pass to the exception reporters (often used to describe what was happening when the exception occurred)
exception (BaseException | None) – the exception to report; retrieved from sys.exc_info() if omitted
logger (logging.Logger | str | bool) – logger instance or logger name to log the exception in, instead of the name of the module where the exception was raised (or False to skip logging the exception)

Return type:

None

Abstract classes

class asphalt.exceptions.api.ExceptionReporter

Interface for services that log exceptions on external systems.

Exception reporter instances must be made available as resources in the context for them to take effect.

abstract report_exception(ctx, exception, message, extra)

Report the given exception to an external service.

Implementors should typically queue an event or something instead of using a synchronous operations to send the exception.

Parameters:

ctx – the context in which the exception occurred
exception – an exception
message – an accompanying message
extra – backend specific extra contextual information gathered from extras providers

class asphalt.exceptions.api.ExtrasProvider

Interface for a provider of extra data for exception reporters.

Implementors must check the type of the reporter and provide extra data specific to each backend. See the documentation of each reporter class to find out the acceptable data structures.

Note

Extras are gathered from providers in an unspecified order. The dicts are then merged, so any conflicting keys might be lost.

abstract get_extras(ctx, reporter)

Return context specific extras for the given exception reporter backend.

Parameters:

ctx – the context in which the exception was raised
reporter – the exception reporter for which to provide extras

Returns:

a dict containing backend specific extra data, or None if no appropriate extra data can be provided

Exception reporters

class asphalt.exceptions.reporters.sentry.SentryExceptionReporter(integrations=(), before_send=None, before_breadcrumb=None, **options)

Reports exceptions using the Sentry service.

To use this backend, install asphalt-exceptions with the sentry extra.

All keyword arguments are directly passed to sentry_sdk.init(). The following defaults are set for the client arguments:

environment: “development” or “production”, depending on the __debug__ flag

Integrations can be added via the integrations option which is a list where each item is either an object that implements the sentry_sdk.integrations.Integration interface, or a dictionary where the type key is a module:varname reference to a class implementing the aforementioned interface. The args key, when present, should be a sequence that is passed to the integration as positional arguments, while the kwargs key, when present, should be a mapping of keyword arguments to their values.

The extras passed to this backend are passed to sentry_sdk.capture_exception() as keyword arguments. Two such options have been special cased and can be looked up as a module:varname reference:

before_send
before_breadcrumb

For more information, see the Sentry SDK documentation.

report_exception(ctx, exception, message, extra)

Report the given exception to an external service.

Implementors should typically queue an event or something instead of using a synchronous operations to send the exception.

Parameters:

ctx – the context in which the exception occurred
exception – an exception
message – an accompanying message
extra – backend specific extra contextual information gathered from extras providers

class asphalt.exceptions.reporters.raygun.RaygunExceptionReporter(api_key, **config)

Reports exceptions using the Raygun service.

To use this backend, install asphalt-exceptions with the raygun extra.

All keyword arguments are directly passed to raygun4py.raygunprovider.RaygunSender.

The extras passed to this backend are passed to raygun4py.raygunprovider.RaygunSender.send_exception() as keyword arguments.

Warning

The current implementation of this backend sends exceptions synchronously, potentially blocking the event loop.

report_exception(ctx, exception, message, extra)

Report the given exception to an external service.

Implementors should typically queue an event or something instead of using a synchronous operations to send the exception.

Parameters:

ctx – the context in which the exception occurred
exception – an exception
message – an accompanying message
extra – backend specific extra contextual information gathered from extras providers