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,6 +459,9 @@ def main():
                     if '--no-site-packages' in cmd_opts:
                         cmd += ' --no-site-packages'
 
+                # -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:
@@ -468,6 +473,14 @@ def main():
                         # 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)
                 out += out_venv