From 34a68fa0fb52128ec443830c49549adcf5d0edc6 Mon Sep 17 00:00:00 2001
From: Hannes Ljungberg <hannes@5monkeys.se>
Date: Sat, 13 Jul 2019 17:05:38 +0200
Subject: [PATCH] pip: Document option types and validate name elements

PR #58966

Also:
* Validate that name elements are strings
---
 .../fragments/58966-pip-validate-name-elements.yml  |  2 ++
 lib/ansible/modules/packaging/language/pip.py       | 13 ++++++++++++-
 2 files changed, 14 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/fragments/58966-pip-validate-name-elements.yml

diff --git a/changelogs/fragments/58966-pip-validate-name-elements.yml b/changelogs/fragments/58966-pip-validate-name-elements.yml
new file mode 100644
index 00000000000..7714ea3ac4d
--- /dev/null
+++ b/changelogs/fragments/58966-pip-validate-name-elements.yml
@@ -0,0 +1,2 @@
+bugfixes:
+  - "pip - Validate that all items in the ``name`` option are strings."
diff --git a/lib/ansible/modules/packaging/language/pip.py b/lib/ansible/modules/packaging/language/pip.py
index b20d5b38616..4dbf51a2bd8 100644
--- a/lib/ansible/modules/packaging/language/pip.py
+++ b/lib/ansible/modules/packaging/language/pip.py
@@ -24,13 +24,16 @@ options:
     description:
       - The name of a Python library to install or the url(bzr+,hg+,git+,svn+) of the remote package.
       - This can be a list (since 2.2) and contain version specifiers (since 2.7).
+    type: list
   version:
     description:
       - The version number to install of the Python library specified in the I(name) parameter.
+    type: str
   requirements:
     description:
       - The path to a pip requirements file, which should be local to the remote system.
         File can be specified as a relative path if using the chdir option.
+    type: str
   virtualenv:
     description:
       - An optional path to a I(virtualenv) directory to install into.
@@ -39,6 +42,7 @@ options:
         If the virtualenv does not exist, it will be created before installing
         packages. The optional virtualenv_site_packages, virtualenv_command,
         and virtualenv_python options affect the creation of the virtualenv.
+    type: path
   virtualenv_site_packages:
     description:
       - Whether the virtual environment will inherit packages from the
@@ -54,6 +58,7 @@ options:
       - The command or a pathname to the command to create the virtual
         environment with. For example C(pyvenv), C(virtualenv),
         C(virtualenv2), C(~/bin/virtualenv), C(/usr/local/bin/virtualenv).
+    type: path
     default: virtualenv
     version_added: "1.1"
   virtualenv_python:
@@ -63,16 +68,19 @@ options:
         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.
+    type: str
     version_added: "2.0"
   state:
     description:
       - The state of module
       - The 'forcereinstall' option is only available in Ansible 2.1 and above.
+    type: str
     choices: [ absent, forcereinstall, latest, present ]
     default: present
   extra_args:
     description:
       - Extra arguments passed to pip.
+    type: str
     version_added: "1.0"
   editable:
     description:
@@ -83,6 +91,7 @@ options:
   chdir:
     description:
       - cd into this directory before running the command
+    type: path
     version_added: "1.3"
   executable:
     description:
@@ -93,6 +102,7 @@ options:
         It cannot be specified together with the 'virtualenv' parameter (added in 2.1).
         By default, it will take the appropriate version for the python interpreter
         use by ansible, e.g. pip3 on python 3, and pip2 or pip on python 2.
+    type: path
     version_added: "1.3"
   umask:
     description:
@@ -101,6 +111,7 @@ options:
         restrictive umask by default (e.g., "0077") and you want to pip install
         packages which are to be used by all users. Note that this requires you
         to specify desired umask mode as an octal string, (e.g., "0022").
+    type: str
     version_added: "2.1"
 notes:
    - Please note that virtualenv (U(http://www.virtualenv.org/)) must be
@@ -569,7 +580,7 @@ def main():
     module = AnsibleModule(
         argument_spec=dict(
             state=dict(type='str', default='present', choices=state_map.keys()),
-            name=dict(type='list'),
+            name=dict(type='list', elements='str'),
             version=dict(type='str'),
             requirements=dict(type='str'),
             virtualenv=dict(type='path'),