[WIP] Documentation: Ansible-2.4 no longer supports Python-2.4 and Python-2.5 (#22721)

* Documentation: Ansible-2.4 no longer supports Python-2.4 and Python-2.5
* Switched to bullet points to enhance readability.

CHANGELOG.md

@@ -8,6 +8,10 @@ Ansible Changes By Release
 * Added fact namespacing, from now on facts will be available under 'ansible_facts' namespace (i.e. `ansible_facts.ansible_os_distribution`), they will still also be added into the main namespace directly but now also having a configuration toggle to disable this. Eventually this will be on by default. This is done to avoid collisions and possible security issues as facts come from the remote targets and they might be compromised.
 * new 'order' play level keyword that allows the user to change the order in which Ansible processes hosts when dispatching tasks.
 * Users can now set group merge priority for groups of the same depth (parent child relationship), using the new `ansible_group_priority` variable, when values are the same or don't exist it will fallback to the previous 'sorting by name'.
+* Support for Python-2.4 and Python-2.5 on the managed system's side was
+  dropped.  If you need to manage a system that ships with Python-2.4 or
+  Python-2.5 you'll need to install Python-2.6 or better there or run
+  Ansible-2.3 until you can upgrade the system.
 
 #### New: Tests
 - any : true if any element is true

docs/docsite/rst/community.rst

@@ -174,11 +174,15 @@ Contributions can be for new features like modules, or to fix bugs you or others
 are interested in writing new modules to be included in the core Ansible distribution, please refer
 to the `module development documentation <http://docs.ansible.com/developing_modules.html>`_.
 
-Ansible's aesthetic encourages simple, readable code and consistent, conservatively extending,
-backwards-compatible improvements.  Code developed for Ansible needs to support Python 2.6+,
-while code in modules must run under Python 2.4 or higher.  Please also use a 4-space indent
-and no tabs, we do not enforce 80 column lines, we are fine with 120-140. We do not take 'style only'
-requests unless the code is nearly unreadable, we are "PEP8ish", but not strictly compliant.
+Ansible's aesthetic encourages simple, readable code and consistent,
+conservatively extending, backwards-compatible improvements. When contributing code to Ansible, 
+please observe the following guidelines:
+
+- Code developed for Ansible needs to support Python2-2.6 or higher and Python3-3.5 or higher.
+- Use a 4-space indent, not  tabs.
+- We do not enforce 80 column lines; up to 160 columns are acceptable.
+- We do not accept 'style only' pull requests unless the code is nearly unreadable.
+- We are "PEP8ish", but not strictly compliant.
 
 You can also contribute by testing and revising other requests, especially if it is one you are interested
 in using. Please keep your comments clear and to the point, courteous and constructive, tickets are not a

docs/docsite/rst/dev_guide/developing_module_utilities.rst

@@ -36,7 +36,7 @@ The following is a list of module_utils files and a general description. The mod
 - openstack.py - Utilities for modules that work with Openstack instances.
 - openswitch.py - Definitions and helper functions for modules that manage OpenSwitch devices
 - powershell.ps1 - Utilities for working with Microsoft Windows clients
-- pycompat24.py - Exception workaround for python 2.4
+- pycompat24.py - Exception workaround for Python 2.4.
 - rax.py -  Definitions and helper functions for modules that work with Rackspace resources.
 - redhat.py - Functions for modules that manage Red Hat Network registration and subscriptions
 - service.py - Contains utilities to enable modules to work with Linux services (placeholder, not in use).

docs/docsite/rst/dev_guide/developing_modules.rst

@@ -60,7 +60,7 @@ The following topics will discuss how to develop and work with modules:
 :doc:`developing_modules_checklist`
      Checklist for contributing your module to Ansible.
 :doc:`developing_modules_python3`
-    Adding Python 3 support to modules (all new modules must be py2.4 and py3 compatible).
+    Adding Python 3 support to modules (all new modules must be Python-2.6 and Python-3.5 compatible).
 :doc:`developing_modules_in_groups`
     A guide for partners wanting to submit multiple modules.
 

docs/docsite/rst/dev_guide/developing_modules_checklist.rst

@@ -22,7 +22,7 @@ Contributing Modules Checklist
 The following  checklist items are important guidelines for people who want to contribute to the development of modules to Ansible on GitHub. Please read the guidelines before you submit your PR/proposal.
 
 * The shebang must always be ``#!/usr/bin/python``.  This allows ``ansible_python_interpreter`` to work
-* Modules must be written to support Python 2.4. If this is not possible, required minimum python version and rationale should be explained in the requirements section in ``DOCUMENTATION``.  This minimum requirement will be advanced to Python-2.6 in Ansible-2.4.
+* Modules must be written to support Python 2.6. If this is not possible, required minimum Python version and rationale should be explained in the requirements section in ``DOCUMENTATION``.  In Ansible-2.3 the minimum requirement for modules was Python-2.4.
 * Modules must be written to use proper Python-3 syntax.  At some point in the future we'll come up with rules for running on Python-3 but we're not there yet.  See :doc:`developing_modules_python3` for help on how to do this.
 * Modules must have a metadata section.  For the vast majority of new modules,
   the metadata should look exactly like this:

docs/docsite/rst/dev_guide/developing_modules_in_groups.rst

@@ -26,7 +26,7 @@ Although it's tempting to get straight into coding, there are a few things to be
 * Shared code can be placed into ``lib/ansible/module_utils/``
 * Shared documentation (for example describing common arguments) can be placed in ``lib/ansible/utils/module_docs_fragments/``.
 * With great power comes great responsiblity: Ansible module maintainers have a duty to help keep modules up to date. As with all successful community projects, module maintainers should keep a watchful eye for reported issues and contributions.
-* Although not required, unit and/or integration tests are strongly recomended. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see ``test/`` and the `Testing Working Group <https://github.com/ansible/community/blob/master/MEETINGS.md>`_.
+* Although not required, unit and/or integration tests are strongly recommended. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see ``test/`` and the `Testing Working Group <https://github.com/ansible/community/blob/master/MEETINGS.md>`_.
 
 Naming Convention
 `````````````````
@@ -91,7 +91,7 @@ And that's it.
 
 Before pushing your PR to GitHub it's a good idea to review the :doc:`developing_modules_checklist` again.
 
-After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :doc:`../YAMLSyntax`) or code that isn't valid Python 2.4 & Python 2.6 (see :doc:`developing_modules_python3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review.
+After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :doc:`../YAMLSyntax`) or code that isn't valid Python 2.6  or valid Python 3.5 (see :doc:`developing_modules_python3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review.
 
 If you need further advice, consider join the ``#ansible-devel`` IRC channel (see how in the "Where to get support").
 

