Docs for proposed Pipeline context manager.

1 files changed, 34 insertions, 22 deletions

diff --git a/README.md b/README.md
index f65bd77..b28558c 100644
--- a/README.md
+++ b/README.md
@@ -174,36 +174,48 @@ execution of that transaction, the entre transaction will be canceled and a
 WatchError will be raised. To implement our own client-side INCR command, we
 could do something like this:
 
+    >>> with r.pipeline() as pipe:
+    ...     while 1:
+    ...         try:
+    ...             # put a WATCH on the key that holds our sequence value
+    ...             pipe.watch('OUR-SEQUENCE-KEY')
+    ...             # after WATCHing, the pipeline is put into immediate execution
+    ...             # mode until we tell it to start buffering commands again.
+    ...             # this allows us to get the current value of our sequence
+    ...             current_value = pipe.get('OUR-SEQUENCE-KEY')
+    ...             next_value = int(current_value) + 1
+    ...             # now we can put the pipeline back into buffered mode with MULTI
+    ...             pipe.multi()
+    ...             pipe.set('OUR-SEQUENCE-KEY', next_value)
+    ...             # and finally, execute the pipeline (the set command)
+    ...             pipe.execute()
+    ...             # if a WatchError wasn't raised during execution, everything
+    ...             # we just did happened atomically.
+    ...             break
+    ...        except WatchError:
+    ...             # another client must have changed 'OUR-SEQUENCE-KEY' between
+    ...             # the time we started WATCHing it and the pipeline's execution.
+    ...             # our best bet is to just retry.
+    ...             continue
+
+Note that, because the `Pipeline` must bind to a single connection for the
+duration of a `watch`, care must be taken to ensure that he connection is
+returned to the connection pool by calling the `reset()` method. If the
+`Pipeline` is used as a context manager (as in the example above) `reset()`
+will be called automatically... But it can also be called manually, like this:
+
     >>> pipe = r.pipeline()
     >>> while 1:
     ...     try:
-    ...         # put a WATCH on the key that holds our sequence value
     ...         pipe.watch('OUR-SEQUENCE-KEY')
-    ...         # after WATCHing, the pipeline is put into immediate execution
-    ...         # mode until we tell it to start buffering commands again.
-    ...         # this allows us to get the current value of our sequence
-    ...         current_value = pipe.get('OUR-SEQUENCE-KEY')
-    ...         next_value = int(current_value) + 1
-    ...         # now we can put the pipeline back into buffered mode with MULTI
-    ...         pipe.multi()
-    ...         pipe.set('OUR-SEQUENCE-KEY', next_value)
-    ...         # and finally, execute the pipeline (the set command)
+    ...         ...
     ...         pipe.execute()
-    ...         # if a WatchError wasn't raised during execution, everything
-    ...         # we just did happened atomically.
-    ...         break
-    ...    except WatchError:
-    ...         # another client must have changed 'OUR-SEQUENCE-KEY' between
-    ...         # the time we started WATCHing it and the pipeline's execution.
-    ...         # our best bet is to just retry.
+    ...     except WatchError:
     ...         continue
-    ...    finally:
-    ...         # Ensure that the pipe's connection has been returned to the
-    ...         # pool (this will normally be done in `pipe.execute()`, but
-    ...         # it should also be done here in case an exception is raised
-    ...         # before `pip.execute()` can be called).
+    ...     finally:
     ...         pipe.reset()
 
+
 ## API Reference
 
 The official Redis documentation does a great job of explaining each command in