README.md

GitLab CI template for Python

This project implements a generic GitLab CI template for Python.

It provides several features, usable in different modes (by configuration).

Usage

In order to include this template in your project, add the following to your gitlab-ci.yml:

include:
  - project: 'to-be-continuous/python'
    ref: '5.0.0'
    file: '/templates/gitlab-ci-python.yml'

Global configuration

The Python template uses some global configuration used throughout all jobs.

Name	description	default value
PYTHON_IMAGE	The Docker image used to run Python ⚠️ set the version required by your project	python:3
PYTHON_PROJECT_DIR	Python project root directory	.
PYTHON_BUILD_SYSTEM	Python build-system to use to install dependencies, build and package the project (see below)	none (auto-detect)
PIP_INDEX_URL	Python repository url	none
PIP_OPTS	pip extra options	none
PYTHON_EXTRA_DEPS	Python extra sets of dependencies to install For Setuptools or Poetry only	none
PYTHON_REQS_FILE	Main requirements file (relative to $PYTHON_PROJECT_DIR) For Requirements Files build-system only	requirements.txt
PYTHON_EXTRA_REQS_FILES	Extra dev requirements file(s) to install (relative to $PYTHON_PROJECT_DIR)	requirements-dev.txt

The cache policy also makes the necessary to manage pip cache (not to download Python dependencies over and over again).

Multi build-system support

The Python template supports the most popular dependency management & build systems.

By default it tries to auto-detect the build system used by the project (based on the presence of pyproject.toml and/or setup.py and/or requirements.txt), but the build system might also be set explicitly using the $PYTHON_BUILD_SYSTEM variable:

Value	Build System (scope)
none (default) or auto	The template tries to auto-detect the actual build system
setuptools	Setuptools (dependencies, build & packaging)
poetry	Poetry (dependencies, build, test & packaging)
pipenv	Pipenv (dependencies only)
reqfile	Requirements Files (dependencies only)

Jobs

py-package job

This job allows building your Python project distribution packages.

It is bound to the build stage, it is disabled by default and can be enabled by setting $PYTHON_PACKAGE_ENABLED to true.

Lint jobs

py-pylint job

This job is disabled by default and performs code analysis based on pylint Python lib. It is activated by setting $PYLINT_ENABLED to true.

It is bound to the build stage, and uses the following variables:

Name	description	default value
PYLINT_ARGS	Additional pylint CLI options	none
PYLINT_FILES	Files or directories to analyse	none (by default analyses all found python source files)

This job produces the following artifacts, kept for one day:

• Code quality json report in code climate format.
• Pylint report for SonarQube (if SONAR_URL is defined).

Test jobs

The Python template features four alternative test jobs:

• py-unittest that performs tests based on unittest Python lib,
• or py-pytest that performs tests based on pytest Python lib,
• or py-nosetest that performs tests based on nose Python lib,
• or py-compile that performs byte code generation to check syntax if not tests are available.

py-unittest job

This job is disabled by default and performs tests based on unittest Python lib. It is activated by setting $UNITTEST_ENABLED to true.

In order to produce JUnit test reports, the tests are executed with the xmlrunner module.

It is bound to the build stage, and uses the following variables:

Name	description	default value
UNITTEST_ARGS	Additional xmlrunner/unittest CLI options	none

This job produces the following artifacts, kept for one day:

• JUnit test report (using the xmlrunner module)
• code coverage report (cobertura xml format).

⚠️ code coverage report artifact is disabled, due to a deprecated syntax, see Activate code coverage report artifact

⚠️ create a .coveragerc file at the root of your Python project to control the coverage settings.

Example:

[run]
# enables branch coverage
branch = True
# list of directories/packages to cover
source =
    module_1
    module_2

py-pytest job