docs/docsite/rst/dev_guide/developing_modules_python3.rst

@@ -20,31 +20,27 @@ pieces but there are some special considerations for some of it as well.
 Minimum Version of Python-3.x and Python-2.x
 --------------------------------------------
 
-In controller side code, we support Python-3.5 or greater and Python-2.6 or
-greater.
-
-For modules (and by extension, module_utils) we support
-Python-3.5 and Python-2.4. Python-3.5 was chosen as a minimum because it is the earliest Python-3 version
-adopted as the default Python by a Long Term Support (LTS) Linux distribution (in this case, Ubuntu-16.04).  
+In both controller side and module code, we support Python-3.5 or greater and Python-2.6 or
+greater.  Python-3.5 was chosen as a minimum because it is the earliest Python-3 version
+adopted as the default Python by a Long Term Support (LTS) Linux distribution (in this case, Ubuntu-16.04).
 Previous LTS Linux distributions shipped with a Python-2 version which users can rely upon instead of the 
 Python-3 version.
 
-For Python-2, the default is for modules to run on Python-2.4.  This allows
-users with older distributions that are stuck on Python-2.4 to manage their
-machines.  Modules are allowed to drop support for Python-2.4 when one of
+For Python-2, the default is for modules to run on at least Python-2.6.  This allows
+users with older distributions that are stuck on Python-2.6 to manage their
+machines.  Modules are allowed to drop support for Python-2.6 when one of
 their dependent libraries requires a higher version of Python.  This is not an
 invitation to add unnecessary dependent libraries in order to force your
-module to be usable only with a newer version of Python.; instead it is an
+module to be usable only with a newer version of Python; instead it is an
 acknowledgment that some libraries (for instance, boto3 and docker-py) will
 only function with a newer version of Python.
 
-.. note:: Python-2.4 Support:
+.. note:: Python-2.4 Module-side Support:
 
-    The only long term supported distro that we know of with Python-2.4 support is
-    RHEL5 (and its rebuilds like CentOS5), which is supported until April of
-    2017.  For Ansible, that means Ansible-2.3 will be the last major release
-    that supports Python-2.4 for modules.  Ansible-2.4 will require
-    Python-2.6 or greater for modules.
+    Support for Python-2.4 and Python-2.5 was dropped in Ansible-2.4.  RHEL-5
+    (and its rebuilds like CentOS-5) were supported until April of 2017.
+    Ansible-2.3 was released in April of 2017 and was the last Ansible release
+    to support Python-2.4 on the module-side.
 
 -----------------------------------
 Porting Controller Code to Python 3
