or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdclient-management.mdconfiguration.mdexception-handling.mdhttp-clients.mdindex.mdresponse-handling.mdspec-loading.mdtesting-utilities.md
tile.json

tessl/pypi-bravado

Library for accessing Swagger-enabled APIs

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/bravado@12.0.x

To install, run

npx @tessl/cli install tessl/pypi-bravado@12.0.0

index.mddocs/

Bravado

Bravado is a Yelp-maintained fork of digium/swagger-py for use with OpenAPI Specification version 2.0 (previously known as Swagger). It provides a complete Python client library for REST APIs defined by OpenAPI specifications, aiming to be a replacement for code generation tools. The library supports both synchronous and asynchronous HTTP clients, handles various authentication methods, and automatically generates client methods from OpenAPI specification files.

Package Information

  • Package Name: bravado
  • Package Type: pypi
  • Language: Python
  • Installation: pip install bravado

Core Imports

from bravado.client import SwaggerClient

For HTTP clients:

from bravado.requests_client import RequestsClient
from bravado.fido_client import FidoClient  # Requires: pip install bravado[fido]

For authentication:

from bravado.requests_client import BasicAuthenticator, ApiKeyAuthenticator

Package version:

import bravado
print(bravado.version)  # '12.0.1'

Basic Usage

from bravado.client import SwaggerClient

# Create client from Swagger spec URL
client = SwaggerClient.from_url('http://petstore.swagger.io/v2/swagger.json')

# Execute API operations
pet = client.pet.getPetById(petId=1).response().result

With authentication:

from bravado.requests_client import RequestsClient
from bravado.client import SwaggerClient

# Configure HTTP client with authentication
http_client = RequestsClient()
http_client.set_basic_auth('api.example.com', 'username', 'password')

# Create authenticated client
client = SwaggerClient.from_url(
    'http://petstore.swagger.io/v2/swagger.json',
    http_client=http_client
)

# Execute operations
pet = client.pet.getPetById(petId=1).response().result

Architecture

Bravado follows a clean architecture with clear separation of concerns:

  • SwaggerClient: Main entry point that dynamically creates API methods from OpenAPI specs
  • HTTP Clients: Pluggable clients (RequestsClient for sync, FidoClient for async) handle transport
  • Authenticators: Modular authentication system supporting basic auth, API keys, and custom schemes
  • Response Processing: HttpFuture objects provide both sync/async response handling and fallback mechanisms
  • Exception Hierarchy: Comprehensive HTTP status code exceptions with proper error handling

This design enables bravado to work as a complete replacement for code generation tools while providing extensive customization options for production deployments.

Capabilities

Client Management

Core functionality for creating and managing Swagger clients from OpenAPI specifications. Includes dynamic operation generation, model handling, and spec loading from URLs or local files.

class SwaggerClient:
    def __init__(self, swagger_spec, also_return_response: bool = False): ...
    @classmethod
    def from_url(cls, spec_url: str, http_client=None, request_headers=None, config=None) -> 'SwaggerClient': ...
    @classmethod
    def from_spec(cls, spec_dict: dict, origin_url: str = None, http_client=None, config=None) -> 'SwaggerClient': ...
    def get_model(self, model_name: str): ...

Client Management

HTTP Clients

Synchronous and asynchronous HTTP client implementations with pluggable adapters. RequestsClient provides sync HTTP operations while FidoClient enables async/Twisted-based operations.

class RequestsClient(HttpClient):
    def __init__(self, ssl_verify: bool = True, ssl_cert=None, **kwargs): ...
    def request(self, request_params: dict, operation=None, request_config=None) -> HttpFuture: ...
    def set_basic_auth(self, host: str, username: str, password: str): ...
    def set_api_key(self, host: str, api_key: str, param_name: str = 'api_key', param_in: str = 'query'): ...

class FidoClient(HttpClient):
    def __init__(self, **kwargs): ...
    def request(self, request_params: dict, operation=None, request_config=None) -> HttpFuture: ...

HTTP Clients

Authentication

Modular authentication system supporting HTTP Basic authentication, API key authentication (query param or header), and extensible custom authentication schemes.

class BasicAuthenticator(Authenticator):
    def __init__(self, host: str, username: str, password: str): ...
    def apply(self, request): ...

class ApiKeyAuthenticator(Authenticator):
    def __init__(self, host: str, api_key: str, param_name: str = 'api_key', param_in: str = 'query'): ...
    def apply(self, request): ...

Authentication

Response Handling

Comprehensive response processing with metadata, timing information, fallback mechanisms, and both sync/async response patterns.

class HttpFuture:
    def __init__(self, future, response_adapter, operation=None, request_config=None): ...
    def response(self, timeout=None, fallback_result=None, exceptions_to_catch=None) -> BravadoResponse: ...
    def result(self, timeout=None): ...  # DEPRECATED
    def cancel(): ...

class BravadoResponse:
    result: Any
    metadata: BravadoResponseMetadata
    @property
    def incoming_response(self) -> IncomingResponse: ...

Response Handling

Exception Handling

Complete HTTP status code exception hierarchy with timeout and connection error handling. Provides specific exceptions for all HTTP status codes plus bravado-specific errors.

class HTTPError(IOError):
    status_code: int
    def __init__(self, response, message: str = None, swagger_result=None): ...

# Specific status code exceptions (300-511)
class HTTPBadRequest(HTTPClientError): status_code = 400
class HTTPUnauthorized(HTTPClientError): status_code = 401
class HTTPForbidden(HTTPClientError): status_code = 403
class HTTPNotFound(HTTPClientError): status_code = 404
class HTTPInternalServerError(HTTPServerError): status_code = 500
# ... and many more

class BravadoTimeoutError(TimeoutError): ...
class BravadoConnectionError(ConnectionError): ...

def make_http_exception(response, message: str = None, swagger_result=None) -> HTTPError: ...

Exception Handling

Configuration

Flexible configuration system for both global bravado settings and per-request options. Supports response metadata customization, timeout configuration, and callback mechanisms.

class BravadoConfig:
    also_return_response: bool
    disable_fallback_results: bool
    response_metadata_class: Type[BravadoResponseMetadata]
    sensitive_headers: list

class RequestConfig:
    also_return_response: bool
    force_fallback_result: bool
    response_callbacks: list
    connect_timeout: float
    timeout: float
    headers: dict
    use_msgpack: bool
    additional_properties: dict

def bravado_config_from_config_dict(config_dict: dict) -> BravadoConfig: ...

Configuration

Spec Loading

Utilities for loading OpenAPI/Swagger specifications from URLs, local files, and YAML/JSON sources with support for remote references and custom headers.

class Loader:
    def __init__(self, http_client, request_headers: dict = None): ...
    def load_spec(self, spec_url: str, base_url: str = None) -> dict: ...
    def load_yaml(self, text: str) -> dict: ...

def load_file(spec_file: str, http_client=None) -> dict: ...
def load_url(spec_url: str, http_client=None, base_url: str = None) -> dict: ...

Spec Loading

Testing Utilities

Mock objects and integration testing base classes for testing applications that use bravado. Includes response mocks, fallback result testing, and comprehensive integration test fixtures.

class BravadoResponseMock:
    def __init__(self, result, metadata=None): ...
    def __call__(self, timeout=None, fallback_result=None, exceptions_to_catch=None) -> 'BravadoResponseMock': ...
    @property
    def result: Any: ...
    @property
    def metadata: BravadoResponseMetadata: ...

class IntegrationTestingFixturesMixin:
    http_client: HttpClient
    http_client_type: Type[HttpClient]
    def swagger_client(self) -> SwaggerClient: ...

Testing Utilities