0
# HTTP Clients
1

2
Synchronous and asynchronous HTTP client implementations with pluggable adapters. Bravado provides two main HTTP client implementations: RequestsClient for synchronous operations and FidoClient for asynchronous/Twisted-based operations.
3

4
## Capabilities
5

6
### HttpClient (Base Interface)
7

8
Abstract base class defining the HTTP client interface that all implementations must follow.
9

10
```python { .api }
11
class HttpClient:
12
    def request(self, request_params: dict, operation=None, request_config=None) -> HttpFuture: ...
13
    def __repr__(self) -> str: ...
14
```
15

16
**Parameters:**
17
- `request_params` (dict): Complete request data including URL, method, headers, body, params, timeouts
18
- `operation`: bravado_core.operation.Operation object (optional)
19
- `request_config`: RequestConfig instance for per-request configuration
20

21
**Returns:**
22
- HttpFuture object for handling the response
23

24
### RequestsClient (Synchronous)
25

26
HTTP client implementation using the requests library for synchronous operations. Supports SSL configuration, authentication, and connection pooling.
27

28
```python { .api }
29
class RequestsClient(HttpClient):
30
    def __init__(self, ssl_verify: bool = True, ssl_cert=None, future_adapter_class=RequestsFutureAdapter, response_adapter_class=RequestsResponseAdapter): ...
31
    def __hash__(self) -> int: ...
32
    def __eq__(self, other) -> bool: ...
33
    def __ne__(self, other) -> bool: ...
34
    def request(self, request_params: dict, operation=None, request_config=None) -> HttpFuture: ...
35
    def set_basic_auth(self, host: str, username: str, password: str): ...
36
    def set_api_key(self, host: str, api_key: str, param_name: str = 'api_key', param_in: str = 'query'): ...
37
    def separate_params(self, request_params: dict) -> tuple: ...
38
    def authenticated_request(self, request_params: dict): ...
39
    def apply_authentication(self, request): ...
40
```
41

42
**Parameters:**
43
- `ssl_verify` (bool): Whether to verify SSL certificates (default: True)
44
- `ssl_cert`: Path to SSL certificate file or (cert_file, key_file) tuple
45
- `future_adapter_class`: Class to use for future adaptation
46
- `response_adapter_class`: Class to use for response adaptation
47
- `host` (str): Hostname for authentication
48
- `username` (str): Username for basic auth
49
- `password` (str): Password for basic auth
50
- `api_key` (str): API key value
51
- `param_name` (str): Parameter name for API key
52
- `param_in` (str): Where to put API key ('query' or 'header')
53

54
**Usage Example:**
55

56
```python
57
from bravado.requests_client import RequestsClient
58
from bravado.client import SwaggerClient
59

60
# Basic client
61
http_client = RequestsClient()
62
client = SwaggerClient.from_url(spec_url, http_client=http_client)
63

64
# With SSL configuration
65
http_client = RequestsClient(ssl_verify=False)  # Disable SSL verification
66
# or
67
http_client = RequestsClient(ssl_cert='/path/to/cert.pem')  # Custom certificate
68

69
# With authentication
70
http_client = RequestsClient()
71
http_client.set_basic_auth('api.example.com', 'username', 'secret')
72
client = SwaggerClient.from_url(spec_url, http_client=http_client)
73
```
74

75
### FidoClient (Asynchronous)
76

77
HTTP client implementation using the fido library for asynchronous operations with Twisted. Requires the fido extra to be installed.
78

79
```python { .api }
80
class FidoClient(HttpClient):
81
    def __init__(self, future_adapter_class=FidoFutureAdapter, response_adapter_class=FidoResponseAdapter): ...
82
    def __hash__(self) -> int: ...
83
    def __eq__(self, other) -> bool: ...
84
    def __ne__(self, other) -> bool: ...
85
    def request(self, request_params: dict, operation=None, request_config=None) -> HttpFuture: ...
86
    @staticmethod
87
    def prepare_request_for_twisted(request_params: dict): ...
88
```
89

