bravado Package

bravado Package

client Module

The SwaggerClient provides an interface for making API calls based on a swagger spec, and returns responses of python objects which build from the API response.

Structure Diagram:

+---------------------+
|                     |
|    SwaggerClient    |
|                     |
+------+--------------+
       |
       |  has many
       |
+------v--------------+
|                     |
|     Resource        +------------------+
|                     |                  |
+------+--------------+         has many |
       |                                 |
       |  has many                       |
       |                                 |
+------v--------------+           +------v--------------+
|                     |           |                     |
|     Operation       |           |    SwaggerModel     |
|                     |           |                     |
+------+--------------+           +---------------------+
       |
       |  uses
       |
+------v--------------+
|                     |
|     HttpClient      |
|                     |
+---------------------+

To get a client

client = bravado.client.SwaggerClient.from_url(swagger_spec_url)
class bravado.client.CallableOperation(operation)

Bases: object

Wraps an operation to make it callable and provides a docstring. Calling the operation uses the configured http_client.

class bravado.client.ResourceDecorator(resource)

Bases: object

Wraps bravado_core.resource.Resource so that accesses to contained operations can be instrumented.

class bravado.client.SwaggerClient(swagger_spec)

Bases: object

A client for accessing a Swagger-documented RESTful service.

classmethod from_spec(spec_dict, origin_url=None, http_client=None, config=None)

Build a SwaggerClient from a Swagger spec in dict form.

Parameters:
  • spec_dict – a dict with a Swagger spec in json-like form
  • origin_url (str) – the url used to retrieve the spec_dict
  • config – Configuration dict - see spec.CONFIG_DEFAULTS
Return type:

bravado_core.spec.Spec

classmethod from_url(spec_url, http_client=None, request_headers=None, config=None)

Build a SwaggerClient from a url to the Swagger specification for a RESTful API.

Parameters:
  • spec_url (str) – url pointing at the swagger API specification
  • http_client (bravado.http_client.HttpClient) – an HTTP client used to perform requests
  • request_headers (dict) – Headers to pass with http requests
  • config – Config dict for bravado and bravado_core. See CONFIG_DEFAULTS in :module:`bravado_core.spec`. See CONFIG_DEFAULTS in :module:`bravado.client`.
Return type:

bravado_core.spec.Spec

get_model(model_name)
bravado.client.construct_params(operation, request, op_kwargs)

Given the parameters passed to the operation invocation, validates and marshals the parameters into the provided request dict.

Parameters:op_kwargs – the kwargs passed to the operation invocation
Raises:SwaggerMappingError on extra parameters or when a required parameter is not supplied.
bravado.client.construct_request(operation, request_options, **op_kwargs)

Construct the outgoing request dict.

Parameters:
  • request_options – _request_options passed into the operation invocation.
  • op_kwargs – parameter name/value pairs to passed to the invocation of the operation.
Returns:

request in dict form

bravado.client.inject_headers_for_remote_refs(request_callable, request_headers)

Inject request_headers only when the request is to retrieve the remote refs in the swagger spec (vs being a request for a service call).

Parameters:
  • request_callable – method on http_client to make a http request
  • request_headers – headers to inject when retrieving remote refs

requests_client Module

class bravado.requests_client.ApiKeyAuthenticator(host, api_key, param_name=u'api_key', param_in=u'query')

Bases: bravado.requests_client.Authenticator

?api_key authenticator.

This authenticator adds an API key via query parameter or header.

Parameters:
  • host – Host to authenticate for.
  • api_key – API key.
  • param_name – Query parameter specifying the API key.
  • param_in – How to send the API key. Can be ‘query’ or ‘header’.
apply(request)

Apply authentication to a request.

Parameters:request – Request to add authentication information to.
class bravado.requests_client.Authenticator(host)

Bases: object

Authenticates requests.

Parameters:host – Host to authenticate for.
apply(request)

Apply authentication to a request.

Parameters:request – Request to add authentication information to.
matches(url)

Returns true if this authenticator applies to the given url.

Parameters:url – URL to check.
Returns:True if matches host, port and scheme, False otherwise.
class bravado.requests_client.BasicAuthenticator(host, username, password)

Bases: bravado.requests_client.Authenticator

HTTP Basic authenticator.

Parameters:
  • host – Host to authenticate for.
  • username – Username.
  • password – Password