@@ -248,13 +244,10 @@ than text.
 Porting Modules to Python 3
 ---------------------------
 
-Ansible modules are not the usual Python-3 porting exercise.  There are two
-factors that make it harder to port them than most code:
-
-1. Many modules need to run on Python-2.4 in addition to Python-3.
-2. A lot of mocking has to go into unit testing a Python-3 module, so it's
-   harder to test that your porting has fixed everything or to to make sure that
-   later commits haven't regressed.
+Ansible modules are slightly harder to port than normal code from other
+projects. A lot of mocking has to go into unit testing an Ansible module so
+it's harder to test that your porting has fixed everything or to to make sure
+that later commits haven't regressed the Python-3 support.
 
 Module String Strategy
 ======================
@@ -266,80 +259,86 @@ mandating that all strings inside of modules are text and converting between
 text and bytes at the borders; instead, we're using a native string strategy
 for now.
 
+Native strings refer to the type that Python uses when you specify a bare
+string literal:
+
+.. code-block:: python
+
+    "This is a native string"
+
+In Python-2, these are byte strings.  In Python-3 these are text strings.  The
+module_utils shipped with Ansible attempts to accept native strings as input
+to its functions and emit native strings as their output.  Modules should be
+coded to expect bytes on Python-2 and text on Python-3.
+
 Tips, tricks, and idioms to adopt
 =================================
 
 Exceptions
 ----------
 
-In code which already needs Python-2.6+ (for instance, because a library it
-depends on only runs on Python >= 2.6) it is okay to port directly to the new
-exception-catching syntax::
+In order for code to function on Python-2.6+ and Python-3, use the
+new exception-catching syntax which uses the ``as`` keyword::
 
     try:
         a = 2/0
     except ValueError as e:
-        module.fail_json(msg="Tried to divide by zero!")
+        module.fail_json(msg="Tried to divide by zero: %s" % e)
 
-For modules which also run on Python-2.4, we have to use an uglier
-construction to make this work under both Python-2.4 and Python-3::
 
-    from ansible.module_utils.pycompat24 import get_exception
-    [...]
+.. note:: Old exception syntax
 
-    try:
-        a = 2/0
-    except ValueError:
-        e = get_exception()
-        module.fail_json(msg="Tried to divide by zero!")
+    Until Ansible-2.4, modules needed to be compatible with Python-2.4 as
+    well.  Python-2.4 did not understand the new exception-catching syntax so
+    we had to write a compatibility function that could work with both
+    Python-2 and Python-3.  You may still see this used in some modules::
+
+        from ansible.module_utils.pycompat24 import get_exception
+        [...]
+
+        try:
+            a = 2/0
+        except ValueError:
+            e = get_exception()
+            module.fail_json(msg="Tried to divide by zero: %s" % e)
+
+    Unless a change is going to be backported to Ansible-2.3, you should not
+    have to use this in new code.
 
 Octal numbers
 -------------
 
-In Python-2.4, octal literals are specified as ``0755``.  In Python-3, that is
-invalid and octals must be specified as ``0o755``.  To bridge this gap,
-modules should create their octals like this::
+In Python-2.6, octal literals could be specified as ``0755``.  In Python-3, that is
+invalid and octals must be specified as ``0o755``.
+
+.. note:: Workaround from Python-2.4 era
+
+    Before Ansible-2.4, modules had to be compatible with Python-2.4.
+    Python-2.4 did not understand the new syntax for octal literals so we used
+    the following workaround to specify octal values::
 
-    # Can't use 0755 on Python-3 and can't use 0o755 on Python-2.4
-    EXECUTABLE_PERMS = int('0755', 8)
+        # Can't use 0755 on Python-3 and can't use 0o755 on Python-2.4
+        EXECUTABLE_PERMS = int('0755', 8)
 
 Bundled six
 -----------
 
-The third-party python-six library exists to help projects create code that
-runs on both Python-2 and Python-3.  Ansible includes version 1.4.1 in
-module_utils so that other modules can use it without requiring that it is
-installed on the remote system.  To make use of it, import it like this::
+The third-party `python-six <https://pythonhosted.org/six/>`_ library exists
+to help projects create code that runs on both Python-2 and Python-3.  Ansible
+includes version 1.4.1 in module_utils so that other modules can use it
+without requiring that it is installed on the remote system.  To make use of
+it, import it like this::
 
     from ansible.module_utils import six
 
 .. note:: Why version 1.4.1?
 
-    six-1.4.1 is the last version of python-six to support Python-2.4.  As
-    long as Ansible modules need to run on Python-2.4 we won't be able to
-    update the bundled copy of six.
+    six-1.4.1 is the last version of python-six to support Python-2.4.  Until
+    Ansible-2.4, most Ansible modules were required to run on Python-2.4.  So
+    the bundled version of six could not be newer than 1.4.1.
 
