From a560ea870da2f66e00a7e846b362d8e92c56651b Mon Sep 17 00:00:00 2001
From: Stephan Jaensch <sjaensch@yelp.com>
Date: Mon, 25 Jun 2018 11:42:39 +0200
Subject: [PATCH] Add callback example, fix example spec URL

---
 bravado/http_future.py   |  3 +--
 docs/source/advanced.rst | 31 +++++++++++++++++++++++++++----
 docs/source/testing.rst  |  2 +-
 3 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/bravado/http_future.py b/bravado/http_future.py
index cca3e653..6069925e 100644
--- a/bravado/http_future.py
+++ b/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).
diff --git a/docs/source/advanced.rst b/docs/source/advanced.rst
index 4c0f5e68..4807e97b 100644
--- a/docs/source/advanced.rst
+++ b/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
diff --git a/docs/source/testing.rst b/docs/source/testing.rst
index 5fc10d9a..6fa32669 100644
--- a/docs/source/testing.rst
+++ b/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,