Bravado

https://github.com/yelp/bravado
Admin
Bravado is a Python library for accessing OpenAPI Specification (formerly Swagger) enabled APIs,...
Tokens:8,959
Snippets:179
Trust Score:9.1
License:BSD-3-Clause
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Bravado

Source: https://github.com/yelp/bravado/blob/master/docs/source/quickstart.md

Install the latest stable version of Bravado from PyPi.

```bash
$ pip install --upgrade bravado
```

--------------------------------

### Instantiate Swagger Client

Source: https://github.com/yelp/bravado/blob/master/README.rst

Basic instantiation of the SwaggerClient from a URL. This is the simplest way to get started.

```Python
from bravado.client import SwaggerClient
client = SwaggerClient.from_url('http://petstore.swagger.io/v2/swagger.json')
pet = client.pet.getPetById(petId=1).response().result
```

--------------------------------

### First API Call (GET)

Source: https://github.com/yelp/bravado/blob/master/docs/source/quickstart.md

Make a simple GET request to retrieve a pet by its ID using the SwaggerClient. This example assumes the Swagger JSON is available at the specified URL.

```python
from bravado.client import SwaggerClient

client = SwaggerClient.from_url("http://petstore.swagger.io/v2/swagger.json")
pet = client.pet.getPetById(petId=42).response().result
```

--------------------------------

### Sample Response Object

Source: https://github.com/yelp/bravado/blob/master/docs/source/quickstart.md

An example of the dynamically created model object returned by a successful GET request.

```text
Pet(category=Category(id=0L, name=u''), status=u'', name=u'', tags=[Tag(id=0L, name=u'')], photoUrls=[u''], id=2)
```

--------------------------------

### Install Bravado (Synchronous HTTP Client)

Source: https://github.com/yelp/bravado/blob/master/README.rst

Command to install Bravado with only the Synchronous Http Client.

```bash
# To install bravado with Synchronous Http Client only.
$ pip install bravado
```

--------------------------------

### Client Configuration Example

Source: https://github.com/yelp/bravado/blob/master/docs/source/configuration.md

Demonstrates how to create a configuration dictionary for SwaggerClient, including both bravado and bravado-core specific settings. This configuration is passed during client initialization.

```python
from bravado.client import SwaggerClient, SwaggerFormat

my_super_duper_format = SwaggerFormat(...)

config = {
    # === bravado config ===

    # What class to use for response metadata
    'response_metadata_class': 'bravado.response.BravadoResponseMetadata',

    # Do not use fallback results even if they're provided
    'disable_fallback_results': False,

    # DEPRECATED: Determines what is returned by HttpFuture.result().
    # Please use HttpFuture.response() for accessing the http response.
    'also_return_response': False,

    # === bravado-core config ====

    # Validate incoming responses
    'validate_responses': True,

    # Validate outgoing requests
    'validate_requests': True,

    # Validate the swagger spec
    'validate_swagger_spec': True,

    # Use models (Python classes) instead of dicts for #/definitions/{models}
    'use_models': True,

    # List of user-defined formats
    'formats': [my_super_duper_format],

}

client = SwaggerClient.from_url(..., config=config)
```

--------------------------------

### Install Bravado (Synchronous and Asynchronous HTTP Clients)

Source: https://github.com/yelp/bravado/blob/master/README.rst

Command to install Bravado with both Synchronous and Asynchronous Http Clients, including RequestsClient and FidoClient.

```bash
# To install bravado with Synchronous and Asynchronous Http Client (RequestsClient and FidoClient).
$ pip install bravado[fido]
```

--------------------------------

### Asynchronous GET Request with FidoClient

Source: https://github.com/yelp/bravado/blob/master/docs/source/quickstart.md

Rewrite the first GET request to use the asynchronous Fido client with an optional timeout. Ensure bravado is installed with the 'fido' extra.

```python
from bravado.client import SwaggerClient
from bravado.fido_client import FidoClient

client = SwaggerClient.from_url(
    'http://petstore.swagger.io/v2/swagger.json',
    FidoClient()
)

result = client.pet.getPetById(petId=42).result(timeout=4)
```

--------------------------------

### Install Git Pre-commit Hooks

Source: https://github.com/yelp/bravado/blob/master/README.rst

Command to install git pre-commit hooks for development workflows.

