GitHub

error_reporter

API reference for error_reporter.

Error reporting: hand failures to reporters such as Sentry or a log pipeline (Effect's ErrorReporter).

eff.with_error_reporting() sends the cause of each failure of eff to every reporter in CurrentErrorReporters; report(cause) sends one cause. With no reporters (the default) nothing happens. A reporter made with make turns a cause into one Report per typed error or defect, skipping interruptions, causes and errors it has seen already, and errors that ask to be ignored.

An error controls its report through attributes (TaggedError declares them; any other object may set them):

  • report_ignored: True to skip it.
  • report_severity: the report's Severity (INFO otherwise).
  • report_attributes: extra key/value metadata.

Classes

Functions

is_ignored

is_ignored(error) -> bool

Whether error asks not to be reported (report_ignored is True).

ParameterTypeDescription
errorobject

Returns bool

def is_ignored(error: object) -> bool:
    """Whether ``error`` asks not to be reported (``report_ignored`` is
    ``True``)."""
    return getattr(error, "report_ignored", False) is True

get_severity

get_severity(error) -> Severity

error's report_severity when it is a Severity, else LogLevel.INFO.

ParameterTypeDescription
errorobject

Returns Severity

def get_severity(error: object) -> Severity:
    """``error``'s ``report_severity`` when it is a ``Severity``, else
    ``LogLevel.INFO``."""
    severity = getattr(error, "report_severity", None)
    return severity if isinstance(severity, LogLevel) and severity in _SEVERITIES else LogLevel.INFO  # pyright: ignore[reportReturnType]

get_attributes

get_attributes(error) -> Mapping[str, object]

error's report_attributes mapping, or an empty one.

ParameterTypeDescription
errorobject

Returns Mapping[str, object]

def get_attributes(error: object) -> Mapping[str, object]:
    """``error``'s ``report_attributes`` mapping, or an empty one."""
    attributes = getattr(error, "report_attributes", None)
    return attributes if isinstance(attributes, Mapping) else _NO_ATTRIBUTES  # pyright: ignore[reportUnknownVariableType]

make

make(f) -> ErrorReporter

A reporter calling f once per typed error or defect of each cause. Interruptions, ignored errors, and causes or errors this reporter has already seen (by identity) are skipped.

ParameterTypeDescription
fCallable[[Report], object]

Returns ErrorReporter

def make(f: Callable[[Report], object]) -> ErrorReporter:
    """A reporter calling ``f`` once per typed error or defect of each
    cause. Interruptions, ignored errors, and causes or errors this
    reporter has already seen (by identity) are skipped."""
    return _Reporter(f)

layer

layer(reporters, *, merge_with_existing=False) -> Layer[Any, Any, Any]

A layer that replaces the current reporters with reporters (or adds them, with merge_with_existing). An item may be an effect making a reporter; it runs when the layer builds.

ParameterTypeDescription
reporters_Reporters[Any, Any]
merge_with_existingbool = False

Returns Layer[Any, Any, Any]

def layer(
    reporters: _Reporters[Any, Any], *, merge_with_existing: bool = False
) -> Layer[Any, Any, Any]:
    """A layer that replaces the current reporters with ``reporters`` (or
    adds them, with ``merge_with_existing``). An item may be an effect
    making a reporter; it runs when the layer builds."""
    given = list(reporters)

    def build():
        current: list[ErrorReporter] = (
            list((yield from CurrentErrorReporters())) if merge_with_existing else []
        )
        for item in given:
            made: ErrorReporter = (yield from item) if isinstance(item, Effect) else item
            if all(made is not existing for existing in current):
                current.append(made)
        return tuple(current)

    return effect(CurrentErrorReporters, _Gen(build))

report

report(cause) -> Effect[None]

Send cause to the current reporters.

ParameterTypeDescription
causeCause[object]

Returns Effect[None]

def report(cause: Cause[object]) -> Effect[None]:
    """Send ``cause`` to the current reporters."""

    def body(fiber: Fiber[Any, Any]) -> Effect[None]:
        report_unsafe(fiber, cause)
        return _VOID

    return _WithFiber(body)