Python interpreter discovery (#50163)

* Python interpreter discovery

* No longer blindly default to only `/usr/bin/python`
* `ansible_python_interpreter` defaults to `auto_legacy`, which will discover the platform Python interpreter on some platforms (but still favor `/usr/bin/python` if present for backward compatibility). Use `auto` to always use the discovered interpreter, append `_silent` to either value to suppress warnings.
* includes new doc utility method `get_versioned_doclink` to generate a major.minor versioned doclink against docs.ansible.com (or some other config-overridden URL)

* docs revisions for python interpreter discovery

(cherry picked from commit 5b53c0012ab7212304c28fdd24cb33fd8ff755c2)

* verify output on some distros, cleanup

test/integration/targets/interpreter_discovery_python/aliases

@@ -0,0 +1,2 @@
+shippable/posix/group1
+non_local # workaround to allow override of ansible_python_interpreter; disables coverage on this integration target

test/integration/targets/interpreter_discovery_python/library/test_echo_module.py

@@ -0,0 +1,29 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
+# (c) 2016, Toshio Kuratomi <tkuratomi@ansible.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+import sys
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    result = dict(changed=False)
+
+    module = AnsibleModule(argument_spec=dict(
+        facts=dict(type=dict, default={})
+    ))
+
+    result['ansible_facts'] = module.params['facts']
+    result['running_python_interpreter'] = sys.executable
+
+    module.exit_json(**result)
+
+
+if __name__ == '__main__':
+    main()

test/integration/targets/interpreter_discovery_python/tasks/main.yml

@@ -0,0 +1,145 @@
+- name: ensure we can override ansible_python_interpreter
+  vars:
+    ansible_python_interpreter: overriddenpython
+  assert:
+    that:
+    - ansible_python_interpreter == 'overriddenpython'
+    fail_msg: "'ansible_python_interpreter' appears to be set at a high precedence to {{ ansible_python_interpreter }},
+              which breaks this test."
+
+- name: snag some facts to validate for later
+  set_fact:
+    distro: '{{ ansible_distribution | default("unknown") | lower }}'
+    distro_version: '{{ ansible_distribution_version | default("unknown") }}'
+    os_family: '{{ ansible_os_family | default("unknown") }}'
+
+- name: test that python discovery is working and that fact persistence makes it only run once
+  block:
+  - name: clear facts to force interpreter discovery to run
+    meta: clear_facts
+
+  - name: trigger discovery with auto
+    vars:
+      ansible_python_interpreter: auto
+    ping:
+    register: auto_out
+
+  - name: get the interpreter being used on the target to execute modules
+    vars:
+      # keep this set so we can verify we didn't repeat discovery
+      ansible_python_interpreter: auto
+    test_echo_module:
+    register: echoout
+
+  - assert:
+      that:
+      - auto_out.ansible_facts.discovered_interpreter_python is defined
+      - echoout.running_python_interpreter == auto_out.ansible_facts.discovered_interpreter_python
+      # verify that discovery didn't run again (if it did, we'd have the fact in the result)
+      - echoout.ansible_facts is not defined or echoout.ansible_facts.discovered_interpreter_python is not defined
+
+
+- name: test that auto_legacy gives a dep warning when /usr/bin/python present but != auto result
+  block:
+  - name: clear facts to force interpreter discovery to run
+    meta: clear_facts
+
+  - name: trigger discovery with auto_legacy
+    vars:
+      ansible_python_interpreter: auto_legacy
+    ping:
+    register: legacy
+
+  - name: check for dep warning (only on platforms where auto result is not /usr/bin/python and legacy is)
+    assert:
+      that:
+      - legacy.deprecations | default([]) | length > 0
+    # only check for a dep warning if legacy returned /usr/bin/python and auto didn't
+    when: legacy.ansible_facts.discovered_interpreter_python == '/usr/bin/python' and
+          auto_out.ansible_facts.discovered_interpreter_python != '/usr/bin/python'
+
+
+- name: test that auto_silent never warns and got the same answer as auto
+  block:
+  - name: clear facts to force interpreter discovery to run
+    meta: clear_facts
+
+  - name: initial task to trigger discovery
+    vars:
+      ansible_python_interpreter: auto_silent
+    ping:
+    register: auto_silent_out
+
+  - assert:
+      that:
+      - auto_silent_out.warnings is not defined
+      - auto_silent_out.ansible_facts.discovered_interpreter_python == auto_out.ansible_facts.discovered_interpreter_python
+
+
+- name: test that auto_legacy_silent never warns and got the same answer as auto_legacy
+  block:
+  - name: clear facts to force interpreter discovery to run
+    meta: clear_facts
+
+  - name: trigger discovery with auto_legacy_silent
+    vars:
+      ansible_python_interpreter: auto_legacy_silent
+    ping:
+    register: legacy_silent
+
+  - assert:
+      that:
+        - legacy_silent.warnings is not defined
+        - legacy_silent.ansible_facts.discovered_interpreter_python == legacy.ansible_facts.discovered_interpreter_python
+
+- name: ensure modules can't set discovered_interpreter_X or ansible_X_interpreter
+  block:
+  - test_echo_module:
+      facts:
+        ansible_discovered_interpreter_bogus: from module
+        discovered_interpreter_bogus: from_module
+        ansible_bogus_interpreter: from_module
+        test_fact: from_module
+    register: echoout
+
+  - assert:
+      that:
+      - test_fact == 'from_module'
+      - discovered_interpreter_bogus | default('nope') == 'nope'
+      - ansible_bogus_interpreter | default('nope') == 'nope'
+      # this one will exist in facts, but with its prefix removed
+      - ansible_facts['ansible_bogus_interpreter'] | default('nope') == 'nope'
+      - ansible_facts['discovered_interpreter_bogus'] | default('nope') == 'nope'
+
+  - name: fedora assertions
+    assert:
+      that:
+      - auto_out.ansible_facts.discovered_interpreter_python == '/usr/bin/python3'
+    when: distro == 'fedora' and distro_version is version('23', '>=')
+
+  - name: rhel assertions
+    assert:
+      that:
+      # rhel 6/7
+      - (auto_out.ansible_facts.discovered_interpreter_python == '/usr/bin/python' and distro_version is version('8','<')) or distro_version is version('8','>=')
+      # rhel 8+
+      - (auto_out.ansible_facts.discovered_interpreter_python == '/usr/libexec/platform-python' and distro_version is version('8','>=')) or distro_version is version('8','<')
+    when: distro == 'redhat'
+
+  - name: ubuntu assertions
+    assert:
+      that:
+      # ubuntu < 16
+      - (auto_out.ansible_facts.discovered_interpreter_python == '/usr/bin/python' and distro_version is version('16.04','<')) or distro_version is version('16.04','>=')
+      # ubuntu >= 16
+      - (auto_out.ansible_facts.discovered_interpreter_python == '/usr/bin/python3' and distro_version is version('16.04','>=')) or distro_version is version('16.04','<')
+    when: distro == 'ubuntu'
+
+  - name: mac assertions
+    assert:
+      that:
+      - auto_out.ansible_facts.discovered_interpreter_python == '/usr/bin/python'
+    when: os_family == 'darwin'
+
+  always:
+  - meta: clear_facts