Registry / http-networking / bravado

bravado

JSON →
library12.0.1pypypi✓ verified 21d ago

Bravado is a Python client library for accessing OpenAPI Specification v2.0 (formerly Swagger) services. It aims to replace code generation by providing a dynamically generated client, supporting both synchronous and asynchronous HTTP requests. The library performs strict validations against the OpenAPI schema for both requests and responses. The current version is 12.0.1, requiring Python 3.8 or newer, and it maintains an active development status with irregular but significant updates.

pip install bravado
INSTALL
IMPORT
SIG · BRAVADO
B
bravado
http-networkingpythonv12.0.1
Install
8.0s avg
Import
7868ms
Disk
78MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v12.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.915 runs
installs and imports cleanly · install 0.0s · import 8.102s · 75MB
glibc
py 3.103.915 runs
installs and imports cleanly · install 8.0s · import 7.634s · 77MB
78MB installed
● package 78MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SwaggerClient
from bravado.client import SwaggerClient
RequestsClient
from bravado.requests_client import RequestsClient
FidoClient
from bravado.fido_client import FidoClient
AsyncioClient
from bravado_asyncio.http_client import AsyncioClient
For the bravado-asyncio optional dependency.

Initializes a SwaggerClient from a public OpenAPI/Swagger specification URL and demonstrates a simple GET request. It also shows how to perform a POST request and mentions optional configuration to disable validation or receive responses as dictionaries instead of dynamic models.

from bravado.client import SwaggerClient # Using a publicly available Petstore Swagger/OpenAPI spec client = SwaggerClient.from_url('http://petstore.swagger.io/v2/swagger.json') # Make a synchronous API call and get the result try: # Using .response().result is the recommended way to get the data pet = client.pet.getPetById(petId=42).response().result print(f"Found pet: {pet.name} (ID: {pet.id})") # Example of a POST call Pet = client.get_model('Pet') Category = client.get_model('Category') new_pet = Pet(id=100, name="Buddy", category=Category(id=1, name="Dogs"), photoUrls=[]) add_result = client.pet.addPet(body=new_pet).response().result print(f"Added pet: {add_result.name} (ID: {add_result.id})") except Exception as e: print(f"An error occurred: {e}") # Example of disabling validation for a request/response (not recommended for production) # client_config = { # 'validate_requests': False, # 'validate_responses': False, # 'use_models': False # Get dicts instead of dynamic models # } # client_relaxed = SwaggerClient.from_url( # 'http://petstore.swagger.io/v2/swagger.json', # config=client_config # ) # pet_dict = client_relaxed.pet.getPetById(petId=42).response().result # print(f"Found pet as dict: {pet_dict.get('name')}")
Debug
Known issues
deprecatedThe `HttpFuture.result()` method is deprecated. Users should now use `HttpFuture.response().result` to access the unmarshalled Swagger result, or `HttpFuture.response()` to get the full `BravadoResponse` instance which includes both the result and HTTP metadata.
fix
Replace `client.operation().result()` with `client.operation().response().result`.
affects: All versions where `response()` exists, specifically recent versions from 1.x onwards (e.g., in documentation from 2018 onwards).
gotchaBravado performs strict validation by default on the Swagger/OpenAPI specification itself, as well as on outgoing requests and incoming responses. This can lead to validation errors if the spec is malformed or if requests/responses don't strictly adhere to the schema.
fix
Ensure your Swagger spec is valid and that your API interactions conform to it. Validation can be selectively disabled via the `config` dictionary passed to `SwaggerClient.from_url()` or `from_spec()` (e.g., `{'validate_requests': False, 'validate_responses': False, 'validate_swagger_spec': False}`).
affects: All versions
gotchaDocstrings for operations in Bravado do not behave like standard Python function docstrings and the built-in `help()` function might not work as expected. The docstrings are structured more like class docstrings.
fix
When using an interactive Python environment (like IPython), use the `?` suffix (e.g., `client.pet.getPetById?`) to view the operation's detailed documentation, including parameters and return types.
affects: All versions
gotchaBy default, network or server errors will raise exceptions (e.g., `BravadoTimeoutError`, `HTTPServerError`). For more graceful error handling, `HttpFuture.response()` supports a `fallback_result` argument.
fix
Pass a `fallback_result` (either a static value or a callable that accepts the exception) and optionally `exceptions_to_catch` to `response()`: `client.operation().response(fallback_result=my_fallback_func, exceptions_to_catch=(BravadoTimeoutError,))`.
affects: All versions
Errors
Common errors & fixes
AttributeError: type object 'SwaggerClient' has no attribute 'from_dict'
The `SwaggerClient` class no longer directly exposes a `from_dict` class method; instead, it uses `from_spec` to load a dictionary-based specification.
fix
Use `SwaggerClient.from_spec()` or `SwaggerClient.from_url()` to initialize the client, ensuring the specification is a dictionary if using `from_spec` or a URL for `from_url`.

