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/units/executor/module_common/test_modify_module.py

@@ -27,10 +27,11 @@ def fake_old_module_open(mocker):
     else:
         mocker.patch('builtins.open', m)
 
-
-def test_shebang(fake_old_module_open, templar):
-    (data, style, shebang) = modify_module('fake_module', 'fake_path', {}, templar)
-    assert shebang == '#!/usr/bin/python'
+# this test no longer makes sense, since a Python module will always either have interpreter discovery run or
+# an explicit interpreter passed (so we'll never default to the module shebang)
+# def test_shebang(fake_old_module_open, templar):
+#     (data, style, shebang) = modify_module('fake_module', 'fake_path', {}, templar)
+#     assert shebang == '#!/usr/bin/python'
 
 
 def test_shebang_task_vars(fake_old_module_open, templar):

test/units/executor/module_common/test_module_common.py

@@ -24,6 +24,7 @@ import pytest
 import ansible.errors
 
 from ansible.executor import module_common as amc
+from ansible.executor.interpreter_discovery import InterpreterDiscoveryRequiredError
 from ansible.module_utils.six import PY2
 
 
@@ -105,7 +106,10 @@ def templar():
 class TestGetShebang(object):
     """Note: We may want to change the API of this function in the future.  It isn't a great API"""
     def test_no_interpreter_set(self, templar):
-        assert amc._get_shebang(u'/usr/bin/python', {}, templar) == (None, u'/usr/bin/python')
+        # normally this would return /usr/bin/python, but so long as we're defaulting to auto python discovery, we'll get
+        # an InterpreterDiscoveryRequiredError here instead
+        with pytest.raises(InterpreterDiscoveryRequiredError):
+            amc._get_shebang(u'/usr/bin/python', {}, templar)
 
     def test_non_python_interpreter(self, templar):
         assert amc._get_shebang(u'/usr/bin/ruby', {}, templar) == (None, u'/usr/bin/ruby')

test/units/plugins/action/test_action.py

@@ -133,7 +133,6 @@ class TestActionBase(unittest.TestCase):
         mock_module_loader.find_plugin.side_effect = mock_find_plugin
         mock_shared_obj_loader = MagicMock()
         mock_shared_obj_loader.module_loader = mock_module_loader
-        mock_templar = MagicMock()
 
         # we're using a real play context here
         play_context = PlayContext()
@@ -144,7 +143,7 @@ class TestActionBase(unittest.TestCase):
             connection=mock_connection,
             play_context=play_context,
             loader=fake_loader,
-            templar=mock_templar,
+            templar=Templar(loader=fake_loader),
             shared_loader_obj=mock_shared_obj_loader,
         )
 
@@ -153,7 +152,8 @@ class TestActionBase(unittest.TestCase):
             with patch.object(os, 'rename'):
                 mock_task.args = dict(a=1, foo='fö〩')
                 mock_connection.module_implementation_preferences = ('',)
-                (style, shebang, data, path) = action_base._configure_module(mock_task.action, mock_task.args)
+                (style, shebang, data, path) = action_base._configure_module(mock_task.action, mock_task.args,
+                                                                             task_vars=dict(ansible_python_interpreter='/usr/bin/python'))
                 self.assertEqual(style, "new")
                 self.assertEqual(shebang, u"#!/usr/bin/python")