xtr_http_client_contracts.exception ¶
The errors the HTTP client contract names.
:class:HttpClientError is the root every one of them derives from,
including every error an implementation adds, so catching it catches anything
calling out can go wrong with, whichever client raised it.
Below it, two branches that mean different things. A
:class:TransportError — with :class:TransportTimeoutError for running out
of time — says there is no answer to look at. An :class:HttpError says
there is one and it is not a success: :class:RedirectionError for a 3xx
nobody followed, :class:ClientError for a 4xx, :class:ServerError for a
5xx, each carrying the response. :class:DecodingError is the third case:
the answer arrived whole and is not what it was being read as.
ClientError ¶
Bases: HttpError
A 4xx status: the server understood the request and would not serve it.
Retrying the same request unchanged gets the same answer, so this is the one range worth telling apart — a 401 asks for credentials, a 404 says there is nothing there, a 429 says to slow down.
DecodingError ¶
Bases: HttpClientError, ValueError
A body could not be turned into the shape that was asked for.
What :meth:HttpResponseInterface.to_array
<xtr_http_client_contracts.http_response_interface.HttpResponseInterface.to_array>
raises when the body is empty, is not JSON, or is JSON that is not an
object. The transfer succeeded, so this is about the payload, not the
connection.
Also a :class:ValueError, so code that already guards what it parses
with except ValueError keeps working without learning a new
exception.
Attributes:
-
reason(str) –What is wrong with the body, naming the URL it came from.
Record what is wrong with the body.
HttpClientError ¶
Bases: Exception
Base class for every error raised through the HTTP client contract.
Catch this to handle anything calling out can go wrong with, whichever client is behind the interface; catch a subclass to handle one cause. Every subclass carries what a caller needs as typed attributes and composes its message from them.
A server answering is not a cause: a request that came back with a 404 or
a 503 succeeded as a transfer, so request() returns the response and
nothing is raised until someone reads its content and asks to be told.
What raises on its own is the transfer failing, a body that will not
decode, and an option no client here understands.
HttpError ¶
Bases: HttpClientError
The status code says the request did not get what it asked for.
Never raised by making the request: a status is an answer, not a failure
of the transfer, so it reaches the caller as a response. This is raised
where the caller asks to be told about it —
:meth:HttpResponseInterface.get_content
<xtr_http_client_contracts.http_response_interface.HttpResponseInterface.get_content>
or :meth:HttpResponseInterface.to_array
<xtr_http_client_contracts.http_response_interface.HttpResponseInterface.to_array>
with throw.
Catch this to handle any unsuccessful status;
:class:RedirectionError <...redirection_error.RedirectionError>,
:class:ClientError <...client_error.ClientError> and
:class:ServerError <...server_error.ServerError> are the three ranges,
and they are siblings, so catching one leaves the others alone.
The response comes along because it is the only place the answer is left: the status code, the headers and the body, which is kept.
Attributes:
-
response(HttpResponseInterface) –The response that was answered with.
-
reason(str) –What the status means for this request, naming the code and the URL. The message is this, composed by whoever raised it — the body of an error document is the most useful thing to put there and reading it is awaited, which a constructor cannot do.
Record the response the status came on, and what it means.
InvalidArgumentError ¶
Bases: TransportError, ValueError
The request was refused before it was sent, for something it asked for.
An unknown option name, an option whose value the client cannot honour, a method or URL it cannot make a request with, or a body given both with the request and as an option. Nothing reached the network, so there is no response, and the same call with a corrected argument would go through.
Also a :class:ValueError, so code that already guards the arguments it
passes with except ValueError keeps working without learning a new
exception.
JsonError ¶
Bases: DecodingError
The body is JSON, but not the object :meth:HttpResponseInterface.to_array promises.
A JSON array, string, number or null where an object was asked for. The
body was read in full and parsed, so the failure is the shape of the payload,
not the transfer.
Also a :class:DecodingError, so code that already catches a body it could
not decode keeps catching this one.
RedirectionError ¶
Bases: HttpError
A 3xx status that was not followed.
Raised once max_redirects has been reached, or straight away when
following was turned off with max_redirects of zero or less — a
redirect that is followed never reaches the caller, since what comes
back is the response from the last hop.
Where the answer points is in the redirect_url entry of
:meth:HttpResponseInterface.get_info
<xtr_http_client_contracts.http_response_interface.HttpResponseInterface.get_info>.
ServerError ¶
Bases: HttpError
A 5xx status: the request may have been fine, the server was not.
The far side is at fault, so the same request may well succeed later. Nothing here retries; what to do about it is the caller's to decide.
TransportError ¶
Bases: HttpClientError
Nothing usable came back, or the request could never be made.
A host that will not resolve, a connection refused or reset, a body that stopped half way, a certificate the client would not accept — and the one case that never touches the network: an option the client does not support. A client reports that by raising rather than by ignoring it, so an option that was spelled wrong, or that this client cannot honour, cannot pass for one it quietly obeyed.
It is also what reading a response raises once it has been cancelled.
Attributes:
-
reason(str) –What went wrong, naming the URL it went wrong for.
Record what went wrong.
TransportTimeoutError ¶
Bases: TransportError, TimeoutError
The transfer went quiet for longer than it was allowed to.
Raised when the idle timeout passes with nothing coming in, when the
whole transfer outlasts max_duration, or when connecting outlasts
max_connect_duration.
Also a :class:TimeoutError, which is what the standard library raises
and what asyncio.timeout turns a deadline into, so code that already
gives up on a timeout keeps working without learning a new exception.