```python
from bravado.client import SwaggerClient

# If loading from a dict
# spec_dict = {'swagger': '2.0', ...}
# client = SwaggerClient.from_spec(spec_dict)

# If loading from a URL
client = SwaggerClient.from_url('http://petstore.swagger.io/swagger.json')
```
AttributeError: type object "SomeBravadoResourceType" has no attribute 'marshal'
In `bravado-core` versions, the `marshal` and `unmarshal` methods on resource objects were made private to indicate they are internal APIs and were renamed with a leading underscore, e.g., `_marshal`.
fix
Access internal marshalling/unmarshalling methods using their private names, `_marshal` and `_unmarshal`, or use the higher-level client methods that handle this automatically. Direct use of these methods is generally discouraged for application developers.

```python
# Avoid direct calls to marshal/unmarshal on model instances
# Use client operations that handle marshalling automatically
# e.g., client.pet.addPet(body=pet_instance).response().result

# If absolutely necessary and aware of the internal API:
# model_instance._marshal()
# model_class._unmarshal(data)
```
bravado.exception.SwaggerMappingError: Missing a required parameter: 'parameter_name'
This error occurs when a required parameter for an API operation call is not provided, or when extra, unrecognized parameters are passed to an operation.
fix
Ensure all required parameters as defined in the Swagger/OpenAPI specification are provided when calling an operation, and avoid passing any extraneous keyword arguments.

```python
# Example: If 'petId' is a required parameter
# Correct:
# client.pet.getPetById(petId=123).response().result

# Incorrect (missing petId):
# client.pet.getPetById().response().result

# Incorrect (extra_param is not defined in spec):
# client.pet.getPetById(petId=123, extra_param='foo').response().result
```
TypeError: id's value: 'I should be integer :(' should be in types (<class 'int'>)
This `TypeError` from `bravado` (via `bravado-core`'s validation) indicates that a value provided for a parameter or a model property does not conform to the data type specified in the OpenAPI/Swagger schema.
fix
Ensure that the data types of values passed to API operations or used in model objects strictly adhere to the types defined in the Swagger/OpenAPI specification. For instance, if an 'id' is defined as an integer, provide an actual integer.

```python
# Example: If 'id' is specified as an integer
# Correct:
# from bravado.client import SwaggerClient
# client = SwaggerClient.from_url('http://petstore.swagger.io/swagger.json')
# Pet = client.get_model('Pet')
# pet_instance = Pet(id=123, name='MyPet')
# client.pet.addPet(body=pet_instance).response().result

# Incorrect (id is a string when it should be an integer):
# pet_instance = Pet(id='not_an_integer', name='MyPet')
```
AttributeError: 'Resource <resource_name>' not found. Available resources: <list_of_available_resources>
This error occurs when attempting to access a resource (like `client.my_resource`) that is not defined or is misspelled in the loaded Swagger/OpenAPI specification.
fix
Verify that the resource name you are trying to access exactly matches one of the resources defined in your Swagger/OpenAPI specification, paying attention to case sensitivity. The error message usually lists the available resources.

```python
# Example: If the spec defines a resource 'pet' (lowercase)
# Correct:
# client.pet.findPetsByStatus(status='available').response().result

# Incorrect (trying to access 'Pet' with uppercase 'P' if not defined as such):
# client.Pet.findPetsByStatus(status='available').response().result
```
Upgrade
Version history
12.0.1latest on PyPI · released May 7, 2025
Audit
Dependencies
requestsrequiredDefault synchronous HTTP client.
bravado-corerequiredImplements Swagger 2.0 Specification features like schema validation and marshaling.
fidooptionalOptional asynchronous HTTP client.
bravado-asynciooptionalAlternative asynchronous HTTP client.
swagger-spec-validatorrequiredUsed by bravado-core for spec validation.
Agent activity
21 hits · last 30 days
node
18
OpenAI (training)
1
Resources
bravado — pip install bravado · libregistry