Add callback example, fix example spec URL

bravado/http_future.py

@@ -123,8 +123,7 @@ def response(self, timeout=None, fallback_result=SENTINEL, exceptions_to_catch=F
         :type timeout: float
         :param fallback_result: either the swagger result or a callable that accepts an exception as argument
             and returns the swagger result to use in case of errors
-        :type fallback_result: either any type of object that represents a valid Swagger result or a callable that
-            takes an exception and returns a fallback swagger result
+        :type fallback_result: Optional[Union[Any, Callable[[Exception], Any]]]
         :param exceptions_to_catch: Exception classes to catch and call `fallback_result`
             with. Has no effect if `fallback_result` is not provided. By default, `fallback_result`
             will be called for read timeout and server errors (HTTP 5XX).

docs/source/advanced.rst

@@ -150,7 +150,7 @@ attribute to access the incoming response:
 .. code-block:: python
 
     petstore = SwaggerClient.from_url(
-        'http://petstore.swagger.io/swagger.json',
+        'http://petstore.swagger.io/v2/swagger.json',
         config={'also_return_response': True},
     )
     pet_response = petstore.pet.getPetById(petId=42).response()
@@ -174,7 +174,7 @@ Swagger result to return in case of errors:
 
 .. code-block:: python
 
-    petstore = SwaggerClient.from_url('http://petstore.swagger.io/swagger.json')
+    petstore = SwaggerClient.from_url('http://petstore.swagger.io/v2/swagger.json')
     response = petstore.pet.findPetsByStatus(status=['available']).response(
         timeout=0.5,
         fallback_result=[],
@@ -193,6 +193,29 @@ that would have been raised normally. This allows you to return different result
 to that response, like the HTTP status code. Subclasses of :class:`.HTTPError` have a ``response`` attribute
 that provides access to that data.
 
+.. code-block:: 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
+
 Customizing which error types to handle
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -211,10 +234,10 @@ to return one as well from your fallback_result function to stay compatible with
 
 .. code-block:: python
 
-    petstore = SwaggerClient.from_url('http://petstore.swagger.io/swagger.json')
+    petstore = SwaggerClient.from_url('http://petstore.swagger.io/v2/swagger.json')
     response = petstore.pet.getPetById(petId=101).response(
         timeout=0.5,
-        fallback_result=lambda e: petstore.get_model('Pet')(name='No Pet found', photoUrls=[]),
+        fallback_result=petstore.get_model('Pet')(name='No Pet found', photoUrls=[]),
     )
 
 Two things to note here: first, use :meth:`.SwaggerClient.get_model` to get the model class for a

docs/source/testing.rst

@@ -17,7 +17,7 @@ First of all, let's define the code we'd like to test:
 
     def get_available_pet_photos():
         petstore = SwaggerClient.from_url(
-            'http://petstore.swagger.io/swagger.json',
+            'http://petstore.swagger.io/v2/swagger.json',
         )
         pets = petstore.pet.findPetsByStatus(status=['available']).response(
             timeout=0.5,