Requests implementation

HTTP client

Module containing a synchronous implementation of the HttpClient interface via the popular requests library.

class http_client.RequestsHttpResponse(response)

Requests implementation of the HttpResponse interface.

Parameters

response (requests.Response) – original requests.Response object

property path
property orig_response
property text
json(**kwargs)
Return type

Dict[str, Any]

class http_client.SessionHttpClient(base_url, auth_class, logger, **kwargs)

HTTP client for easy communication with the Data Stewardship Wizard API. It’s a synchronous implementation of a HttpClient interface via the Requests package.

Uses requests.Session in order to re-use HTTP connections and improve overall performance. Also transparently mediates the authentication process.

It is possible to add custom logic with before_request() and after_request() hooks.

All requests raise HttpError, so you don’t have to check every response for valid status code. Just assume it’s OK and catch the aforementioned exception somewhere. The UnexpectedAuthError is raised if some unexpected error occurs during the authentication process. This means the API responded in an unexpected way and something is wrong.

Keyword arguments
  • default_timeout:

    This timeout is used as default value when no timeout is specified within a request. You can pass one numeric value (applied for both the connect and read timeouts), tuple of numeric values to specify different connect and read timeouts or None to wait forever. Default: None.

  • session (requests.Session):

    If you want, you can configure your own session (instance of a requests.Session class) outside of this client and pass it as keyword argument.

  • headers: (Dict[str, str])

    Dict of all the HTTP headers you want to send with each requests.

  • enable_ssl (bool):

    If you set this flag to True, every request gets encrypted and the whole communication will be done over SSL/TLS. Default: True.

Parameters

  • base_url (str) – URL of the DSW API

  • auth_class (AuthBase) – class responsible for the authentication process

  • logger (logging.Logger) – logger object

before_request(*args, **kwargs)

This method can be overridden by users to provide custom logic before sending the request.

args and kwargs are the exact arguments that go into the request. This method must return the same, new or modified args and kwargs.

Returns

current, new or modified positional and keyword arguments for the request

Return type

Tuple[Tuple[Any, ..], Dict[str, Any]]

after_request(response)

This method can be overridden by users to provide custom logic after receiving the response.

response is the original response from the server. This method must return the same, new or modified response.

Parameters

response (http_client.RequestsHttpResponse) – original response from the server

Returns

current, new or modified response from the server

Return type

http_client.RequestsHttpResponse

head(path, **kwargs)

Sends a HEAD request. Returns RequestsHttpResponse object.

Parameters

  • path (str) – path for the new requests.Request object.

  • kwargs – Optional arguments that the request takes.

Raises

HttpError on HTTP status codes between 400 and 599 while authenticating or doing the request itself

Raises

UnexpectedAuthError on unexpected errors while authenticating

Return type

http_client.RequestsHttpResponse

options(path, **kwargs)

Sends an OPTIONS request. Returns RequestsHttpResponse object.

Parameters

  • path (str) – path for the new requests.Request object.

  • kwargs – Optional arguments that the request takes.

Raises

HttpError on HTTP status codes between 400 and 599 while authenticating or doing the request itself

Raises

UnexpectedAuthError on unexpected errors while authenticating

Return type

http_client.RequestsHttpResponse

get(path, **kwargs)

Sends a GET request. Returns RequestsHttpResponse object.

Parameters

  • path (str) – path for the new requests.Request object.

  • kwargs – Optional arguments that request takes.

Raises

HttpError on HTTP status codes between 400 and 599 while authenticating or doing the request itself

Raises

UnexpectedAuthError on unexpected errors while authenticating

Return type

http_client.RequestsHttpResponse

post(path, body=None, **kwargs)

Sends a POST request. Returns RequestsHttpResponse object.

Parameters

  • path (str) – path for the new requests.Request object.

  • body (Optional[Dict[str, Any]]) – (optional) json to send in the body of the requests.Request.

  • kwargs – Optional arguments that the request takes.

Raises

HttpError on HTTP status codes between 400 and 599 while authenticating or doing the request itself

Raises

UnexpectedAuthError on unexpected errors while authenticating

Return type

http_client.RequestsHttpResponse

put(path, body=None, **kwargs)

Sends a PUT request. Returns RequestsHttpResponse object.

Parameters

  • path (str) – path for the new requests.Request object.

  • body (Optional[Dict[str, Any]]) – (optional) json to send in the body of the requests.Request.

  • kwargs – Optional arguments that the request takes.

Raises

HttpError on HTTP status codes between 400 and 599 while authenticating or doing the request itself

Raises

UnexpectedAuthError on unexpected errors while authenticating

Return type

http_client.RequestsHttpResponse

delete(path, **kwargs)

Sends a DELETE request. Returns RequestsHttpResponse object.

Parameters

  • path (str) – path for the new requests.Request object.

  • kwargs – Optional arguments that the request takes.

Raises

HttpError on HTTP status codes between 400 and 599 while authenticating or doing the request itself

Raises

UnexpectedAuthError on unexpected errors while authenticating

Return type

http_client.RequestsHttpResponse

Auth

Module with classes procuring the whole authentication process.

class auth.TokenRetrievalStrategy(auth_url, credentials)

Abstract class for strategy on how to retrieve auth token from the server.

Every subclass has to implement the get_new_token() method.

Parameters

  • auth_url (str) – URL of the authentication endpoint

  • credentials (Dict[str, str]) – dict containing keys email and password

get_new_token()

Make a POST request to the authentication URL and obtain new auth token.

Raises

requests.HTTPError on HTTP status codes between 400 and 599

Raises

UnexpectedAuthError on missing token in HTTP response body

Returns

authentication token to be passed with every request

Return type

str

class auth.BodyTokenRetrievalStrategy(auth_url, credentials)

This strategy knows how to retrieve an authentication token contained in the body of the HTTP response from the server.

Parameters

  • auth_url (str) – URL of the authentication endpoint

  • credentials (Dict[str, str]) – dict containing keys email and password

get_new_token()

Make a POST request to the authentication URL and obtain new auth token.

Raises

requests.HTTPError on HTTP status codes between 400 and 599

Raises

UnexpectedAuthError on missing token in HTTP response body

Returns

authentication token to be passed with every request

Return type

str

class auth.BearerAuth(token)

Subclass of requests.AuthBase, defining how to authenticate with every request via the Bearer authentication protocol defined in RFC 6750.

Parameters

token (str) – Authentication token obtained from the auth endpoint

class auth.JWTBearerAuth(token_retrieval_strategy)

Subclass of requests.AuthBase, defining how to authenticate with every request using JSON Web Tokens defined in RFC 7519.

Parameters

token_retrieval_strategy (TokenRetrievalStrategy) – means of authentication

static token_expiration(jwt_token)

Return expiration datetime of given jwt_token.

Parameters

jwt_token – string representation of a JWT token (encoded)

Raises

UnexpectedAuthError if jwt_token is not a valid JWT token

Returns

datetime of expiration

Return type

datetime.datetime