From 8274fa60f88607eb0e81908f049c391455956dd8 Mon Sep 17 00:00:00 2001
From: Marek Wywiał <onjinx@gmail.com>
Date: Sun, 16 Feb 2014 14:50:27 +0100
Subject: Made the new template.Context.flatten() method a public API.

That method was introduced in 9db4271bd11ac23a5a5652bbcdf8fb6d4b997651.

Refs #21765.
---
 docs/ref/templates/api.txt | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

(limited to 'docs/ref')

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
-- 
cgit v1.3