Allowed Context.push to behave as a context mananger.

Thanks Loic Bistuer for the review.

1 files changed, 25 insertions, 0 deletions

diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt
index 6a9efc0811..f7dd0121d1 100644
--- a/docs/ref/templates/api.txt
+++ b/docs/ref/templates/api.txt
@@ -325,6 +325,31 @@ If you ``pop()`` too much, it'll raise
     ...
     django.template.ContextPopException
 
+.. versionadded:: 1.7
+
+You can also use ``push()`` as a context manager to ensure a matching ``pop()``
+is called.
+
+    >>> c = Context()
+    >>> c['foo'] = 'first level'
+    >>> with c.push():
+    >>>     c['foo'] = 'second level'
+    >>>     c['foo']
+    'second level'
+    >>> c['foo']
+    'first level'
+
+All arguments passed to ``push()`` will be passed to the ``dict`` constructor
+used to build the new context level.
+
+    >>> c = Context()
+    >>> c['foo'] = 'first level'
+    >>> with c.push(foo='second level'):
+    >>>     c['foo']
+    'second level'
+    >>> c['foo']
+    'first level'
+
 .. method:: update(other_dict)
 
 In addition to ``push()`` and ``pop()``, the ``Context``