xtr_http_kernel.exception ¶
Every error this library raises.
All of them derive from :class:HttpKernelError, so one except catches
anything the request lifecycle can go wrong with, and a narrower one handles
one cause. Each carries the data a caller needs as typed attributes rather
than forcing a message to be parsed.
HttpKernelError ¶
Bases: Exception
Base class for every error raised by this library.
Catch this to handle anything turning a request into a response can go wrong with; catch a subclass to handle one cause. Every subclass carries the data a caller needs as typed attributes and composes its own message from them.
InvalidArgumentError ¶
Bases: HttpKernelError, ValueError
The lifecycle or its configuration was given a value it cannot work with.
Also a :class:ValueError, so code that already guards its configuration
with except ValueError keeps working without learning a new exception.
Attributes:
-
reason(str) –What is wrong with the value.
Record what is wrong with the value.
InvalidCollectorPriorityError ¶
Bases: HttpKernelError, TypeError
A data collector tag's priority is not an integer.
The priority orders the panels of a profile, so a value that cannot be
compared with the others fails the build rather than a profile later.
Also a :class:TypeError.
Attributes:
-
key(ServiceKey) –The tagged definition.
-
priority(object) –The value it carried.
Record the definition and the priority it carried.
InvalidCollectorTagError ¶
Bases: HttpKernelError, ValueError
A data collector tag lacks a name or a template, or one is not a string.
The name is what a profile keeps the collector's data under and the
template is what shows it, so neither can be left for later. Also a
:class:ValueError.
Attributes:
-
key(ServiceKey) –The tagged definition.
-
attribute(str) –The attribute that is missing or not a string.
Record the definition and the attribute it lacks.
InvalidCookieError ¶
Bases: HttpKernelError, ValueError
A cookie of a request message is not one a Cookie header can carry.
The cookies of a message are a plain mapping, which nothing checked on
the way in; the header they are written into is read back by splitting it
apart again. So a name or a value the cookie grammar refuses would either
break the header or come back as something else — a value holding ;
reads back as further cookies of its own, one of them possibly replacing
a cookie that was really sent. The cookie is refused here instead, where
the name is still known.
Also a :class:ValueError, so code that already guards what it builds
with except ValueError keeps working without learning a new
exception.
Attributes:
Record which cookie was refused and why.
InvalidMiddlewarePriorityError ¶
Bases: HttpKernelError
A http_kernel.middleware tag's priority attribute is not an integer.
Raised while the kernel is built, so a misdeclared bundle fails at startup rather than serving an unordered chain.
Attributes:
-
key(tuple[type, Hashable | None]) –The tagged service's
(type, qualifier)key. -
priority(object) –What the tag carried instead of an integer.
Record the offending service key and what its tag carried.
InvalidRateLimitError ¶
Bases: HttpKernelError, ValueError
A route's rate limit was declared in a way it cannot be applied.
Raised where it is declared — fewer than one token, a router that already has routes, a key that is not a string — rather than silently limiting nothing.
Attributes:
-
reason(str) –What is wrong with the declaration.
Record what is wrong with the declaration.
InvalidTokenError ¶
Bases: HttpKernelError, ValueError
A profile token holds characters a profile is never stored under.
A token names a file under the profiler's folder, so anything but letters,
digits, _ and - is refused before a path is built from it — a
.. reaching outside the folder included. Also a :class:ValueError.
Attributes:
-
token(str) –The token that was refused.
Record the refused token.
RangedResponseBodyError ¶
Bases: HttpKernelError
The response being built into a message declares a Content-Range.
The header says the body is one part of the file; which part that is, and the reading of it, belong to where the response is sent. A message built here would carry the whole file under a header saying it carries a part of it — the two halves of the message contradicting each other, which is worse than either alone. Build the message from the range being sent instead.
Attributes:
-
response(str) –The kind of response whose body could not be read, as the name of its class.
-
content_range(str) –The range the response declares, as the header carries it.
Record the kind of response that was refused and the range it declares.
ResponseAlreadyAMessageError ¶
Bases: HttpKernelError
The response being built into a message already is one.
The bridge's own response is both what the framework sends and a message
in its own right, so converting it is asking to turn a message into the
same message: there is nothing to do but read its body, which is awaited
and so cannot be read here. Use the response as the message it already is —
await response.get_body().get_contents() for its body — rather than
handing it over to be converted.
Attributes:
-
response(str) –The kind of response that already is a message, as the name of its class.
Record the kind of response that already is a message.
StreamedResponseBodyError ¶
Bases: HttpKernelError
The response being built into a message streams its body.
A streamed body is an iterator the server drains once as it sends it: reading it here would consume it and leave the response with nothing to send, and handing over a message with an empty body instead would pass emptiness off as the answer. Build the message from the content the response was given, and stream that.
Attributes:
-
response(str) –The kind of response whose body could not be read, as the name of its class.
Record the kind of response whose body could not be read.
TooManyRequestsError ¶
Bases: HttpKernelError, HTTPException
A route turned a request away because a rate limit refused it.
Also the framework's own HTTP exception, so the application answers it
as it answers any other: 429 Too Many Requests with a Retry-After
header, reshaped by an exception handler registered for this class when
the application wants another body.
Attributes:
-
rate_limit(RateLimit) –The limit that refused the request.
-
limiter(str) –The configured limiter's name.
-
key(str) –The key the request was counted under.
-
retry_after(int) –Whole seconds until the request would be accepted.
Record the refused limit, counting the wait from now.
UnknownCollectorError ¶
Bases: HttpKernelError, LookupError
A profile was asked for data no collector of it gathered.
Also a :class:LookupError, as a missing key is.
Attributes:
-
name(str) –The collector asked for.
-
available(tuple[str, ...]) –The collectors the profile holds.
Record the collector asked for and the ones there are.
UnknownRateLimiterError ¶
Bases: HttpKernelError, LookupError
A route names a rate limiter nobody configured.
Raised when the first request reaches the route, since routes are declared before any kernel is built. A limiter is configured in the rate limiter bundle's configuration, under the name the route uses.
Attributes:
-
limiter(str) –The name the route used.
-
available(tuple[str, ...]) –The names the application configured.
Record the unknown name and the ones that exist.
UnsupportedConnectionError ¶
Bases: HttpKernelError
Something asked for the request as a message while a socket was served.
An HTTP message describes a request and the response it earns, so it can
only be built from an HTTP request. A WebSocket connection has neither a
method nor a body to read once, and the frames it exchanges are not
messages of this kind; a route serving one takes the framework's own
websocket parameter instead.
Attributes:
-
connection(str) –What the connection being served is, as the server named it —
"websocket"where a socket was served.
Record what was being served instead of an HTTP request.