update wording on dictionary default ordering

diff --git a/docs/templates.rst b/docs/templates.rst
index 6226468dbf8153255063b2caeda7cc1eefbf35f5..1826bbcb9f31c9535242cdfdbfa0272eaae66f47 100644 (file)
--- 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 5ff0bdde51add80c9bd274a77d76dee8650d1fd4..af9a45248ca1d746139c9abd4996f516feff7bb2 100644 (file)
--- 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