Add documentation of Jinja2 templating idioms that differ when run under Python3

Fixes #19514

3 files changed, 75 insertions, 1 deletions

diff --git a/docs/docsite/rst/playbooks_python_version.rst b/docs/docsite/rst/playbooks_python_version.rst
new file mode 100644
index 0000000000..519fff3f37
--- /dev/null
+++ b/docs/docsite/rst/playbooks_python_version.rst
@@ -0,0 +1,69 @@
+.. _pb-py-compat:
+
+Python Version and Templating
+=============================
+
+Jinja2 templates leverage Python data types and standard functions.  This
+makes for a rich set of operations that can be performed on data.  However,
+this also means that certain specifics of the underlying Python becomes
+visible to template authors.  Since Ansible playbooks use Jinja2 for templates
+and variables, this means that playbook authors need to be aware of these
+specifics as well.
+
+Unless otherwise noted, these differences are only of interest when running
+Ansible in Python2 versus Python3.  Changes within Python2 and Python3 are
+generally small enough that they are not visible at the jinja2 level.
+
+.. _pb-py-compat-dict-views:
+
+Dictionary Views
+----------------
+
+In Python2, the :meth:`dict.keys`, :meth:`dict.values`, and :meth:`dict.items`
+methods returns a list.  Jinja2 returns that to Ansible via a string
+representation that Ansible can turn back into a list.  In Python3, those
+methods returns a :ref:`dictionary view <python3:dict-views>` object.  The
+string representation that Jinja2 returns for dictionary views is not parsable
+by Ansible back into a list.  It is, however, easy to make this portable by
+using the :func:`list <jinja2:list>` filter whenever using :meth:`dict.keys`,
+:meth:`dict.values`, or :meth:`dict.items`::
+
+    vars:
+      hosts:
+        testhost1: 127.0.0.2
+        testhost2: 127.0.0.3
+    tasks:
+      - debug:
+          msg: '{{ item }}'
+        # Only works with Python 2
+        #with_items: "{{ hosts.keys() }}"
+        # Works with both Python 2 and Python 3
+        with_items: "{{ hosts.keys() | list }}"
+
+.. _pb-py-compat-iteritems:
+
+dict.iteritems()
+----------------
+
+In Python2, dictionaries have :meth:`~dict.iterkeys`,
+:meth:`~dict.itervalues`, and :meth:`~dict.iteritems` methods.  These methods
+have been removed in Python3.  Playbooks and Jinja2 templates should use
+:meth:`dict.keys`, :meth:`dict.values`, and :meth:`dict.items` in order to be
+compatible with both Python2 and Python3::
+
+    vars:
+      hosts:
+        testhost1: 127.0.0.2
+        testhost2: 127.0.0.3
+    tasks:
+      - debug:
+          msg: '{{ item }}'
+        # Only works with Python 2
+        #with_items: "{{ hosts.iteritems() }}"
+        # Works with both Python 2 and Python 3
+        with_items: "{{ hosts.items() | list }}"
+
+.. seealso::
+    * The :ref:`pb-py-compat-dict-views` entry for information on
+      why the :func:`list filter <jinja2:list>` is necessary
+      here.
diff --git a/docs/docsite/rst/playbooks_templating.rst b/docs/docsite/rst/playbooks_templating.rst
index bae594f71f..62a6f04ea0 100644
--- a/docs/docsite/rst/playbooks_templating.rst
+++ b/docs/docsite/rst/playbooks_templating.rst
@@ -14,7 +14,7 @@ Please note that all templating happens on the Ansible controller before the tas
    playbooks_filters
    playbooks_tests
    playbooks_lookups
-
+   playbooks_python_version
 
 
 .. seealso::
diff --git a/docs/docsite/rst/playbooks_variables.rst b/docs/docsite/rst/playbooks_variables.rst
index 1921fe3d7b..68282f6d0c 100644
--- a/docs/docsite/rst/playbooks_variables.rst
+++ b/docs/docsite/rst/playbooks_variables.rst
@@ -124,6 +124,11 @@ it's more than that -- you can also read variables about other hosts.  We'll sho
    pieces of files, or to have other ecosystem tools read Ansible files.  Not everyone will need this but it can unlock
    possibilities.
 
+.. seealso::
+
+    :doc:`playbooks_templating`
+        More information about Jinja2 templating
+
 .. _jinja2_filters:
 
 Jinja2 Filters