apiclient

Generic API client module.

exception spicerack.apiclient.APIClientError[source]

Bases: SpicerackError

General errors raised by this module.

exception spicerack.apiclient.APIClientResponseError(response: requests.models.Response, message: str = '') → None[source]

Bases: APIClientError

Exception class for failed responses to API requests.

Override parent constructor to add the requests's response object.

Parameters:

response (requests.models.Response) -- the requests's response object.
message (str, default: '') -- an optional exception message. A default message with the HTTP method, URL and status code will be prefixed before this message.

class spicerack.apiclient.APIClient(base_url: str, http_session: requests.sessions.Session, *, dry_run: bool = True) → None[source]

Bases: object

Generic API client class with DRY-RUN support. API-specific classes should derive from this one.

Initialize the instance.

Parameters:

base_url (str) -- the full base URL for the API. It must include the scheme and the domain and can include the API path prefix if there is one.
http_session (requests.sessions.Session) -- the requests's session to use to make the API calls.
dry_run (bool, default: True) -- whether this is a DRY-RUN.

request(method: str, uri: str, **kwargs: Any) → requests.models.Response[source]

Perform a request against the HTTP session with the provided HTTP method and data.

Parameters:

method (str) -- the HTTP method to use (e.g. "get").
uri (str) -- the relative URI to request.
**kwargs (typing.Any) -- arbitrary keyword arguments, to be passed to the requests library.

Raises:

spicerack.apiclient.APIClientError -- if the given uri does not start with a slash (/) or the request couldn't be performed.
spicerack.apiclient.APIClientResponseError -- if the response status code is not ok, between 400 and 600.

Return type:

requests.models.Response

Returns:

The API response object if not in DRY-RUN mode or the request is read-only (GET/HEAD/OPTIONS). When in DRY-RUN mode and a read-write request is made the API will not be called and a dummy HTTP 200 response will be returned.

property http_session: Session

Getter for the HTTP session request object to adjust it's configuration if needed.

Returns:: the pre-configured session.