PyPI
===============================================================================

This template automates the process of building and publishing a Python
package to the Python Package Index (PyPI).


Usage
-----

In your project's ``.gitlab-ci.yml``:

.. code-block:: yaml

    include:
      - project: "bytecode-solutions/core/core-gitlab-templates"
        file: "releases/pypi.yml"

Parameters
----------

The template defines the following inputs:

``image``
    The Docker image used for running the job.
    Default: ``python:latest``

``branch``
    The branch on which the job should be executed.
    Default: ``release``

``stage``
    The pipeline stage in which the release job runs.
    Default: ``release``

Behavior
--------

The job performs the following steps:

1. Installs required packaging tools (``build`` and ``twine``)
2. Builds the distribution files into ``dist/``
3. Uploads the artifacts to PyPI using ``twine``

The job runs only when the current branch matches the provided ``branch`` input.

Environment Variables
---------------------

The following variables must be configured in GitLab CI/CD settings:

``PYPI_USER``
    Your PyPI username or token name.

``PYPI_PASSWORD``
    Your PyPI password or API token.

.. note::

   For security, it's recommended to use API tokens instead of passwords
   when authenticating with PyPI. Store these as **masked GitLab CI variables**.