-Compile Test
-------------
-
-We have travis compiling all modules with various versions of Python to check
-that the modules conform to the syntax at those versions.  When you've
-ported a module so that its syntax works with Python-3, we need to modify
-.travis.yml so that the module is included in the syntax check.  Here's the
-relevant section of .travis.yml::
-
-    env:
-      global:
-        - PY3_EXCLUDE_LIST="cloud/amazon/cloudformation.py
-          cloud/amazon/ec2_ami.py
-          [...]
-          utilities/logic/wait_for.py"
-
-The :envvar:`PY3_EXCLUDE_LIST` environment variable is a blacklist of modules
-which should not be tested (because we know that they are older modules which
-have not yet been ported to pass the Python-3 syntax checks.  To get another
-old module to compile with Python-3, remove the entry for it from the list.
-The goal is to have the LIST be empty.
+    Ansible-2.4 now targets Python-2.6 or greater for modules.  We'll be
+    updating the bundled six soon.
 
 -------------------------------------
 Porting module_utils code to Python 3
@@ -360,4 +359,3 @@ Functions which return strings **must** document whether they return text,
 byte, or native strings. Module-utils functions are therefore often very
 defensive in nature, converting from potential text or bytes at the
 beginning of a function and converting to the native string type at the end.
-

docs/docsite/rst/dev_guide/developing_program_flow_modules.rst

@@ -330,8 +330,8 @@ ansible module.
 .. note::
     Ansible wraps the zipfile in the Python script for two reasons:
 
-    * for compatibility with Python-2.4 and Python-2.6 which have less
-      featureful versions of Python's ``-m`` command line switch.
+    * for compatibility with Python-2.6 which has a less
+      functional version of Python's ``-m`` command line switch.
     * so that pipelining will function properly.  Pipelining needs to pipe the
       Python module into the Python interpreter on the remote node.  Python
       understands scripts on stdin but does not understand zip files.

docs/docsite/rst/faq.rst

@@ -112,7 +112,7 @@ While you can write ansible modules in any language, most ansible modules are wr
 are important core ones.
 
 By default Ansible assumes it can find a /usr/bin/python on your remote system that is a 2.X version of Python, specifically
-2.4 or higher.
+2.6 or higher.
 
 Setting of an inventory variable 'ansible_python_interpreter' on any host will allow Ansible to auto-replace the interpreter
 used when executing python modules.   Thus, you can point to any python you want on the system if /usr/bin/python on your

docs/docsite/rst/intro_installation.rst

@@ -66,10 +66,9 @@ This includes Red Hat, Debian, CentOS, OS X, any of the BSDs, and so on.
 Managed Node Requirements
 `````````````````````````
 
-On the managed nodes, you need a way to communicate, which is normally ssh. By default this uses sftp. If that's not available, you can switch to scp in ansible.cfg.
-You also need Python 2.4 or later. If you are running less than Python 2.5 on the remotes, you will also need:
-
-* ``python-simplejson``
+On the managed nodes, you need a way to communicate, which is normally ssh. By
+default this uses sftp. If that's not available, you can switch to scp in
+:file:`ansible.cfg`.  You also need Python 2.6 or later.
 
 .. note::
 
@@ -91,7 +90,7 @@ You also need Python 2.4 or later. If you are running less than Python 2.5 on th
    Ansible 2.2 introduces a tech preview of support for Python 3. For more information, see `Python 3 Support <http://docs.ansible.com/ansible/python_3_support.html>`_.
 
    By default, Ansible uses Python 2 in order to maintain compatibility with older distributions
-   such as RHEL 5 and RHEL 6. However, some Linux distributions (Gentoo, Arch) may not have a
+   such as RHEL 6. However, some Linux distributions (Gentoo, Arch) may not have a
    Python 2.X interpreter installed by default.  On those systems, you should install one, and set
    the 'ansible_python_interpreter' variable in inventory (see :doc:`intro_inventory`) to point at your 2.X Python.  Distributions
    like Red Hat Enterprise Linux, CentOS, Fedora, and Ubuntu all have a 2.X interpreter installed
@@ -118,7 +117,7 @@ RPMs are available from yum for `EPEL
 Fedora distributions.
 
 Ansible itself can manage earlier operating
-systems that contain Python 2.4 or higher (so also EL5).
+systems that contain Python 2.6 or higher (so also EL6).
 
 Fedora users can install Ansible directly, though if you are using RHEL or CentOS and have not already done so, `configure EPEL <http://fedoraproject.org/wiki/EPEL>`_