internet/community.general
3
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2026-05-06 13:22:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update info on python support (#38855)

Browse Source 
* Update the documentation to list Python 3 as official
* Add some reference targets for inventory variables so we can link to docs
* Add a platform FAQ section
  Populate it with

  * virtualenv info (previously on the python3 support page)
  * BSD (Link to the working with BSD page)
  * Solaris (Document how to work around the non-POSIX shell on some
    Solaris hosts)

  Fixes #21594

* Fix some refs in the release_and_maintenance document

* Fix unindent error in module template

Fix for the module/plugin template unintentionally unindented inside of
a raw block, leading to errors like:

ERROR: docs/docsite/rst/modules/redshift_facts_module.rst:289:0: Explicit markup ends without a blank line; unexpected unindent.

* Make wording for Solaris troubleshooting better.
This commit is contained in:
Toshio Kuratomi
2018-04-18 13:04:47 -07:00
committed by GitHub
parent c1ae1c8251
commit a08459a814
6 changed files with 166 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/docsite/rst/reference_appendices/python_3_support.rst
View File

@@ -2,45 +2,32 @@
Python 3 Support
================
Ansible 2.2, 2.3, and 2.4 feature a tech preview of Python 3 support. This topic discusses how you can test to make sure your modules and playbooks work with Python 3.
Ansible 2.5 and above have support for Python 3. Previous to 2.5, the Python 3 support was
considered a tech preview. This topic discusses how to setup your controller and managed machines
to use Python 3.
.. note:: Ansible supports Python version 3.5 and above only.
On the controller side
----------------------
.. note:: Technology preview features provide early access to upcoming product innovations,
enabling you to test functionality and provide feedback during the development process.
Please be aware that tech preview features may not be functionally complete and are not
intended for production use. To report a Python 3 bug, please see `Community Information & Contributing <http://docs.ansible.com/ansible/community.html#i-d-like-to-report-a-bug>`_.
Testing Python 3 with commands and playbooks
--------------------------------------------
* Run Ansible 2.2+ - See :ref:`from_source`
* To test Python 3 on the controller, run your ansible command via
``python3``. For example:
The easiest way to run :command:`/usr/bin/ansible` under Python 3 is to install it with the Python3
version of pip. This will make the default :command:`/usr/bin/ansible` run with Python3:
.. code-block:: shell
$ python3 /usr/bin/ansible localhost -m ping
$ python3 /usr/bin/ansible-playbook sample-playbook.yml
You can also install Ansible using :program:`pip` for Python3 which will make the default
:command:`/usr/bin/ansible` run with Python3:
.. code-block:: shell
$ virtualenv --python=python3 py3-ansible
$ source ./py3-ansible/bin/activate
$ pip3 install ansible
$ ansible --version | grep "python version"
python version = 3.6.2 (default, Sep 22 2017, 08:28:09) [GCC 7.2.1 20170915 (Red Hat 7.2.1-2)]
On systems with SELinux installed, such as Red Hat Enterprise Linux or Fedora, the SELinux Python libraries also need to be copied over.
If you are running Ansible :ref:`from_source` and want to use Python 3 with your source checkout, run your
command via ``python3``. For example:
.. code-block:: shell
$ cp -r -v /usr/lib64/python3.*/site-packages/selinux/ ./py3-ansible/lib64/python3.*/site-packages/
$ cp -v /usr/lib64/python3.*/site-packages/*selinux*.so ./py3-ansible/lib64/python3.*/site-packages/
$ source ./hacking/env-setup
$ python3 $(which ansible) localhost -m ping
$ python3 $(which ansible-playbook) sample-playbook.yml
.. note:: Individual Linux distribution packages may be packaged for Python2 or Python3. When running from
distro packages you'll only be able to use Ansible with the Python version for which it was
@@ -49,23 +36,27 @@ On systems with SELinux installed, such as Red Hat Enterprise Linux or Fedora, t
with your distro to see if that applies in your case.
Testing Python 3 module support
--------------------------------
Using Python 3 on the managed machines with commands and playbooks
------------------------------------------------------------------
* Set the ansible_python_interpreter configuration option to
:command:`/usr/bin/python3`. The ``ansible_python_interpreter`` configuration option is
usually set per-host as an inventory variable associated with a host or group of hosts:
* Set the ``ansible_python_interpreter`` configuration option to :command:`/usr/bin/python3`. The
``ansible_python_interpreter`` configuration option is usually set as an inventory
variable associated with a host or group of hosts:
.. code-block:: ini
# Example inventory that makes an alias for localhost that uses python3
# Example inventory that makes an alias for localhost that uses Python3
localhost-py3 ansible_host=localhost ansible_connection=local ansible_python_interpreter=/usr/bin/python3
# Example of setting a group of hosts to use Python3
[py3-hosts]
localhost-py3 ansible_host=localhost ansible_connection=local
ubuntu16
fedora27
[py3-hosts:vars]
ansible_python_interpreter=/usr/bin/python3
See :ref:`intro_inventory` for more information.
.. seealso:: :ref:`intro_inventory` for more information.
* Run your command or playbook:
@@ -76,7 +67,8 @@ See :ref:`intro_inventory` for more information.
Note that you can also use the `-e` command line option to manually
set the python interpreter when you run a command. For example:
set the python interpreter when you run a command. This can be useful if you want to test whether
a specific module or playbook has any bugs under Python 3. For example:
.. code-block:: shell
@@ -86,10 +78,14 @@ set the python interpreter when you run a command. For example:
What to do if an incompatibility is found
-----------------------------------------
If you find a bug while testing modules with Python3 you can submit a bug
report on `Ansible's GitHub project
<https://github.com/ansible/ansible/issues/>`_. Be sure to mention Python3 in
the bug report so that the right people look at it.
We have spent several releases squashing bugs and adding new tests so that Ansible's core feature
set runs under both Python 2 and Python 3. However, bugs may still exist in edge cases and many of
the modules shipped with Ansible are maintained by the community and not all of those may be ported
yet.
If you find a bug running under Python 3 you can submit a bug report on `Ansible's GitHub project
<https://github.com/ansible/ansible/issues/>`_. Be sure to mention Python3 in the bug report so
that the right people look at it.
If you would like to fix the code and submit a pull request on github, you can
refer to :ref:`developing_python3` for information on how we fix