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:Trueto skip it.report_severity: the report'sSeverity(INFOotherwise).report_attributes: extra key/value metadata.
Classes#
Functions#
is_ignored#
is_ignored(error) -> boolWhether error asks not to be reported (report_ignored is
True).
| Parameter | Type | Description |
|---|---|---|
error | object |
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 Trueget_severity#
get_severity(error) -> Severityerror's report_severity when it is a Severity, else
LogLevel.INFO.
| Parameter | Type | Description |
|---|---|---|
error | object |
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.
| Parameter | Type | Description |
|---|---|---|
error | object |
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) -> ErrorReporterA 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.
| Parameter | Type | Description |
|---|---|---|
f | Callable[[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.
| Parameter | Type | Description |
|---|---|---|
reporters | _Reporters[Any, Any] | |
merge_with_existing | bool = 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.
| Parameter | Type | Description |
|---|---|---|
cause | Cause[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)