asyncutils.exceptions¶

Exception handling utilties and exception classes used by this module.

Attributes¶

`CRITICAL`	The tuple (`SystemExit`, `SystemError`, `KeyboardInterrupt`), representing exceptions that should be allowed to propagate under most error handling mechanisms.
`ignore_all`	Instance of `IgnoreErrors` that ignores all errors; that is, `IgnoreErrors(BaseException)`. Use with caution!
`ignore_noncritical`	Instance of `IgnoreErrors` that ignores all errors besides `SystemExit`, `SystemError` and `KeyboardInterrupt`. Equivalent to `ignore_all.excluding(CRITICAL)`.
`ignore_stopaiteration`	Instance of `IgnoreErrors` that ignores `StopAsyncIteration`. Equivalent to `IgnoreErrors(StopAsyncIteration)`.
`ignore_stopiteration`	Instance of `IgnoreErrors` that ignores `StopIteration`. Equivalent to `IgnoreErrors(StopIteration)`.
`ignore_typeerrs`	Instance of `IgnoreErrors` that ignores `TypeError`. Equivalent to `IgnoreErrors(TypeError)`.
`ignore_typical`	Instance of `IgnoreErrors` that ignores `Exception` and subclasses thereof. Equivalent to `IgnoreErrors()`.
`ignore_valerrs`	Instance of `IgnoreErrors` that ignores `ValueError`. Equivalent to `IgnoreErrors(ValueError)`.

Exceptions¶