apply(request)

Apply authentication to a request.

Parameters:request – Request to add authentication information to.
class bravado.requests_client.RequestsClient

Bases: bravado.http_client.HttpClient

Synchronous HTTP client implementation.

apply_authentication(request)
authenticated_request(request_params)
request(request_params, operation=None, response_callbacks=None, also_return_response=False)
Parameters:
  • request_params (dict) – complete request data.
  • operation (bravado_core.operation.Operation) – operation that this http request is for. Defaults to None - in which case, we’re obviously just retrieving a Swagger Spec.
  • response_callbacks – List of callables to post-process the incoming response. Expects args incoming_response and operation.
  • also_return_response – Consult the constructor documentation for bravado.http_future.HttpFuture.
Returns:

HTTP Future object

Return type:

class:bravado_core.http_future.HttpFuture

static separate_params(request_params)

Splits the passed in dict of request_params into two buckets.

  • sanitized_params are valid kwargs for constructing a requests.Request(..)
  • misc_options are things like timeouts which can’t be communicated to the Requests library via the requests.Request(…) constructor.
Parameters:request_params – kitchen sink of request params. Treated as a read-only dict.
Returns:tuple(sanitized_params, misc_options)
set_api_key(host, api_key, param_name=u'api_key', param_in=u'query')
set_basic_auth(host, username, password)
class bravado.requests_client.RequestsFutureAdapter(session, request, misc_options)

Bases: bravado.http_future.FutureAdapter

Mimics a concurrent.futures.Future for the purposes of making HTTP calls with the Requests library in a future-y sort of way.

build_timeout(result_timeout)

Build the appropriate timeout object to pass to session.send(…) based on connect_timeout, the timeout passed to the service call, and the timeout passed to the result call.

Parameters:result_timeout – timeout that was passed into future.result(..)
Returns:timeout
Return type:float or tuple(connect_timeout, timeout)
result(timeout=None)

Blocking call to wait for API response

Parameters:timeout (float) – timeout in seconds to wait for response. Defaults to None to wait indefinitely.
Returns:raw response from the server
Return type:dict
class bravado.requests_client.RequestsResponseAdapter(requests_lib_response)

Bases: bravado_core.response.IncomingResponse

Wraps a requests.models.Response object to provide a uniform interface to the response innards.

headers
json(**kwargs)
Returns:response content in a json-like form
Return type:int, float, double, string, unicode, list, dict
reason
status_code
text

fido_client Module

http_future Module

class bravado.http_future.FutureAdapter

Bases: object

Mimics a concurrent.futures.Future regardless of which client is performing the request, whether it is synchronous or actually asynchronous.

This adapter must be implemented by all bravado clients such as FidoClient or RequestsClient to wrap the object returned by their ‘request’ method.

result(timeout=None)

Must implement a result method which blocks on result retrieval.

Parameters:timeout – maximum time to wait on result retrieval. Defaults to None which means blocking undefinitely.
class bravado.http_future.HttpFuture(future, response_adapter, operation=None, response_callbacks=None, also_return_response=False)

Bases: object

Wrapper for a FutureAdapter that returns an HTTP response.

Parameters:
  • future – The future object to wrap.
  • response_adapter (type that is a subclass of bravado_core.response.IncomingResponse.) – Adapter type which exposes the innards of the HTTP response in a non-http client specific way.
  • response_callbacks – See bravado.client.REQUEST_OPTIONS_DEFAULTS
  • also_return_response – Determines if the incoming http response is included as part of the return value from calling HttpFuture.result(). When False, only the swagger result is returned. When True, the tuple(swagger result, http response) is returned. This is useful if you want access to additional data that is not accessible from the swagger result. e.g. http headers, http response code, etc. Defaults to False for backwards compatibility.
result(timeout=None)

Blocking call to wait for the HTTP response.

Parameters:timeout (float) – Number of seconds to wait for a response. Defaults to None which means wait indefinitely.
Returns:Depends on the value of also_return_response sent in to the constructor.
bravado.http_future.raise_on_expected(http_response)

Raise an HTTPError if the response is non-2XX and matches a response in the swagger spec.

Parameters:http_responsebravado_core.response.IncomingResponse
Raises:HTTPError
bravado.http_future.raise_on_unexpected(http_response)

