Skip to content

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

InvalidArgumentError(reason: str)

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

InvalidCollectorPriorityError(key: ServiceKey, priority: object)

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

InvalidCollectorTagError(key: ServiceKey, attribute: str)

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

InvalidCookieError(name: str, reason: str)

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:

  • name (str) –

    The name the cookie was held under.

  • reason (str) –

    What is wrong with the cookie.

Record which cookie was refused and why.

InvalidMiddlewarePriorityError

InvalidMiddlewarePriorityError(key: tuple[type, Hashable | None], priority: object)

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

InvalidRateLimitError(reason: str)

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

InvalidTokenError(token: str)

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

RangedResponseBodyError(response: str, content_range: str)

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

ResponseAlreadyAMessageError(response: str)

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

StreamedResponseBodyError(response: str)

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

TooManyRequestsError(rate_limit: RateLimit, limiter: str, key: str, now: float)

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

UnknownCollectorError(name: str, available: tuple[str, ...])

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

UnknownRateLimiterError(limiter: str, available: tuple[str, ...])

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

UnsupportedConnectionError(connection: str)

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.