Click a link to jump to the indicated section.
class
bluecat_libraries.http_client.Client
(target)
Bases: object
An HTTP client with some utilities to make creating service clients easier. The class implements the necessary methods to act as a context manager.
Parameters | Description |
---|---|
target (Instance) |
A definition of a target service. |
New in version 20.6.1.
_handle_nonerror_response(response)
Handle a response that’s considered to be a success (non error) by
is_error_response
. The standard implementation simply returns the
response object.
Parameters | Description |
---|---|
response (Response) |
Object representing the HTTP response. |
Return type: Any
Returns: The result of the handled response.
This method is not intended to be called by users of the class. Derived classes may overwrite this method and customize the behaviour, e.g., parse the response body into a typed structure.
New in version 23.1.0.
_handle_request_exc(exc)
Handle the exception that is raised when the request is attempted.
The standard implementation raises a GeneralError
from the passed
exception.
Parameters | Description |
---|---|
exc (Exception) |
The exception raised when the HTTP request is made. |
Raises:
GeneralError – When the request to the target service fails.
It is expected that this method raises an exception.
This method is not intended to be called by users of the class. Derived classes may overwrite this method and customize the behaviour, e.g., change the exception type and/or the message.
Return type: None
New in version 23.1.0.
close()
Release any allocated resources, e.g., an internal session.
handle_error_response(response)
Handle a response that’s considered to be an error (based on the HTTP status code). The standard implementation raises an exception. Derived classes may overwrite it to provide custom handling.
Parameters | Description |
---|---|
response (requests.Response) |
Object representing the HTTP response. |
http_delete(url, params=None, data=None, json=None, expected_status_codes=None, **kwargs)
Perform an HTTP DELETE request based on the provided parameters. See http_request for details.
Return type: Response
http_get(url, params=None, expected_status_codes=None, **kwargs)
Perform an HTTP GET request based on the provided parameters. See http_request for details.
If expected_status_codes is not specified, it defaults to (200, ). 200 is the HTTP status code for successful response OK.
Return type: Response
http_patch(url, params=None, data=None, json=None, expected_status_codes=None, **kwargs)
Perform an HTTP PATCH request based on the provided parameters. See http_request for details.
Return type: Response
http_post(url, params=None, data=None, json=None, expected_status_codes=None, **kwargs)
Perform an HTTP POST request based on the provided parameters. See http_request for details.
Return type: Response
http_put(url, params=None, data=None, json=None, expected_status_codes=None, **kwargs)
Perform an HTTP PUT request based on the provided parameters. See http_request for details.
Return type: Response
http_request(method, url, params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None, json=None, expected_status_codes=None)
Perform an HTTP request based on the provided parameters. It is done
as part of the internally maintained session, i.e. using the set
authorization. The majority of the method’s parameters correspond to
their namesakes in requests.Session.request()
. However, this
class additionally processes the response. It uses
is_error_response()
and handle_error_response()
to
detect and handle error responses. That approach allows derived classes
to customize the behaviour. Additionally, it checks the HTTP status
code against provided expected_status_codes and raises an exception.
Parameters | Description |
---|---|
method (str) |
HTTP method to be used. |
url (str) |
URL to be used for the request. |
params (dict, optional) |
Query parameters to be passed in the request. |
data (dict, list[tuple], bytes, or a file-like object, optional) |
Value to be sent in the body of the request. |
headers (dict, optional) |
HTTP Headers to be sent with the request. |
cookies (dict or CookieJar object, optional) |
Cookies to be sent with the request. |
files (dict, optional) |
File-like objects for multipart encoding upload. |
auth (tuple or callable, optional) |
Object to handle HTTP Authentication. |
timeout (float or tuple, optional) |
How long to wait to receive data before giving up. If given as a tuple, it is used as (connect, read) timeouts. |
allow_redirects (bool, optional) |
Whether to allow redirects. Defaults to |
proxies (dict, optional) |
Mapping of protocol or protocol and hostname to a URL of a proxy to be used. |
hooks (dict, optional) |
Hooks to be called upon events. |
stream (bool, optional) |
Whether to immediately read the response content.
Defaults to |
verify (bool or str, optional) |
Whether to verify the server’s TLS certificate. If a
string is passed, it is treated as a path to a CA bundle to be
used. Defaults to |
cert (str or tuple, optional) |
Path to a SSL client certificate file (.pem). If the certificate has a key, it can be provides as the second item in a tuple, with the first item being the path to the certificate file. |
json (object, optional) |
Object to be sent as JSON in the body of the request. |
expected_status_codes (iterable[int], optional) |
HTTP status codes that are acceptable as
a status code of the HTTP response. If the received code does not
match the passed values, an |
Returns: Object representing the HTTP response received to the performed request.
Return type: requests.Response
verify
is None
, the value of verify
from
the underlying session object is used explicitly.
property
is_authenticated
Determine whether the authentication necessary to communicate with the target service is set.
Return type: bool
is_error_response(response)
Determine whether a response is an error response.
This method exists to allow derived classes to customize the behaviour.
Parameters | Description |
---|---|
response (requests.Response) |
Object representing the HTTP response. |
Returns: Whether the response conveys an error.
Return type: bool