bravado

Bravado is a Python client library designed for interacting with Swagger 2.0 services. Unlike traditional tools that require a code generation step, Bravado dynamically generates a client at runtime based on your Swagger schema.

Key capabilities include:

• Dynamic Client Generation: No pre-generation step required.
• HTTP Clients: Supports both Synchronous (via requests) and Asynchronous (via fido) clients.
• Validation: Performs strict validation to ensure Swagger Schema v2.0 compatibility and validates both HTTP requests and responses against the schema.
• Type Mapping: Maps Swagger models directly to Python types, allowing you to work with objects instead of raw JSON.
• Schema Ingestion: Can ingest Swagger schemas via local file paths or HTTP URLs.
• Developer Experience: Provides REPL-friendly navigation with docstrings for Resources, Operations, and Models.

After initializing a SwaggerClient via from_url or from_spec, you interact with the API using a hierarchical method structure: client.resource.operation(operation_params).

• Resources: Generated from the tags in your Swagger spec. If an operation has no tags, the first element of its path is used (e.g., /pet/find becomes the pet resource).
• Operations: Named after the operationId in the spec. If no operationId is provided, Bravado generates one.
• Parameters: Pass keyword arguments to the operation method. The keys must match the (sanitized) parameter names from the spec, and values should use corresponding Python types (e.g., use bool for boolean).

Use dir(client) to discover available resources and dir(client.resource) to discover available operations.

# Example pattern
client = SwaggerClient.from_url('http://api.example.com/swagger.json')
# Accessing a resource and calling an operation
response_future = client.pet.find(petId=123)

Calling an operation method returns an HttpFuture. To retrieve the actual result, you must call the .response method on the future, which is a blocking call.

Successful Responses (HTTP 100-299)

If the request succeeds, .response returns a BravadoResponse instance. You can access the parsed Swagger data via the .result attribute.

Error Responses (HTTP 300+)

By default, if the server returns an HTTP status code of 300 or higher, calling .response will raise a subclass of HTTPError. You can catch this exception to access:

• .swagger_result: The parsed Swagger error body.
• .response: The raw HTTP response object.

future = client.pet.find(petId=123)

try:
    # .response() blocks until the request completes
    bravado_response = future.response
    print(bravado_response.result)
except HTTPError as e:
    # Handle 300+ status codes
    print(f"Error status: {e.response.status_code}")
    print(f"Error body: {e.swagger_result}")

Instead of catching exceptions for timeouts or server errors, you can use the fallback_result argument in the .response() method of an HttpFuture.

Static Fallback

Pass a direct value (like an empty list or a model instance) to return when an error occurs.

Dynamic Fallback

Pass a callable that accepts the exception as its only argument. This allows you to return different results based on the error type (e.g., returning cached data on BravadoTimeoutError vs. an empty list on a 5XX error).

Customizing Error Types

By default, fallbacks trigger on timeouts or 5XX errors. To change this, specify the exceptions_to_catch argument in .response().

Testing Fallbacks

To force a fallback for testing, set force_fallback_result=True in the request configuration. This will pass a ForcedFallbackResultError to your fallback callable.

# Static fallback example
response = petstore.pet.findPetsByStatus(status=['available']).response(
    timeout=0.5,
    fallback_result=[],
)

# Dynamic fallback example
def pet_status_fallback(exc):
    if isinstance(exc, BravadoTimeoutError):
        return pet_status_cache
    return []

response = petstore.pet.findPetsByStatus(status=['available']).response(
    timeout=0.5,
    fallback_result=pet_status_fallback,
)

# Check if a fallback was used
if response.metadata.is_fallback_result:
    print("Using fallback data")