fix proposal for issue #25151: [python3] pip failed to create virtual env when using custom command (pyvenv) (#25241)

* Fix proposal for bug 25151

* Fix proposal for bug 25151 - pip module, pyvenv validation

* Graceful fail when virtualenv_python is defined and virtualenv_command uses the venv module

* Making sure that venv is being used as a modue "-m venv"

* Updating syntax in validations

* Updating syntax in validations - fixing stupid typo "[)"

* Raising an error if virtualenv_command is pyvenv or venv and virtualenv_python is used

* trailing whitespace gone, pyvenv, venv validation and docs update

* cleaning whitespaces from blank lines

lib/ansible/modules/packaging/language/pip.py

@@ -84,7 +84,9 @@ options:
     description:
       - The Python executable used for creating the virtual environment.
         For example C(python3.5), C(python2.7). When not specified, the
-        Python version used to run the ansible module is used.
+        Python version used to run the ansible module is used. This parameter
+        should not be used when C(virtualenv_command) is using C(pyvenv) or
+        the C(-m venv) module.
     required: false
     default: null
   state:
@@ -457,16 +459,27 @@ def main():
                     if '--no-site-packages' in cmd_opts:
                         cmd += ' --no-site-packages'
 
-                if virtualenv_python:
-                    cmd += ' -p%s' % virtualenv_python
-                elif PY3:
-                    # Ubuntu currently has a patch making virtualenv always
-                    # try to use python2.  Since Ubuntu16 works without
-                    # python2 installed, this is a problem.  This code mimics
-                    # the upstream behaviour of using the python which invoked
-                    # virtualenv to determine which python is used inside of
-                    # the virtualenv (when none are specified).
-                    cmd += ' -p%s' % sys.executable
+                # -p is a virtualenv option, not compatible with pyenv or venv
+                # this if validates if the command being used is not any of them
+                if not any(ex in module.params['virtualenv_command'] for ex in ('pyvenv', '-m venv')):
+                    if virtualenv_python:
+                        cmd += ' -p%s' % virtualenv_python
+                    elif PY3:
+                        # Ubuntu currently has a patch making virtualenv always
+                        # try to use python2.  Since Ubuntu16 works without
+                        # python2 installed, this is a problem.  This code mimics
+                        # the upstream behaviour of using the python which invoked
+                        # virtualenv to determine which python is used inside of
+                        # the virtualenv (when none are specified).
+                        cmd += ' -p%s' % sys.executable
+
+                # if venv or pyvenv are used and virtualenv_python is defined, then
+                # virtualenv_python is ignored, this has to be acknowledged
+                elif module.params['virtualenv_python']:
+                    module.fail_json(
+                        msg='virtualenv_python should not be used when'
+                            ' using the venv module or pyvenv as virtualenv_command'
+                    )
 
                 cmd = "%s %s" % (cmd, env)
                 rc, out_venv, err_venv = module.run_command(cmd, cwd=chdir)