.. _JOBTMPL/PublishOnPyPI:

PublishOnPyPI
#############

Publish a wheel (``*.whl``) packages and/or source (``*.tar.gz``) package to `PyPI <https://pypi.org/>`__.

.. topic:: Features

   * Publish a Python package to `PyPI <https://pypi.org/>`__.

.. topic:: Behavior

   1. Download package artifact
   2. Publish source package(s) (``*.tar.gz``)
   3. Publish wheel package(s) (``*.whl``)
   4. Delete the artifact

.. topic:: Preconditions

   1. A PyPI account was created and the package name is either not occupied or the user has access rights for that
      package.
   2. An access token was generated at PyPI, which can be used for uploading packages.
   3. A secret (e.g. ``PYPI_TOKEN``) was setup in GitHub Actions to handover the PyPI token to the pipeline.

.. topic:: Job Execution

   .. image:: ../../_static/pyTooling-Actions-PublishOnPyPI.png
      :width: 500px

.. topic:: Dependencies

   * :gh:`pyTooling/download-artifact`

     * :gh:`actions/download-artifact`
   * :gh:`actions/setup-python`
   * :gh:`geekyeggo/delete-artifact`

   * pip

     * :pypi:`wheel`
     * :pypi:`twine`


.. _JOBTMPL/PublishOnPyPI/Instantiation:

Instantiation
*************

Simple Example
==============

The following example demonstrates how to publish the artifact named ``Package`` to PyPI on every pipeline run triggered
by a Git tag. A secret is forwarded from GitHub secrets to a job secret.

.. code-block:: yaml

   jobs:
     # ...

     PublishOnPyPI:
       uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@r5
       if: startsWith(github.ref, 'refs/tags')
       with:
         artifact: Package
       secrets:
         PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}

Complex Example
===============

In this more complex example, the job depends on a parameter creation (``Params``) and packaging job (``Package``). The
used Python version is overwritten by a parameter calculated in the ``Params`` jobs. Also the artifact name is managed
by that job. Finally, the list of requirements is overwritten to load a list of requirements from ``dist/requirements.txt``.

.. code-block:: yaml

   jobs:
     Params:
       # ...

     Package:
       # ...

     PublishOnPyPI:
       uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@r5
       if: startsWith(github.ref, 'refs/tags')
       needs:
         - Params
         - Package
       with:
         python_version: ${{ needs.Params.outputs.python_version }}
         requirements: -r dist/requirements.txt
         artifact: ${{ fromJson(needs.Params.outputs.artifact_names).package_all }}
       secrets:
         PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}

.. seealso::

   :ref:`JOBTMPL/Package`


.. _JOBTMPL/PublishOnPyPI/Parameters:

Parameter Summary
*****************

.. rubric:: Goto :ref:`input parameters <JOBTMPL/PublishOnPyPI/Inputs>`

+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| Parameter Name                                                      | Required | Type     | Default                                                           |
+=====================================================================+==========+==========+===================================================================+
| :ref:`JOBTMPL/PublishOnPyPI/Input/ubuntu_image_version`             | no       | string   | ``'24.04'``                                                       |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishOnPyPI/Input/python_version`                   | no       | string   | ``'3.13'``                                                        |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishOnPyPI/Input/requirements`                     | no       | string   | ``'wheel twine'``                                                 |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/PublishOnPyPI/Input/artifact`                         | yes      | string   | — — — —                                                           |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+

.. rubric:: Goto :ref:`secrets <JOBTMPL/PublishOnPyPI/Secrets>`

+-----------------------------------------------------------+----------+----------+--------------+
| Token Name                                                | Required | Type     | Default      |
+===========================================================+==========+==========+==============+
| :ref:`JOBTMPL/PublishOnPyPI/Secret/PYPI_TOKEN`            | no       | string   | — — — —      |
+-----------------------------------------------------------+----------+----------+--------------+

.. rubric:: Goto :ref:`output parameters <JOBTMPL/PublishOnPyPI/Outputs>`

This job template has no output parameters.


.. _JOBTMPL/PublishOnPyPI/Inputs:

Input Parameters
****************

.. _JOBTMPL/PublishOnPyPI/Input/ubuntu_image_version:

ubuntu_image_version
====================

:Type:            string
:Required:        no
:Default Value:   ``'24.04'``
:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
                  for available Ubuntu image versions.
:Description:     Version of the Ubuntu image used to run this job.

                  .. note::

                     Unfortunately, GitHub Actions has only a `limited set of functions <https://docs.github.com/en/actions/reference/workflows-and-actions/expressions#functions>`__,
                     thus, the usual Ubuntu image name like ``'ubuntu-24.04'`` can't be split into image name and image
                     version.


.. _JOBTMPL/PublishOnPyPI/Input/python_version:

python_version
==============

:Type:            string
:Required:        no
:Default Value:   ``'3.13'``
:Possible Values: Any valid Python version conforming to the pattern ``<major>.<minor>`` or ``pypy-<major>.<minor>``. |br|
                  See `actions/python-versions - available Python versions <https://github.com/actions/python-versions>`__
                  and `actions/setup-python - configurable Python versions <https://github.com/actions/setup-python>`__.
:Description:     Python version used as default for other jobs requiring a single Python version. |br|
                  In case :ref:`JOBTMPL/Parameters/Input/python_version_list` is an empty string, this version is used
                  to populate the version list.


.. _JOBTMPL/PublishOnPyPI/Input/requirements:

requirements
============

:Type:            string
:Required:        no
:Default Value:   ``''``
:Possible Values: Any valid list of parameters for ``pip install``. |br|
                  Either a requirements file can be referenced using ``'-r path/to/requirements.txt'``, or a list of
                  packages can be specified using a space separated list like ``'wheel twine'``.
:Description:     Python dependencies to be installed through *pip*.


.. _JOBTMPL/PublishOnPyPI/Input/artifact:

artifact
========

:Type:            string
:Required:        yes
:Possible Values: Any valid artifact name.
:Description:     Name of the artifact containing the packaged Python package(s).


.. _JOBTMPL/PublishOnPyPI/Secrets:

Secrets
*******


.. _JOBTMPL/PublishOnPyPI/Secret/PYPI_TOKEN:

PYPI_TOKEN
==========

:Type:            string
:Required:        no
:Default Value:   — — — —
:Description:     The token to publish and upload packages on `PyPI <https://pypi.org/>`__.


.. _JOBTMPL/PublishOnPyPI/Outputs:

Outputs
*******

This job template has no output parameters.


.. _JOBTMPL/PublishOnPyPI/Optimizations:

Optimizations
*************

This template offers no optimizations (reduced job runtime).