```bash
# Install git pre-commit hooks
tox -e pre-commit install
```

--------------------------------

### GET Request with Dictionary Response

Source: https://github.com/yelp/bravado/blob/master/docs/source/quickstart.md

Configure the client to not use models and receive responses as simple dictionaries. This example also includes an optional timeout.

```python
from bravado.client import SwaggerClient

client = SwaggerClient.from_url(
    'http://petstore.swagger.io/v2/swagger.json',
    config={'use_models': False}
)

result = client.pet.getPetById(petId=42).result(timeout=4)
```

--------------------------------

### Example Code to Test

Source: https://github.com/yelp/bravado/blob/master/docs/source/testing.md

This is the Python code that utilizes bravado to fetch pet photos. It's the target for our unit tests.

```python
from itertools import chain

from bravado.client import SwaggerClient

def get_available_pet_photos():
    petstore = SwaggerClient.from_url(
        'http://petstore.swagger.io/v2/swagger.json',
    )
    pets = petstore.pet.findPetsByStatus(status=['available']).response(
        timeout=0.5,
        fallback_result=lambda e: [],
    ).result

    return chain.from_iterable(pet.photoUrls for pet in pets)
```

--------------------------------

### Instantiate Swagger Client with FidoClient (Async)

Source: https://github.com/yelp/bravado/blob/master/README.rst

Instantiate the SwaggerClient using the FidoClient for asynchronous HTTP requests. Ensure bravado is installed with the 'fido' extra.

```Python
# Install bravado with fido extra (``pip install bravado[fido]``)
from bravado.fido_client import FidoClient
from bravado.client import SwaggerClient

http_client = FidoClient()
client = SwaggerClient.from_url(
    'http://petstore.swagger.io/v2/swagger.json',
    http_client=http_client,
)
pet = client.pet.getPetById(petId=1).response().result
```

--------------------------------

### Sample Dictionary Response

Source: https://github.com/yelp/bravado/blob/master/docs/source/quickstart.md

An example of a response received as a plain dictionary when 'use_models' is set to False.

```javascript
{
    'category': {
        'id': 0L,
        'name': u''
    },
    'id': 2,
    'name': u'',
    'photoUrls': [u''],
    'status': u'',
    'tags': [
        {'id': 0L, 'name': u''}
    ]
}
```

--------------------------------

### Minimal Custom Response Metadata Implementation

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

A basic example of a custom response metadata class that subclasses Bravado's ResponseMetadata. Ensure your __init__ method accepts and passes all arguments to the superclass to maintain compatibility.

```python
class MyResponseMetadata(ResponseMetadata):
    def __init__(self, *args, **kwargs):
        super(MyResponseMetadata, self).__init__(*args, **kwargs)
```

--------------------------------

### Use Default Values from Spec

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

Example of calling an operation without providing a parameter that has a default value defined in the Swagger spec. Bravado automatically uses the default value.

```python
client.pet.findPetByStatus()
```

--------------------------------

### Validate Request Body

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

Example of a request body that will fail validation due to incorrect type for the 'id' field. This demonstrates Bravado's built-in validation against the Swagger schema.

```python
pet = Pet(id="I should be integer :(", name="tommy")
client.pet.addPet(body=pet).response().result
```

--------------------------------

### Load Swagger from File Path

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

Shows how to initialize a SwaggerClient by providing the path to a local swagger.json file using the 'from_url' method with a 'file://' URI.

```python
client = SwaggerClient.from_url('file:///some/path/swagger.json')
```

--------------------------------

### Instantiate Swagger Client with Basic Authentication

Source: https://github.com/yelp/bravado/blob/master/README.rst

Instantiate the SwaggerClient using basic authentication. Requires setting up the RequestsClient with username and password for a specific host.

```Python
from bravado.requests_client import RequestsClient
from bravado.client import SwaggerClient

http_client = RequestsClient()
http_client.set_basic_auth(
    'api.yourhost.com',
    'username', 'password'
)
client = SwaggerClient.from_url(
    'http://petstore.swagger.io/v2/swagger.json',
    http_client=http_client,
)
pet = client.pet.getPetById(petId=1).response().result
```

--------------------------------

### Load Swagger using load_file Helper

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

Demonstrates an alternative method to load a Swagger definition from a file using the 'load_file' helper function and 'from_spec'.

