From 0fa20045b0d2bf06f11a2bab005d9bd986525eda Mon Sep 17 00:00:00 2001
From: jeff <jeff@sixtyfathoms.com>
Date: Sat, 13 Jun 2020 13:30:27 -1000
Subject: [PATCH] update wording on dictionary default ordering

---
 docs/templates.rst    | 14 +++++++++++---
 src/jinja2/filters.py |  5 ++---
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/docs/templates.rst b/docs/templates.rst
index 6226468d..1826bbcb 100644
--- a/docs/templates.rst
+++ b/docs/templates.rst
@@ -688,9 +688,17 @@ iterate over containers like `dict`::
     {% endfor %}
     </dl>
 
-Note, however, that **Python dicts are not ordered**; so you might want to
-either pass a sorted ``list`` of ``tuple`` s -- or a
-``collections.OrderedDict`` -- to the template, or use the `dictsort` filter.
+Python dicts may not be in the order you want to display them in. If
+order matters, use the ``|dictsort`` filter.
+
+.. code-block:: jinja
+
+    <dl>
+    {% for key, value in my_dict | dictsort %}
+        <dt>{{ key|e }}</dt>
+        <dd>{{ value|e }}</dd>
+    {% endfor %}
+    </dl>
 
 Inside of a for-loop block, you can access some special variables:
 
diff --git a/src/jinja2/filters.py b/src/jinja2/filters.py
index 5ff0bdde..af9a4524 100644
--- a/src/jinja2/filters.py
+++ b/src/jinja2/filters.py
@@ -307,9 +307,8 @@ def do_dictsort(
     by: 'te.Literal["key", "value"]' = "key",
     reverse: bool = False,
 ) -> "t.List[t.Tuple[K, V]]":
-    """Sort a dict and yield (key, value) pairs. Because python dicts are
-    unsorted you may want to use this function to order them by either
-    key or value:
+    """Sort a dict and yield (key, value) pairs. Python dicts may not
+    be in the order you want to display them in, so sort them first.
 
     .. sourcecode:: jinja
 
-- 
2.47.2