0
# Bravado
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: bravado
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install bravado`
10

11
## Core Imports
12

13
```python
14
from bravado.client import SwaggerClient
15
```
16

17
For HTTP clients:
18

19
```python
20
from bravado.requests_client import RequestsClient
21
from bravado.fido_client import FidoClient  # Requires: pip install bravado[fido]
22
```
23

24
For authentication:
25

26
```python
27
from bravado.requests_client import BasicAuthenticator, ApiKeyAuthenticator
28
```
29

30
Package version:
31

32
```python
33
import bravado
34
print(bravado.version)  # '12.0.1'
35
```
36

37
## Basic Usage
38

39
```python
40
from bravado.client import SwaggerClient
41

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

45
# Execute API operations
46
pet = client.pet.getPetById(petId=1).response().result
47
```
48

49
With authentication:
50

51
```python
52
from bravado.requests_client import RequestsClient
53
from bravado.client import SwaggerClient
54

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

59
# Create authenticated client
60
client = SwaggerClient.from_url(
61
    'http://petstore.swagger.io/v2/swagger.json',
62
    http_client=http_client
63
)
64

65
# Execute operations
66
pet = client.pet.getPetById(petId=1).response().result
67
```
68

69
## Architecture
70

71
Bravado follows a clean architecture with clear separation of concerns:
72

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

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

81
## Capabilities
82

83
### Client Management
84

85
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.
86

87
```python { .api }
88
class SwaggerClient:
89
    def __init__(self, swagger_spec, also_return_response: bool = False): ...
90
    @classmethod
91
    def from_url(cls, spec_url: str, http_client=None, request_headers=None, config=None) -> 'SwaggerClient': ...
92
    @classmethod
93
    def from_spec(cls, spec_dict: dict, origin_url: str = None, http_client=None, config=None) -> 'SwaggerClient': ...
94
    def get_model(self, model_name: str): ...
95
```
96

97
[Client Management](./client-management.md)
98

99
### HTTP Clients
100

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

103
```python { .api }
104
class RequestsClient(HttpClient):
105
    def __init__(self, ssl_verify: bool = True, ssl_cert=None, **kwargs): ...
106
    def request(self, request_params: dict, operation=None, request_config=None) -> HttpFuture: ...
107
    def set_basic_auth(self, host: str, username: str, password: str): ...
108
    def set_api_key(self, host: str, api_key: str, param_name: str = 'api_key', param_in: str = 'query'): ...
109

110
class FidoClient(HttpClient):
111
    def __init__(self, **kwargs): ...
112
    def request(self, request_params: dict, operation=None, request_config=None) -> HttpFuture: ...
113
```
114

115
[HTTP Clients](./http-clients.md)
116

117
### Authentication
118

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

121
```python { .api }
122
class BasicAuthenticator(Authenticator):
123
    def __init__(self, host: str, username: str, password: str): ...
124
    def apply(self, request): ...
125

126
class ApiKeyAuthenticator(Authenticator):
127
    def __init__(self, host: str, api_key: str, param_name: str = 'api_key', param_in: str = 'query'): ...
128
    def apply(self, request): ...
129
```
130

131
[Authentication](./authentication.md)
132

133
### Response Handling
134

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

137
```python { .api }
138
class HttpFuture:
139
    def __init__(self, future, response_adapter, operation=None, request_config=None): ...
140
    def response(self, timeout=None, fallback_result=None, exceptions_to_catch=None) -> BravadoResponse: ...
141
    def result(self, timeout=None): ...  # DEPRECATED
142
    def cancel(): ...
143

144
class BravadoResponse:
145
    result: Any
146
    metadata: BravadoResponseMetadata
147
    @property
148
    def incoming_response(self) -> IncomingResponse: ...
149
```
150

151
[Response Handling](./response-handling.md)
152

153
### Exception Handling
154

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

157
```python { .api }
158
class HTTPError(IOError):
159
    status_code: int
160
    def __init__(self, response, message: str = None, swagger_result=None): ...
161

162
# Specific status code exceptions (300-511)
163
class HTTPBadRequest(HTTPClientError): status_code = 400
164
class HTTPUnauthorized(HTTPClientError): status_code = 401
165
class HTTPForbidden(HTTPClientError): status_code = 403
166
class HTTPNotFound(HTTPClientError): status_code = 404
167
class HTTPInternalServerError(HTTPServerError): status_code = 500
168
# ... and many more
169

170
class BravadoTimeoutError(TimeoutError): ...
171
class BravadoConnectionError(ConnectionError): ...
172

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

176
[Exception Handling](./exception-handling.md)
177

178
### Configuration
179

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

182
```python { .api }
183
class BravadoConfig:
184
    also_return_response: bool
185
    disable_fallback_results: bool
186
    response_metadata_class: Type[BravadoResponseMetadata]
187
    sensitive_headers: list
188

189
class RequestConfig:
190
    also_return_response: bool
191
    force_fallback_result: bool
192
    response_callbacks: list
193
    connect_timeout: float
194
    timeout: float
195
    headers: dict
196
    use_msgpack: bool
197
    additional_properties: dict
198

199
def bravado_config_from_config_dict(config_dict: dict) -> BravadoConfig: ...
200
```
201

202
[Configuration](./configuration.md)
203

204
### Spec Loading
205

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

208
```python { .api }
209
class Loader:
210
    def __init__(self, http_client, request_headers: dict = None): ...
211
    def load_spec(self, spec_url: str, base_url: str = None) -> dict: ...
212
    def load_yaml(self, text: str) -> dict: ...
213

214
def load_file(spec_file: str, http_client=None) -> dict: ...
215
def load_url(spec_url: str, http_client=None, base_url: str = None) -> dict: ...
216
```
217

218
[Spec Loading](./spec-loading.md)
219

220
### Testing Utilities
221

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

224
```python { .api }
225
class BravadoResponseMock:
226
    def __init__(self, result, metadata=None): ...
227
    def __call__(self, timeout=None, fallback_result=None, exceptions_to_catch=None) -> 'BravadoResponseMock': ...
228
    @property
229
    def result: Any: ...
230
    @property
231
    def metadata: BravadoResponseMetadata: ...
232

233
class IntegrationTestingFixturesMixin:
234
    http_client: HttpClient
235
    http_client_type: Type[HttpClient]
236
    def swagger_client(self) -> SwaggerClient: ...
237
```
238

239
[Testing Utilities](./testing-utilities.md)