```python
from bravado.swagger_model import load_file

client = SwaggerClient.from_spec(load_file('/path/to/swagger.json'))
```

--------------------------------

### Access Model Docstring

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

Demonstrates retrieving the docstring for a model using the '?' method, which provides details about its attributes and constructor.

```console
>> pet_model = petstore.get_model('Pet')
>> pet_model?

Type:       type
String Form:<class 'bravado_core.Pet'>
File:       /some/dir/bravado_core/model.py
Docstring:
Attributes:

category: Category
id: integer
name: string
photoUrls: list of string
status: string - pet status in the store
tags: list of Tag
Constructor information:
 Definition:pet_type(self, **kwargs)
```

--------------------------------

### Access Operation Docstring

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

Shows how to use the '?' method to retrieve the docstring for an operation, which includes parameter and return type information.

```console
>> petstore.pet.getPetById?

Type:       CallableOperation
String Form:<bravado.client.CallableOperation object at 0x241b5d0>
File:       /some/dir/bravado/bravado/client.py
Definition: c.pet.getPetById(self, **op_kwargs)
Docstring:
[GET] Find pet by ID

Returns a single pet

:param petId: ID of pet to return
:type petId: integer
:returns: 200: successful operation
:rtype: object
:returns: 400: Invalid ID supplied
:returns: 404: Pet not found
Constructor Docstring::type operation: :class:`bravado_core.operation.Operation`
Call def:   c.pet.getPetById(self, **op_kwargs)
Call docstring:
Invoke the actual HTTP request and return a future that encapsulates
the HTTP response.

:rtype: :class:`bravado.http_future.HTTPFuture`
```

--------------------------------

### Instantiate Swagger Client with Header Authentication

Source: https://github.com/yelp/bravado/blob/master/README.rst

Instantiate the SwaggerClient using API key authentication passed in a header. The API key and parameter name must be specified.

```Python
from bravado.requests_client import RequestsClient
from bravado.client import SwaggerClient

http_client = RequestsClient()
http_client.set_api_key(
    'api.yourhost.com', 'token',
    param_name='api_key', param_in='header'
)
client = SwaggerClient.from_url(
    'http://petstore.swagger.io/v2/swagger.json',
    http_client=http_client,
)
pet = client.pet.getPetById(petId=1).response().result
```

--------------------------------

### POST Request with Models

Source: https://github.com/yelp/bravado/blob/master/docs/source/quickstart.md

Demonstrates how to create and send a POST request using Bravado models, hiding JSON handling and making the code more Pythonic.

```python
Pet = client.get_model('Pet')
Category = client.get_model('Category')
pet = Pet(id=42, name="tommy", category=Category(id=24))
client.pet.addPet(body=pet).response().result
```

--------------------------------

### Add Custom Request Headers

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

Demonstrates how to include custom HTTP headers in a request. The '_request_options' parameter is used to pass a dictionary of headers.

```python
Pet = client.get_model('Pet')
Category = client.get_model('Category')
pet = Pet(id=42, name="tommy", category=Category(id=24))
swagger_client.pet.addPet(
    body=pet,
    _request_options={"headers": {"foo": "bar"}},
).response().result
```

--------------------------------

### Run Tests with Tox

Source: https://github.com/yelp/bravado/blob/master/README.rst

Command to execute tests using tox, a Python testing and automation tool.

```bash
# Run tests
tox
```

--------------------------------

### Applying Per-Request Options

Source: https://github.com/yelp/bravado/blob/master/docs/source/configuration.md

Pass a dictionary of request options to the `_request_options` parameter of a service call to override default configurations for that specific request. This is useful for setting custom headers or timeouts.

```python
client = SwaggerClient.from_url(...)
request_options = { ... }
client.pet.getPetById(petId=42, _request_options=request_options).response().result
```

--------------------------------

### Mocking API Responses with BravadoResponseMock

Source: https://github.com/yelp/bravado/blob/master/docs/source/testing.md

This test uses `BravadoResponseMock` to simulate the response from `findPetsByStatus`. It asserts that the correct photo URLs are returned.

