1 files changed, 68 insertions, 0 deletions
diff --git a/docs/docsite/rst/playbook_guide/playbooks_python_version.rst b/docs/docsite/rst/playbook_guide/playbooks_python_version.rst
new file mode 100644
index 0000000..ee18b60
--- /dev/null
+++ b/docs/docsite/rst/playbook_guide/playbooks_python_version.rst
@@ -0,0 +1,68 @@
+.. _pb-py-compat:
+
+********************
+Python3 in templates
+********************
+
+Ansible uses Jinja2 to take advantage of Python data types and standard functions in templates and variables.
+You can use these data types and standard functions to perform a rich set of operations on your data. However,
+if you use templates, you must be aware of differences between Python versions.
+
+These topics help you design templates that work on both Python2 and Python3. They might also help if you are upgrading from Python2 to Python3. Upgrading within Python2 or Python3 does not usually introduce changes that affect Jinja2 templates.
+
+.. _pb-py-compat-dict-views:
+
+Dictionary views
+================
+
+In Python2, the :meth:`dict.keys`, :meth:`dict.values`, and :meth:`dict.items`
+methods return a list.  Jinja2 returns that to Ansible using a string
+representation that Ansible can turn back into a list.
+
+In Python3, those methods return a :ref:`dictionary view <python3:dict-views>` object. The
+string representation that Jinja2 returns for dictionary views cannot be parsed back
+into a list by Ansible.  It is, however, easy to make this portable by
+using the :func:`list <jinja2:jinja-filters.list>` filter whenever using :meth:`dict.keys`,
+:meth:`dict.values`, or :meth:`dict.items`.
+
+.. code-block:: yaml+jinja
+
+    vars:
+      hosts:
+        testhost1: 127.0.0.2
+        testhost2: 127.0.0.3
+    tasks:
+      - debug:
+          msg: '{{ item }}'
+        # Only works with Python 2
+        #loop: "{{ hosts.keys() }}"
+        # Works with both Python 2 and Python 3
+        loop: "{{ hosts.keys() | list }}"
+
+.. _pb-py-compat-iteritems:
+
+dict.iteritems()
+================
+
+Python2 dictionaries have :meth:`~dict.iterkeys`, :meth:`~dict.itervalues`, and :meth:`~dict.iteritems` methods.
+
+Python3 dictionaries do not have these methods. Use :meth:`dict.keys`, :meth:`dict.values`, and :meth:`dict.items` to make your playbooks and templates compatible with both Python2 and Python3.
+
+.. code-block:: yaml+jinja
+
+    vars:
+      hosts:
+        testhost1: 127.0.0.2
+        testhost2: 127.0.0.3
+    tasks:
+      - debug:
+          msg: '{{ item }}'
+        # Only works with Python 2
+        #loop: "{{ hosts.iteritems() }}"
+        # Works with both Python 2 and Python 3
+        loop: "{{ hosts.items() | list }}"
+
+.. seealso::
+    * The :ref:`pb-py-compat-dict-views` entry for information on
+      why the :func:`list filter <jinja2:jinja-filters.list>` is necessary
+      here.