Fixed #16335 -- Clarified an unintuitive behavior.

The DTL will perform dict lookup before method lookup, which yields
an unexpected result for defaultdicts.

1 files changed, 12 insertions, 0 deletions

diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt
index 17e5d6944e..e88a7b70f0 100644
--- a/docs/topics/templates.txt
+++ b/docs/topics/templates.txt
@@ -97,6 +97,18 @@ Use a dot (``.``) to access attributes of a variable.
     * Method call
     * List-index lookup
 
+    This can cause some unexpected behavior with objects that override
+    dictionary lookup. For example, consider the following code snippet that
+    attempts to loop over a ``collections.defaultdict``::
+
+        {% for k, v in defaultdict.iteritems %}
+	    Do something with k and v here...
+        {% endfor %}
+
+    Because dictionary lookup happens first, that behavior kicks in and provides
+    a default value instead of using the intended ``.iteritems()``
+    method. In this case, consider converting to a dictionary first.
+
 In the above example, ``{{ section.title }}`` will be replaced with the
 ``title`` attribute of the ``section`` object.