```python
import mock

from bravado.testing.response_mocks import BravadoResponseMock

from mypackage import get_available_pet_photos

def test_get_available_pet_photos(mock_client):
    mock_pets = [
        mock.Mock(
            photoUrls=['https://example.com/image.png'],
        ),
        mock.Mock(
            photoUrls=[
                'https://example.com/image2.png',
                'https://example.com/image3.png',
            ],
        ),
    ]

    mock_client.pet.findPetsByStatus.return_value.response = BravadoResponseMock(
        result=mock_pets,
    )

    pet_photos = get_available_pet_photos()

    assert list(pet_photos) == [
        'https://example.com/image.png',
        'https://example.com/image2.png',
        'https://example.com/image3.png',
    ]
```

--------------------------------

### Testing Fallback Responses with FallbackResultBravadoResponseMock

Source: https://github.com/yelp/bravado/blob/master/docs/source/testing.md

This test verifies the fallback result path by using `FallbackResultBravadoResponseMock`. It asserts that an empty list is returned when the fallback is triggered.

```python
from bravado.testing.response_mocks import FallbackResultBravadoResponseMock

from example import get_available_pet_photos

def test_get_available_pet_photos_fallback_result(mock_client):
    mock_client.pet.findPetsByStatus.return_value
        .response = FallbackResultBravadoResponseMock()

    pet_photos = get_available_pet_photos()

    assert list(pet_photos) == []
```

--------------------------------

### Basic Fallback Result

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

Use a simple value as a fallback when an API call times out or returns an error.

```python
petstore = SwaggerClient.from_url('http://petstore.swagger.io/v2/swagger.json')
response = petstore.pet.findPetsByStatus(status=['available']).response(
    timeout=0.5,
    fallback_result=[],
)
```

--------------------------------

### Access HTTP Response with also_return_response

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

Configures the SwaggerClient to return the full HTTP response along with the result. This allows access to headers and status codes.

```python
petstore = SwaggerClient.from_url(
    'http://petstore.swagger.io/v2/swagger.json',
    config={'also_return_response': True},
)
pet_response = petstore.pet.getPetById(petId=42).response()
http_response = pet_response.incoming_response
assert isinstance(http_response, bravado_core.response.IncomingResponse)
print http_response.headers
print http_response.status_code
print pet.name
```

--------------------------------

### Fallback Result with Model Instance

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

When using models, return an instance of the expected model from your fallback function or value to maintain type compatibility. Use `SwaggerClient.get_model()` to retrieve model classes.

```python
petstore = SwaggerClient.from_url('http://petstore.swagger.io/v2/swagger.json')
response = petstore.pet.getPetById(petId=101).response(
    timeout=0.5,
    fallback_result=petstore.get_model('Pet')(name='No Pet found', photoUrls=[]),
)
```

--------------------------------

### Mocking the SwaggerClient for Unit Tests

Source: https://github.com/yelp/bravado/blob/master/docs/source/testing.md

This pytest fixture mocks the SwaggerClient to prevent actual network requests during testing. It patches the `from_url` method.

```python
import mock
import pytest

from bravado.client import SwaggerClient

@pytest.fixture
def mock_client():
    mock_client = mock.Mock(name='mock SwaggerClient')
    with mock.patch.object(SwaggerClient, 'from_url', return_value=mock_client):
        yield mock_client
```

--------------------------------

### Callable Fallback for Differentiated Error Handling

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

Provide a callable function as a fallback to handle different exception types, such as timeouts or server errors, distinctly. This allows for custom logic based on the error encountered.

```python
def pet_status_fallback(exc):
    if isinstance(exc, BravadoTimeoutError):
        # Backend is slow, return last cached response
        return pet_status_cache

    # Some server issue, let's not show any pets
    return []

petstore = SwaggerClient.from_url(
    'http://petstore.swagger.io/v2/swagger.json',
    # The petstore result for this call is not spec compliant...
    config={'validate_responses': False},
)
response = petstore.pet.findPetsByStatus(status=['available']).response(
    timeout=0.5,
    fallback_result=pet_status_fallback,
)

if not response.metadata.is_fallback_result:
    pet_status_cache = response.result
```

--------------------------------

### Validation Error Message

Source: https://github.com/yelp/bravado/blob/master/docs/source/advanced.md

The expected error message when the 'id' field in the Pet object is not of the correct integer type.

```console
TypeError: id's value: 'I should be integer :(' should be in types (<type 'long'>, <type 'int'>)
```
Tokens:
Raw