Why an effect failed.
A Cause is a flat list of reasons, as in Effect 4:
Fail: an expected, typed error. This is what theEchannel tracks.Die: a defect. An exception nobody planned for.Interrupt: the fiber was interrupted, optionally by another fiber.
Most causes hold one reason. More appear when finalizers fail while unwinding, or when concurrent work fails in several places at once.
Each reason carries annotations: services keyed by tag, such as the
tracer.StackTrace frame a failure inside a span records. They take part
in equality, as in Effect, but not in the hash.
| Attribute | Type | Description |
|---|---|---|
E_co | = TypeVar('E_co', covariant=True) | |
empty | Cause[Never] = Cause(()) |
Classes#
Functions#
reason_annotations#
reason_annotations(reason) -> ContextA reason's annotations as a Context.
| Parameter | Type | Description |
|---|---|---|
reason | Reason[object] |
Returns Context
def reason_annotations(reason: Reason[object]) -> Context:
"""A reason's annotations as a ``Context``."""
return _context(reason.annotations)merge#
merge(*causes) -> Cause[E]Combine causes of failures that happened together: a body and its finalizers, or concurrent siblings. A defect in any of them makes every typed error a defect, so the result cannot be recovered.
| Parameter | Type | Description |
|---|---|---|
causes | Cause[E] = () |
Returns Cause[E]
def merge[E](*causes: Cause[E]) -> Cause[E]:
"""Combine causes of failures that happened together: a body and its
finalizers, or concurrent siblings. A defect in any of them makes
every typed error a defect, so the result cannot be recovered."""
combined: Cause[E] = Cause(())
for c in causes:
combined = combined + c
return combined.elect_defects()from_reasons#
from_reasons(reasons) -> Cause[E]A cause holding exactly reasons, in order, repeats included.
| Parameter | Type | Description |
|---|---|---|
reasons | Iterable[Reason[E]] |
Returns Cause[E]
def from_reasons[E = Never](reasons: Iterable[Reason[E]]) -> Cause[E]:
"""A cause holding exactly ``reasons``, in order, repeats included."""
return Cause(tuple(reasons))fail#
fail(error) -> Cause[E]| Parameter | Type | Description |
|---|---|---|
error | E |
Returns Cause[E]
def fail[E](error: E) -> Cause[E]:
return Cause((Fail(error),))die#
die(defect) -> Cause[Never]| Parameter | Type | Description |
|---|---|---|
defect | BaseException |
Returns Cause[Never]
def die(defect: BaseException) -> Cause[Never]:
return Cause((Die(defect),))interrupt#
interrupt(fiber_id=None) -> Cause[Never]| Parameter | Type | Description |
|---|---|---|
fiber_id | int | None = None |
Returns Cause[Never]
def interrupt(fiber_id: int | None = None) -> Cause[Never]:
return Cause((Interrupt(fiber_id),))