90
**Parameters:**
91
- `future_adapter_class`: Class to use for future adaptation (default: FidoFutureAdapter)
92
- `response_adapter_class`: Class to use for response adaptation (default: FidoResponseAdapter)
93

94
**Usage Example:**
95

96
```python
97
# Install: pip install bravado[fido]
98
from bravado.fido_client import FidoClient
99
from bravado.client import SwaggerClient
100

101
# Async client
102
http_client = FidoClient()
103
client = SwaggerClient.from_url(spec_url, http_client=http_client)
104

105
# Operations return HttpFuture objects that work with Twisted
106
future = client.pet.getPetById(petId=1)
107
response = future.response()  # This will integrate with Twisted's event loop
108
```
109

110
### Future Adapters
111

112
Adapter classes that wrap different HTTP client futures to provide a uniform interface.
113

114
#### RequestsFutureAdapter
115

116
```python { .api }
117
class RequestsFutureAdapter(FutureAdapter):
118
    timeout_errors: tuple  # (requests.exceptions.ReadTimeout,)
119
    connection_errors: tuple  # (requests.exceptions.ConnectionError,)
120
    def __init__(self, session, request, misc_options: dict): ...
121
    def result(self, timeout: float = None): ...
122
    def cancel(self): ...
123
    def build_timeout(self, result_timeout: float): ...
124
```
125

126
#### FidoFutureAdapter
127

128
```python { .api }
129
class FidoFutureAdapter(FutureAdapter):
130
    timeout_errors: tuple  # (fido.exceptions.HTTPTimeoutError,)
131
    connection_errors: tuple  # Connection-related exceptions
132
    def __init__(self, eventual_result): ...
133
    def result(self, timeout: float = None): ...
134
    def cancel(self): ...
135
```
136

137
### Response Adapters
138

139
Adapter classes that wrap different HTTP client responses to provide a uniform interface.
140

141
#### RequestsResponseAdapter
142

143
```python { .api }
144
class RequestsResponseAdapter(IncomingResponse):
145
    def __init__(self, requests_lib_response): ...
146
    @property
147
    def status_code(self) -> int: ...
148
    @property
149
    def text(self) -> str: ...
150
    @property
151
    def raw_bytes(self) -> bytes: ...
152
    @property
153
    def reason(self) -> str: ...
154
    @property
155
    def headers(self) -> dict: ...
156
    def json(self, **kwargs): ...
157
```
158

159
#### FidoResponseAdapter
160

161
```python { .api }
162
class FidoResponseAdapter(IncomingResponse):
163
    def __init__(self, fido_response): ...
164
    @property
165
    def status_code(self) -> int: ...
166
    @property
167
    def text(self) -> str: ...
168
    @property
169
    def raw_bytes(self) -> bytes: ...
170
    @property
171
    def reason(self) -> str: ...
172
    @property
173
    def headers(self) -> dict: ...
174
    def json(self, **_): ...
175
```
176

177
## Client Selection Guidelines
178

179
**Use RequestsClient when:**
180
- Building traditional synchronous applications
181
- Using frameworks like Flask, Django, or FastAPI
182
- Simple request/response patterns
183
- Debugging and development (easier to understand flow)
184

185
**Use FidoClient when:**
186
- Building high-concurrency applications
187
- Using Twisted-based frameworks
188
- Need to handle many concurrent API requests
189
- Building microservices with async patterns
190

191
## Custom HTTP Clients
192

193
You can implement custom HTTP clients by inheriting from HttpClient:
194

195
```python
196
from bravado.http_client import HttpClient
197
from bravado.http_future import HttpFuture
198

199
class CustomHttpClient(HttpClient):
200
    def request(self, request_params, operation=None, request_config=None):
201
        # Implement your custom HTTP logic
202
        # Must return an HttpFuture object
203
        pass
204
```
205

206
## Constants
207

208
```python { .api }
209
APP_FORM: str  # 'application/x-www-form-urlencoded'
210
MULT_FORM: str  # 'multipart/form-data'
211
```
212

213
These constants are used for content type handling in form submissions.