Internal client - BlueCat Python Library - 24.2

BlueCat Python Library Guide

Locale
English
Product name
BlueCat Python Library
Version
24.2

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.

Note:

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.

Note:

It is expected that this method raises an exception.

Note:

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 True.

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 False.

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 True.

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 UnexpectedResponse is raised. If left empty, the status code validation is not performed.

Returns: Object representing the HTTP response received to the performed request.

Return type: requests.Response

Note: Changed in version 23.1.0: If parameter 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