Python templates¶

The Python template file python.yml can be included via

include:
  - project: computing/gitlab-ci-templates
    file: python.yml

This file provides the following job templates:

• .python:cache
• .python:base
• .python:build
• .python:coverage
• .python:test
• .python:coverage-combine
• .python:unittest
• .python:pytest
• .python:flake8
• .python:radon
• .python:mkdocs
• .python:sphinx
• .python:twine

.python:cache¶

Description¶

Configures caching of the pip cache directory via the following variable:

Example usage¶

pip:
  extends:
    - .python:cache

.python:base¶

Extends: .python:cache

Description¶

The base Python job template. This template configures Pip caching, the PYTHON environment variable, and a default docker image (python).

Example usage¶

python:
  extends:
    - .python:base
  before_script:
    - python -m pip install numpy
  script:
    - python -c "import numpy; print(numpy.sqrt((1, 2, 3, 4)))"

.python:build¶

Extends: .python:base

Description¶

The .python:build job template provides an end-to-end distribution build configuration, effectively running the following command to build a project:

python -m build --sdist --wheel .

The outputs are uploaded as job artifacts.

The following variables can be used to configure the build:

Example usage¶

The default options are most likely enough for your project:

build:
  extends:
    - .python:build

To disable the wheel build:

tarball:
  extends:
    - .python:build
  variables:
    WHEEL: "false"

.python:coverage¶

Extends: .python:base

Description¶

A base template for Python test jobs that use Coverage.py to measure code coverage. The template just configures printing and uploading of coverage reports from a test suite run.

For most projects it would probably make more sense to use one of the harness-specific templates for unittest or pytest below.

Example usage¶

test:
  extends:
    - .python:coverage
  before_script:
    # install coverage
    - python -m pip install coverage
  script:
    - python -m coverage run --source mylib ./script.py

.python:test¶

.python:coverage-combine¶

Extends: .python:combine

Description¶

This job executes python -m coverage combine to combine coverage reports from multiple jobs. The combined report is then converted to XML and uploaded as a coverage_report artifact.

The job can be configured using the following variables:

Example usage¶

.test:
  extends:
    - .python:coverage
  script:
    - python -m coverage run --source mylib ./script.py
  # disable coverage total report from individual jobs
  coverage: null
  artifacts:
    paths:
      # upload all .coverage files as artifacts
      - .coverage*

test:3.9
  extends:
    - .test
  image: python:3.9

test:3.10
  extends:
    - .test
  image: python:3.10

coverage:
  extends:
    - .python:coverage-combine

.python:unittest¶

Extends: .python:coverage

Description¶

This job runs a unittest suite for a Python project.

With default options, this job approximately runs the following:

pip install .
python -m unittest discover

The job can be configured using the following variables:

Example usage¶

To run unittest after installing the mylib-*.tar.gz file created by the tarball job:

test:
  extends:
    - .python:unittest
  needs:
    - tarball
  variables:
    GIT_STRATEGY: none
    INSTALL_TARGET: "mylib-*.tar.gz"
    COVERAGE_TARGET: "mylib"

.python:pytest¶

Extends: .python:coverage

Description¶

This job installs a project and runs pytest, uploading JUnit XML test and coverage reports.

With default options, this job approximately runs the following script:

pip install .
pip install pytest
pytest --cov=${CI_PROJECT_NAME}

The job can be configured using the following variables:

Example usage¶

For projects that include pytest configurations in the repository and don't need any plugins, you can just use the template without any additions:

test:
  extends:
    - .python:pytest

To configure the template to install from a tarball, then run tests using pytest-xdist with coverage measured from the installed library:

test:
  extends:
    - .python:pytest
  variables:
    GIT_STRATEGY: none
    TESTS_REQUIRE: "pytest-xdist"
    INSTALL_TARGET: "myproject-*.tar.*"
    COVERAGE_TARGET: "my_library"
    PYTEST_OPTIONS: "--pyargs my_library"

In this instance the job effectively runs this script:

pip install myproject-*.tar.*
pip install pytest pytest-xdist
pytest --cov=my_library --pyargs my_library

.python:mkdocs¶

Description¶

This job runs mkdocs build, uploading the output site/ directory as a job artifact.

With default options, this job approximately runs the following script:

pip install mkdocs
mkdocs build .

The template can be configured using the following variables:

Example usage¶

(Including gitlab pages job):

mkdocs:
  extends:
    - .python:mkdocs
  variables:
    REQUIREMENTS: "-r requirements.txt"

pages:
  needs: [mkdocs]
  script:
    - mv -v site public
  artifacts:
    paths:
      - public

.python:sphinx¶

Extends: .python:base

Description¶

This job runs sphinx, uploading the HTML output directory html/ as a job artifact.

With default options, this job approximately runs the following script:

cd docs
make html

However, if docs/Makefile isn't found, the following is run:

cd docs
sphinx-build -b html . ..

The template can be configured using the following variables:

Example usage¶

Example usage (including gitlab pages job):

sphinx:
  extends:
    - .python:sphinx
  variables:
    REQUIREMENTS: "-r docs/requirements.txt"

pages:
  needs: [sphinx]
  script:
    - mv -v html public
  artifacts:
    paths:
      - public

.python:flake8¶

Extends: .python:base

Description¶

This template runs the flake8 linter over the project source, uploading a code quality report.

With default options, this job approximately runs the following script:

pip install flake8
flake8

The template can be configured using the following variables:

Example usage¶

lint:
  extends:
    - .python:flake8

.python:radon¶

Extends: .python:base

Description¶

This template runs the Radon code analysis tool over the project source, uploading a code quality report.

With default options, this job approximately runs the following script:

pip install radon
radon cc .

The template can be configured using the following variables:

Example usage¶

cc:
  extends:
    - .python:radon

.python:twine¶

Extends: .python:base

Description¶

This template runs twine to upload packages to the Python Package Index (PyPI).

With default options, this job approximately runs the following script:

pip install twine
twine check *.tar.* *.whl
twine upload *.tar.* *.whl

The template can be configured using the following variables:

Example usage¶

upload:
  extends:
    - .python:twine