Made the new template.Context.flatten() method a public API.

That method was introduced in 9db4271bd11ac23a5a5652bbcdf8fb6d4b997651.

Refs #21765.

2 files changed, 45 insertions, 0 deletions

diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt
index 7627c02b6e..5701b1a9d1 100644
--- a/docs/ref/templates/api.txt
+++ b/docs/ref/templates/api.txt
@@ -368,6 +368,43 @@ the stack instead of an empty one.
 Using a ``Context`` as a stack comes in handy in some custom template tags, as
 you'll see below.
 
+.. method:: Context.flatten()
+
+.. versionadded:: 1.7
+
+Using ``flatten()`` method you can get whole ``Context`` stack as one dictionary
+including builtin variables.
+
+    >>> c = Context()
+    >>> c['foo'] = 'first level'
+    >>> c.update({'bar': 'second level'})
+    {'bar': 'second level'}
+    >>> c.flatten()
+    {'True': True, 'None': None, 'foo': 'first level', 'False': False, 'bar': 'second level'}
+
+A ``flatten()`` method is also internally used to make ``Context`` objects comparable.
+
+    >>> c1 = Context()
+    >>> c1['foo'] = 'first level'
+    >>> c1['bar'] = 'second level'
+    >>> c2 = Context()
+    >>> c2.update({'bar': 'second level', 'foo': 'first level'})
+    {'foo': 'first level', 'bar': 'second level'}
+    >>> c1 == c2
+    True
+
+Result from ``flatten()`` can be useful in unit tests to compare ``Context``
+against ``dict``::
+
+    class ContextTest(unittest.TestCase):
+        def test_against_dictionary(self):
+            c1 = Context()
+            c1['update'] = 'value'
+            self.assertEqual(c1.flatten(), {
+                'True': True, 'None': None, 'False': False,
+                'update': 'value'})
+
+
 .. _subclassing-context-requestcontext:
 
 Subclassing Context: RequestContext
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index cd9a9dd225..8e241caf44 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -636,6 +636,14 @@ Templates
   parameters that are passed to the ``dict`` constructor used to build the new
   context level.
 
+* The new :meth:`Context.flatten() <django.template.Context.flatten>` method
+  returns a ``Context``'s stack as one flat dictionary.
+
+* ``Context`` objects can now be compared for equality (internally, this
+  uses :meth:`Context.flatten() <django.template.Context.flatten>` so the
+  internal structure of each ``Context``'s stack doesn't matter as long as their
+  flattened version is identical).
+
 * The :ttag:`widthratio` template tag now accepts an "as" parameter to capture
   the result in a variable.