`BulkheadError`	Raised when there is an error in bulkhead processing.
`BulkheadFull`	Raised when a bulkhead is full and a party requests it to execute a coroutine.
`BulkheadShutDown`	Raised when a bulkhead is being shut down and a party requests it to execute a coroutine.
`BusError`	Raised when an operation on an `EventBus` fails.
`BusPublishingError`	Raised when an event bus fails to publish an event.
`BusShutDown`	Raised when subscription or publishing operations are called on an `EventBus` that is closing down.
`BusStatsError`	Raised when attempting to access publishing statistics on an `EventBus` whose statistics are not tracked.
`BusTimeout`	Raised when an `EventBus` takes too long to publish an event.
`CircuitBreakerError`	Base class for circuit breaker errors.
`CircuitHalfOpen`	Raised when a circuit exceeds its maximum calls in the half-open state.
`CircuitOpen`	Raised when a circuit is open in a `CircuitBreaker` (but shouldn't be).
`Critical`	Raised when a critical error is encountered by exception-handling middleware.
`EventValueError`	Raised when a party attempts to get the value an event of which the value is not set.
`ForbiddenOperation`	A forbidden operation was attempted on a password-protected queue.
`FutureCorrupted`	Raised after an internal party discovers an external party has set the result of a future whose result is for it to set only.
`GetPasswordMissing`	The get password was not passed to the get methods of a get-protected queue.
`GetPasswordRetrievalError`	Raised when `password_queue()` cannot find the get password from the closure variables.
`ItemsExhausted`	Raised when an asynchronous iterable runs out of items to take or collect.
`LockForceRequest`	Thrown to coroutines that acquire locks when a locksmith (inheriting from `locksmiths.LocksmithBase`) necessitates the lock be released.
`MaxIterationsError`	Raised when a function has reached the specified maximum iterations.
`PasswordError`	Raised when the wrong password is provided to the get or put methods of a password-protected queue.
`PasswordMissing`	Base class of `GetPasswordMissing` and `PutPasswordMissing`.
`PasswordQueueError`	Base class for all errors related to password-protected queues, as returned by `password_queue()`.
`PasswordRetrievalError`	Raised when `password_queue()` cannot find the password from the closure variables.
`PoolError`	Raised when a task pool encounters a miscellaneous error.
`PoolFull`	Raised when the task queue in a task pool is filled.
`PoolShutDown`	Raised when submissions are sent to a shutting down pool.
`PutPasswordMissing`	The put password was not passed to the put methods of a put-protected queue.
`PutPasswordRetrievalError`	Raised when `password_queue()` cannot find the put password from the closure variables.
`RateLimitExceeded`	Raised when a call to a function exceeds its rate limit and waiting is not allowed.
`StateCorrupted`	Raised when the module-internal state is corrupted, usually by a slip-up of some abstraction layer outside of this library, and an exception can be thrown. Should not be caught by users.
`VersionConversionError`	Base class for errors thrown when attempting to normalize an object to a version.
`VersionCorrupted`	Raised when internal state consistency checks of a version fail, indicating modifications by the user affected private state.
`VersionError`	Base class for all version-related errors.
`VersionNormalizerFault`	Wraps any errors thrown by a custom normalizer, intentionally or otherwise.
`VersionNormalizerMissing`	Raised when no normalizer is registered for an unrecognized object.
`VersionNormalizerTypeError`	Raised when a custom normalizer returns anything but an iterable of integers.
`VersionValueError`	Raised when an argument passed to the `VersionInfo` constructor is negative, for instance.
`WrongPassword`	Raised when the wrong password of the correct type is provided to the get or put methods of a password-protected queue.
`WrongPasswordType`	Raised when the password provided to the get or put methods of a password-protected queue is of the incorrect type.

Classes¶

`IgnoreErrors`	Context manager to suppress errors of the specified types and exit once they occur; works in both sync and async. More customizable than `contextlib.suppress`, because some exception classes can be excluded from the suppression.
`WarningToError`	Context manager to convert specific warnings to errors; works in both sync and async.

Functions¶

`exception_occurred`(...)	Whether the object is actually a sentinel for an exception, described above.
`potent_derive`(…)
`prepare_exception`(→ E)
`raise_exc`(…)	Programmatically raise an exception. The variadic `args` and `kwargs` are passed to the constructor of `exc_typ` in the first overload, and the remaining arguments are as in `potent_derive()`.
`unnest`(→ collections.abc.Generator[BaseException, ...)
`unnest_reverse`(...)	Basically the above but in reverse order, with rare edge cases. More memory- and time-efficient than unnest.
`unwrap_exc`(→ BaseException)	Recover the exception wrapped by `wrap_exc()`.
`wrap_exc`(→ asyncutils._internal.types.ExceptionWrapper)	Wrap an exception in a special proxy `wrapper`, such that `exception_occurred(wrapper)` returns `True`.

Module Contents¶

exception asyncutils.exceptions.BulkheadError[source]¶

Bases: RuntimeError

Raised when there is an error in bulkhead processing.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.BulkheadFull[source]¶

Bases: BulkheadError

Raised when a bulkhead is full and a party requests it to execute a coroutine.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.BulkheadShutDown[source]¶

Bases: BulkheadError

Raised when a bulkhead is being shut down and a party requests it to execute a coroutine.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.BusError[source]¶

Bases: RuntimeError

Raised when an operation on an EventBus fails.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.BusPublishingError(bus: asyncutils.channels.EventBus, mw: asyncutils._internal.types.Middleware, /)[source]¶

Bases: BusError

Raised when an event bus fails to publish an event.

Initialize self. See help(type(self)) for accurate signature.

property bus: asyncutils.channels.EventBus | None¶: May be None if the event bus was garbage-collected.

property middleware: asyncutils._internal.types.Middleware | None¶: May be None if the middleware was garbage-collected.

exception asyncutils.exceptions.BusShutDown[source]¶

Bases: BusError

Raised when subscription or publishing operations are called on an EventBus that is closing down.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.BusStatsError[source]¶

Bases: BusError

Raised when attempting to access publishing statistics on an EventBus whose statistics are not tracked.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.BusTimeout[source]¶

Bases: BusError

Raised when an EventBus takes too long to publish an event.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.CircuitBreakerError[source]¶

Bases: RuntimeError

Base class for circuit breaker errors.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.CircuitHalfOpen[source]¶

Bases: CircuitBreakerError

Raised when a circuit exceeds its maximum calls in the half-open state.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.CircuitOpen[source]¶

Bases: CircuitBreakerError

Raised when a circuit is open in a CircuitBreaker (but shouldn’t be).

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.Critical[E: (SystemExit, SystemError, KeyboardInterrupt)](exc: E)[source]¶

exception asyncutils.exceptions.Critical(exc: None = ...)

Bases: BaseException

Raised when a critical error is encountered by exception-handling middleware.

Initialize the critical exception with the exception being wrapped, or the currently handled exception if not passed.

property exc: E¶: The exception that occurred, determined by the raising scope by default.

exception asyncutils.exceptions.EventValueError[source]¶

Bases: ValueError

Raised when a party attempts to get the value an event of which the value is not set.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.ForbiddenOperation(op: str, *a: object)[source]¶

Bases: PasswordQueueError, TypeError

A forbidden operation was attempted on a password-protected queue.

Substitute in the arguments to the string (if any) to derive the name of the forbidden operation.

property op: str¶: A string representing the operation type.

exception asyncutils.exceptions.FutureCorrupted[source]¶

Bases: RuntimeError

Raised after an internal party discovers an external party has set the result of a future whose result is for it to set only.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.GetPasswordMissing[source]¶

Bases: PasswordMissing

The get password was not passed to the get methods of a get-protected queue.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.GetPasswordRetrievalError(from_: str)[source]¶

Bases: PasswordRetrievalError

Raised when password_queue() cannot find the get password from the closure variables.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.ItemsExhausted[source]¶

Bases: ValueError

Raised when an asynchronous iterable runs out of items to take or collect.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.LockForceRequest[T, L: asyncutils._internal.types.AsyncLockLike[Any], R: asyncutils.locksmiths.LocksmithBase](requester: R, fulfill: collections.abc.Callable[[Any], None], lock: L, info: T, /)[source]¶

Bases: BaseException

Thrown to coroutines that acquire locks when a locksmith (inheriting from locksmiths.LocksmithBase) necessitates the lock be released.

Initialize self. See help(type(self)) for accurate signature.

fulfill(answer: object, /) → None¶: Answer the request with answer, after presumably releasing the lock and performing error handling.

property info: T¶: The info passed to the force() method, or as returned by get_info(). Coerced to str as a note attached on this exception when traceback prints it.

property lock: L¶: The lock involved.

property requester: R¶: The locksmith that sent this error.

exception asyncutils.exceptions.MaxIterationsError[source]¶

Bases: RuntimeError

Raised when a function has reached the specified maximum iterations.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.PasswordError[T][source]¶

Bases: PasswordQueueError

Raised when the wrong password is provided to the get or put methods of a password-protected queue.

Initialize self. See help(type(self)) for accurate signature.

property qid: int¶: The memory address of the queue associated with the exception. Invalid if the queue has been garbage collected.

property wrongpass: T¶: The wrong password associated with the exception. May be None if the wrong password has been garbage collected.

exception asyncutils.exceptions.PasswordMissing[source]¶

Bases: PasswordQueueError, TypeError

Base class of GetPasswordMissing and PutPasswordMissing.

Initialize self. See help(type(self)) for accurate signature.

classmethod __init_subclass__(*, m: str = ...) → None[source]¶

exception asyncutils.exceptions.PasswordQueueError[source]¶

Bases: Exception

Base class for all errors related to password-protected queues, as returned by password_queue().

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.PasswordRetrievalError(from_: str)[source]¶

Bases: PasswordQueueError

Raised when password_queue() cannot find the password from the closure variables.

Initialize self. See help(type(self)) for accurate signature.

property from_: str¶: The specified name of the closure variable.

exception asyncutils.exceptions.PoolError[source]¶

Bases: RuntimeError

Raised when a task pool encounters a miscellaneous error.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.PoolFull[source]¶

Bases: PoolError

Raised when the task queue in a task pool is filled.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.PoolShutDown[source]¶

Bases: PoolError

Raised when submissions are sent to a shutting down pool.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.PutPasswordMissing[source]¶

Bases: PasswordMissing

The put password was not passed to the put methods of a put-protected queue.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.PutPasswordRetrievalError(from_: str)[source]¶

Bases: PasswordRetrievalError

Raised when password_queue() cannot find the put password from the closure variables.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.RateLimitExceeded[source]¶

Bases: RuntimeError

Raised when a call to a function exceeds its rate limit and waiting is not allowed.

Implementation detail

The initialization signature may change without notice, and is therefore not documented here.

Initialize self. See help(type(self)) for accurate signature.

async repeat_call() → Any[source]¶: Repeat the call to the function that exceeded the rate limit without the rate limiter.

exception asyncutils.exceptions.StateCorrupted(adjective: str, details: str, /)[source]¶

Bases: BaseException

Raised when the module-internal state is corrupted, usually by a slip-up of some abstraction layer outside of this library, and an exception can be thrown. Should not be caught by users.

Initialize self. See help(type(self)) for accurate signature.

property adjective: str¶

property details: str¶

exception asyncutils.exceptions.VersionConversionError[source]¶

Bases: VersionError

Base class for errors thrown when attempting to normalize an object to a version.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.VersionCorrupted(obj: asyncutils.version.VersionInfo, /)[source]¶

Bases: VersionError, RuntimeError

Raised when internal state consistency checks of a version fail, indicating modifications by the user affected private state.

Initialize self. See help(type(self)) for accurate signature.

__getattr__(name: str, /) → Any[source]¶

property obj: asyncutils.version.VersionInfo | None¶: The instance of VersionInfo having been corrupted. None if garbage collected.

exception asyncutils.exceptions.VersionError[source]¶

Bases: Exception

Base class for all version-related errors.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.VersionNormalizerFault[T]( normalizer: collections.abc.Callable[[T], collections.abc.Iterable[int]], obj: T, exc: BaseException, /, )[source]¶

Bases: VersionConversionError

Wraps any errors thrown by a custom normalizer, intentionally or otherwise.

Initialize self. See help(type(self)) for accurate signature.

property exc: BaseException | None¶: The exception thrown. None if garbage collected.

property normalizer: collections.abc.Callable[[T], collections.abc.Iterable[int]] | None¶: The normalizer at fault. None if garbage collected.

property obj: T | None¶: The handled object. None if garbage collected.

exception asyncutils.exceptions.VersionNormalizerMissing[T](obj: T, /)[source]¶

Bases: VersionConversionError, TypeError

Raised when no normalizer is registered for an unrecognized object.

Initialize self. See help(type(self)) for accurate signature.

property obj: T | None¶: The unrecognized object. None if garbage collected.

exception asyncutils.exceptions.VersionNormalizerTypeError[T](normalizer: collections.abc.Callable[[T], object], obj: T, /)[source]¶

Bases: VersionConversionError, TypeError

Raised when a custom normalizer returns anything but an iterable of integers.

Initialize self. See help(type(self)) for accurate signature.

property normalizer: collections.abc.Callable[[T], Any] | None¶: The normalizer at fault. None if garbage collected.

property obj: T | None¶: The object being normalized by the normalizer, for which a value of incorrect type was returned. None if garbage collected.

exception asyncutils.exceptions.VersionValueError[source]¶

Bases: VersionConversionError, ValueError

Raised when an argument passed to the VersionInfo constructor is negative, for instance.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.WrongPassword[T](queue: asyncutils._internal.types.QProt[Any, Any, Any], pwd: T, /)[source]¶

Bases: PasswordError[T], ValueError

Raised when the wrong password of the correct type is provided to the get or put methods of a password-protected queue.

Initialize self. See help(type(self)) for accurate signature.

exception asyncutils.exceptions.WrongPasswordType[T, R: type]( queue: asyncutils._internal.types.QProt[Any, Any, Any] | None, pwd: T, wrongtyp: type[T], correcttyp: R, /, )[source]¶

Bases: PasswordError[T], TypeError

Raised when the password provided to the get or put methods of a password-protected queue is of the incorrect type.

Initialize self. See help(type(self)) for accurate signature.

property correcttype: R | None¶: The correct password type associated with the exception. May be None if the wrong password type has been garbage collected, indicating its instances, and thus the password, and by extension the queue itself, have been destroyed.

property wrongtype: type[T] | None¶: The wrong password type associated with the exception. May be None if the wrong password type has been garbage collected.

class asyncutils.exceptions.IgnoreErrors( /, *exc: asyncutils._internal.types.ExcType, exclude: collections.abc.Iterable[asyncutils._internal.types.ExcType] = ..., )[source]¶

Context manager to suppress errors of the specified types and exit once they occur; works in both sync and async. More customizable than contextlib.suppress, because some exception classes can be excluded from the suppression.

The positional arguments are the exception classes to suppress within the context, and the iterable exclude will be consumed to build up but. All overlap is discarded.

async __aenter__() → Self[source]¶: Async context support.

async __aexit__(exc_typ: asyncutils._internal.types.ExcType, exc_val: BaseException, exc_tb: types.TracebackType, /) → bool[source]¶
async __aexit__(exc_typ: None, exc_val: None, exc_tb: None, /) → Literal[False]: Async context support.

__enter__() → Self[source]¶: Start suppressing the exceptions with types in exc, except those in but, and return the context manager instance.

__exit__(exc_typ: asyncutils._internal.types.ExcType, exc_val: BaseException, exc_tb: types.TracebackType, /) → bool[source]¶
__exit__(exc_typ: None, exc_val: None, exc_tb: None, /) → Literal[False]: Stop suppressing the specified exceptions.

combined( *others: Self | asyncutils._internal.types.ExcType | collections.abc.Iterable[Self] | collections.abc.Iterable[asyncutils._internal.types.ExcType], ) → Self[source]¶: Return a combined IgnoreErrors instance that ignores all the error types from itself and the others and respects their exclusions.

excluding(*others: asyncutils._internal.types.ExcType) → Self[source]¶: Return a new IgnoreErrors instance that ignores the error types from itself except those from the others.

property but: tuple[asyncutils._internal.types.ExcType, Ellipsis]¶: The subclasses of exception types in exc that are not ignored.

property exc: tuple[asyncutils._internal.types.ExcType, Ellipsis]¶: The exception types that are ignored.

class asyncutils.exceptions.WarningToError(/, *typs: type[Warning])[source]¶

Context manager to convert specific warnings to errors; works in both sync and async.

Positional arguments represent warning types to convert to their corresponding error types if they are to occur within the context.

async __aenter__() → None[source]¶: Async context support.

async __aexit__(exc_typ: asyncutils._internal.types.ExcType, exc_val: BaseException, exc_tb: types.TracebackType, /) → None[source]¶
async __aexit__(exc_typ: None, exc_val: None, exc_tb: None, /) → None: Async context support.

__enter__() → Self[source]¶: Note that an error is to be raised once one of the warning types is encountered within the context and return the context manager instance.

__exit__(exc_typ: asyncutils._internal.types.ExcType, exc_val: BaseException, exc_tb: types.TracebackType, /) → None[source]¶
__exit__(exc_typ: None, exc_val: None, exc_tb: None, /) → None: Stop raising errors for the warning types specified.

asyncutils.exceptions.exception_occurred(instance: object, /) → TypeGuard[asyncutils._internal.types.ExceptionWrapper]¶: Whether the object is actually a sentinel for an exception, described above.

asyncutils.exceptions.potent_derive( group: BaseExceptionGroup, /, *more: BaseException, ordered: bool = ..., predicate: collections.abc.Callable[[BaseException], bool] = ..., raise_critical: bool = ..., keep: asyncutils._internal.types.Exceptable = ..., filter_out: asyncutils._internal.types.Exceptable = ..., ack1: collections.abc.Callable[[BaseException], object] | None = ..., ack2: collections.abc.Callable[[BaseException], object] | None = ..., ack3: collections.abc.Callable[[BaseException], object] | None = ..., notes: collections.abc.Iterable[str] | None = ..., ) → BaseExceptionGroup[source]¶
asyncutils.exceptions.potent_derive( exc: asyncutils._internal.types.NonGroupExc, /, *more: BaseException, message: str, ordered: bool = ..., predicate: collections.abc.Callable[[BaseException], bool] = ..., raise_critical: bool = ..., keep: asyncutils._internal.types.Exceptable = ..., filter_out: asyncutils._internal.types.Exceptable = ..., ack1: collections.abc.Callable[[BaseException], object] | None = ..., ack2: collections.abc.Callable[[BaseException], object] | None = ..., ack3: collections.abc.Callable[[BaseException], object] | None = ..., notes: collections.abc.Iterable[str] | None = ..., traceback: types.TracebackType | None = ..., context: BaseException, cause: None = ..., suppress: bool = ..., ) → BaseExceptionGroup
asyncutils.exceptions.potent_derive( exc: asyncutils._internal.types.NonGroupExc, /, *more: BaseException, message: str, ordered: bool = ..., predicate: collections.abc.Callable[[BaseException], bool] = ..., raise_critical: bool = ..., keep: asyncutils._internal.types.Exceptable = ..., filter_out: asyncutils._internal.types.Exceptable = ..., ack1: collections.abc.Callable[[BaseException], object] | None = ..., ack2: collections.abc.Callable[[BaseException], object] | None = ..., ack3: collections.abc.Callable[[BaseException], object] | None = ..., notes: collections.abc.Iterable[str] | None = ..., traceback: types.TracebackType | None = ..., context: None = ..., cause: BaseException, suppress: bool = ..., ) → BaseExceptionGroup
asyncutils.exceptions.potent_derive( exc: asyncutils._internal.types.NonGroupExc, /, *more: BaseException, message: str, ordered: bool = ..., predicate: collections.abc.Callable[[BaseException], bool] = ..., raise_critical: bool = ..., keep: asyncutils._internal.types.Exceptable = ..., filter_out: asyncutils._internal.types.Exceptable = ..., ack1: collections.abc.Callable[[BaseException], object] | None = ..., ack2: collections.abc.Callable[[BaseException], object] | None = ..., ack3: collections.abc.Callable[[BaseException], object] | None = ..., notes: collections.abc.Iterable[str] | None = ..., traceback: types.TracebackType | None = ..., context: None = ..., cause: None = ..., suppress: bool = ..., ) → BaseExceptionGroup: Return an instance of BaseExceptionGroup, applying the specified filtering and combining the exceptions from other groups, flattening

when necessary.

ordered defaults to False, because that is more efficient.

The intersection of filter_out and keep, which are exception types (or tuples thereof), should be non-empty; they are redundant otherwise.

The acknowledgement parameters ack1, ack2 and ack3 are called on exceptions in the above intersection, exceptions that don’t pass the

predicate and exceptions that are not in keep respectively.

They must be callables that return fast (e.g. collecting into a list) to avoid slowing down the function.

If raise_critical is True, exit early once a critical exception (type of which is a member of CRITICAL) is encountered and

propagate it.

notes is attached to the group using add_note().

The suppress, context, cause and traceback parameters are used to add metadata to the result group; see prepare_exception().

They only have an effect when the first argument is not a group.

asyncutils.exceptions.prepare_exception[E: BaseException]( exc: E, /, *, traceback: types.TracebackType | None = ..., cause: BaseException | None = ..., context: BaseException | None = ..., suppress: bool = ..., notes: collections.abc.Iterable[str] = ..., ) → E[source]¶: Attach some info to the exception exc and return it.

notes is an iterable of strings that are added to the exception using add_note(). If a single string, it is treated as one note; to avoid this for some reason, convert the string to a tuple beforehand.

The parameter traceback corresponds to the attribute __traceback__, cause to __cause__, context to __context__ and suppress to __suppress_context__.

asyncutils.exceptions.raise_exc(

exc_typ: asyncutils._internal.types.ExcType,

/,

*args: object,

traceback: types.TracebackType | None = ...,

cause: BaseException | None = ...,

context: BaseException | None = ...,

suppress: bool = ...,

notes: collections.abc.Iterable[str] = ...,

**kwargs: object,

) → NoReturn[source]¶
asyncutils.exceptions.raise_exc( exc_val: BaseException, /, *, traceback: types.TracebackType | None = ..., cause: BaseException | None = ..., context: BaseException | None = ..., suppress: bool = ..., notes: collections.abc.Iterable[str] = ..., ) → NoReturn: Programmatically raise an exception. The variadic args and kwargs are passed to the constructor of exc_typ in the first overload, and the remaining arguments are as in potent_derive().

asyncutils.exceptions.unnest( group: BaseException, /, *more: BaseException, raise_critical: bool = ..., keep: asyncutils._internal.types.Exceptable = ..., filter_out: asyncutils._internal.types.Exceptable = ..., predicate: collections.abc.Callable[[BaseException], bool] = ..., ack1: collections.abc.Callable[[BaseException], object] | None = ..., ack2: collections.abc.Callable[[BaseException], object] | None = ..., ack3: collections.abc.Callable[[BaseException], object] | None = ..., ) → collections.abc.Generator[BaseException, BaseException][source]¶: Flatten exceptions that may be nested in BaseExceptionGroup’s, with priority for those just sent in.

Keyword arguments are as in potent_derive().

Tip

Use this only when you must preserve the order, and the faster unnest_reverse() otherwise.

asyncutils.exceptions.unnest_reverse( group: BaseException, /, *more: BaseException, raise_critical: bool = ..., keep: asyncutils._internal.types.Exceptable = ..., filter_out: asyncutils._internal.types.Exceptable = ..., predicate: collections.abc.Callable[[BaseException], bool] = ..., ack1: collections.abc.Callable[[BaseException], object] | None = ..., ack2: collections.abc.Callable[[BaseException], object] | None = ..., ack3: collections.abc.Callable[[BaseException], object] | None = ..., ) → collections.abc.Generator[BaseException, BaseException][source]¶: Basically the above but in reverse order, with rare edge cases. More memory- and time-efficient than unnest.

asyncutils.exceptions.unwrap_exc(instance: asyncutils._internal.types.ExceptionWrapper, /) → BaseException¶: Recover the exception wrapped by wrap_exc().

asyncutils.exceptions.wrap_exc(exc: BaseException, /) → asyncutils._internal.types.ExceptionWrapper¶: Wrap an exception in a special proxy wrapper, such that exception_occurred(wrapper) returns True.

asyncutils.exceptions.CRITICAL: Final[tuple[type[SystemExit], type[SystemError], type[KeyboardInterrupt]]]¶: The tuple (SystemExit, SystemError, KeyboardInterrupt), representing exceptions that should be allowed to propagate under most error handling mechanisms.

asyncutils.exceptions.ignore_all: Final[IgnoreErrors]¶: Instance of IgnoreErrors that ignores all errors; that is, IgnoreErrors(BaseException). Use with caution!

asyncutils.exceptions.ignore_noncritical: Final[IgnoreErrors]¶: Instance of IgnoreErrors that ignores all errors besides SystemExit, SystemError and KeyboardInterrupt. Equivalent to ignore_all.excluding(CRITICAL).

asyncutils.exceptions.ignore_stopaiteration: Final[IgnoreErrors]¶: Instance of IgnoreErrors that ignores StopAsyncIteration. Equivalent to IgnoreErrors(StopAsyncIteration).

asyncutils.exceptions.ignore_stopiteration: Final[IgnoreErrors]¶: Instance of IgnoreErrors that ignores StopIteration. Equivalent to IgnoreErrors(StopIteration).

asyncutils.exceptions.ignore_typeerrs: Final[IgnoreErrors]¶: Instance of IgnoreErrors that ignores TypeError. Equivalent to IgnoreErrors(TypeError).

asyncutils.exceptions.ignore_typical: Final[IgnoreErrors]¶: Instance of IgnoreErrors that ignores Exception and subclasses thereof. Equivalent to IgnoreErrors().

asyncutils.exceptions.ignore_valerrs: Final[IgnoreErrors]¶: Instance of IgnoreErrors that ignores ValueError. Equivalent to IgnoreErrors(ValueError).