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
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 8.102s · 75MB
glibcpy 3.10–3.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.fixReplace `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.fixEnsure 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.fixWhen 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.fixPass 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.
fixUse `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`.
fixAccess 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.
fixEnsure 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.
fixEnsure 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.
fixVerify 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.