Raise an HTTPError if the response is 5XX.

Parameters:http_responsebravado_core.response.IncomingResponse
Raises:HTTPError
bravado.http_future.unmarshal_response(incoming_response, operation, response_callbacks=None)

So the http_client is finished with its part of processing the response. This hands the response over to bravado_core for validation and unmarshalling and then runs any response callbacks. On success, the swagger_result is available as incoming_response.swagger_result.

Raises:

HTTPError - On 5XX status code, the HTTPError has minimal information. - On non-2XX status code with no matching response, the HTTPError

contains a detailed error message.

  • On non-2XX status code with a matching response, the HTTPError
    contains the return value.

exception Module

exception bravado.exception.HTTPBadGateway(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPServerError

status_code = 502
exception bravado.exception.HTTPBadRequest(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 400
exception bravado.exception.HTTPClientError(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPError

4xx responses.

exception bravado.exception.HTTPConflict(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 409
exception bravado.exception.HTTPError(response, message=None, swagger_result=None)

Bases: exceptions.IOError

Unified HTTPError used across all http_client implementations.

class bravado.exception.HTTPErrorType

Bases: type

A metaclass for registering HTTPError subclasses.

exception bravado.exception.HTTPExpectationFailed(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 417
exception bravado.exception.HTTPFailedDependency(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 424
exception bravado.exception.HTTPForbidden(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 403
exception bravado.exception.HTTPGatewayTimeout(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPServerError

status_code = 504
exception bravado.exception.HTTPGone(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 410
exception bravado.exception.HTTPHTTPVersionNotSupported(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPServerError

status_code = 505
exception bravado.exception.HTTPInsufficientStorage(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPServerError

status_code = 507
exception bravado.exception.HTTPInternalServerError(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPServerError

status_code = 500
exception bravado.exception.HTTPLengthRequired(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 411
exception bravado.exception.HTTPLocked(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 423
exception bravado.exception.HTTPLoopDetected(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPServerError

status_code = 508
exception bravado.exception.HTTPMethodNotAllowed(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 405
exception bravado.exception.HTTPMisdirectedRequest(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 421
exception bravado.exception.HTTPNetworkAuthenticationRequired(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPServerError

status_code = 511
exception bravado.exception.HTTPNotAcceptable(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 406
exception bravado.exception.HTTPNotExtended(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPServerError

status_code = 510
exception bravado.exception.HTTPNotFound(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 404
exception bravado.exception.HTTPNotImplemented(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPServerError

status_code = 501
exception bravado.exception.HTTPPayloadTooLarge(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 413
exception bravado.exception.HTTPPaymentRequired(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 402
exception bravado.exception.HTTPPreconditionFailed(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 412
exception bravado.exception.HTTPPreconditionRequired(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 428
exception bravado.exception.HTTPProxyAuthenticationRequired(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 407
exception bravado.exception.HTTPRangeNotSatisfiable(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 416
exception bravado.exception.HTTPRequestHeaderFieldsTooLarge(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 431
exception bravado.exception.HTTPRequestTimeout(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 408
exception bravado.exception.HTTPServerError(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPError

5xx responses.

exception bravado.exception.HTTPServiceUnavailable(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPServerError

status_code = 503
exception bravado.exception.HTTPTooManyRequests(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 429
exception bravado.exception.HTTPURITooLong(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 414
exception bravado.exception.HTTPUnauthorized(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 401
exception bravado.exception.HTTPUnavailableForLegalReasons(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 451
exception bravado.exception.HTTPUnprocessableEntity(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 422
exception bravado.exception.HTTPUnsupportedMediaType(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 415
exception bravado.exception.HTTPUpgradeRequired(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPClientError

status_code = 426
exception bravado.exception.HTTPVariantAlsoNegotiates(response, message=None, swagger_result=None)

Bases: bravado.exception.HTTPServerError

status_code = 506
bravado.exception.make_http_exception(response, message=None, swagger_result=None)

Return an HTTP exception class based on the response. If a specific class doesn’t exist for a particular HTTP status code, a more general HTTPError class will be returned. :type response: bravado_core.response.IncomingResponse :param message: Optional string message :param swagger_result: If the response for this HTTPError is

documented in the swagger spec, then this should be the result value of the response.
Returns:An HTTP exception class that can be raised