upload-pypi: support API token upload

Support an api_token argument.  Accounts that have two-factor auth
will at some point require using API tokens to upload.

Change-Id: Id0c47d088d6e8febbae3c96caecc81ebe247754e

roles/upload-pypi/README.rst

@@ -8,9 +8,16 @@ Upload python packages to PyPI
    server as well as the authentication information needed. It is
    expected that this argument comes from a `Secret`.
 
+  .. zuul:rolevar:: api_token
+     :default: None
+
+     PyPi API token to use for upload.  If specified, ``username`` and
+     ``password`` should be empty.
+
   .. zuul:rolevar:: username
 
-     Username to use to log in to PyPI.
+     Username to use to log in to PyPI.  `Note` PyPi reccommends using
+     two-factor auth and generating an API token for uploading.
 
   .. zuul:rolevar:: password
 

roles/upload-pypi/tasks/main.yaml

@@ -1,3 +1,10 @@
+- name: Validate password/token combo
+  fail:
+    msg: 'Specify either username/password or api_token'
+  when: >
+      (pypi_info.api_token is defined) and
+      ((pypi_info.username is defined) or (pypi_info.password is defined))
+
 - name: Create .pypirc configuration file tempfile
   tempfile:
     state: file

roles/upload-pypi/templates/.pypirc.j2

@@ -6,5 +6,5 @@ index-servers=
 {% if pypi_repository_url %}
 repository:{{ pypi_repository_url }}
 {% endif %}
-username:{{ pypi_info.username }}
+username:{{ '__token__' if (pypi_info.api_token is defined) else pypi_info.username }}
-password:{{ pypi_info.password }}
+password:{{ pypi_info.api_token if (pypi_info.api_token is defined) else pypi_info.password }}

zuul.d/python-jobs.yaml

@@ -338,8 +338,9 @@
     description: |
       Generate and upload a python source tarball and binary wheel
 
-      Requires a variable ``pypi_info`` be set which is a dict containing
+      Requires a variable ``pypi_info`` be set which is a dict
-      at least a ``username`` and ``password`` attribute.
+      containing authentication values.  See
+      `<https://zuul-ci.org/docs/zuul-jobs/python-roles.html#role-upload-pypi>`__
     post-run: playbooks/python/upload-pypi.yaml
 
 - job: