[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.
pull/22728/head
Toshio Kuratomi 8 years ago committed by GitHub
parent f5f6cf467e
commit 8de05d3752

@ -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

@ -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

@ -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).

@ -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.

@ -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:

@ -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").

@ -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
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,23 +259,39 @@ 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)
.. note:: Old exception syntax
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::
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
[...]
@ -291,14 +300,22 @@ construction to make this work under both Python-2.4 and Python-3::
a = 2/0
except ValueError:
e = get_exception()
module.fail_json(msg="Tried to divide by zero!")
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)
@ -306,40 +323,22 @@ modules should create their octals like this::
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.
Compile Test
------------
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.
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.

@ -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.

@ -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

@ -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>`_

Loading…
Cancel
Save