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) following those recommendations

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: '2.0.3'
    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
PIP_INDEX_URL	Python repository url	none
PYTHON_PROJECT_DIR	Python project root directory	.
REQUIREMENTS_FILE	Path to requirements file (relative to $PYTHON_PROJECT_DIR)	requirements.txt
PIP_OPTS	pip extra options	none

The cache policy also declares the .cache/pip directory as cached (not to download Python dependencies over and over again).

Default configuration follows this Python project structure

Poetry support

The Python template supports Poetry as packaging and dependency management tool.

If a pyproject.toml and poetry.lock file is detected at the root of your project structure, requirements will automatically be generated from Poetry. Poetry support is disabled if PYTHON_POETRY_DISABLED is set to true.

⚠️ as stated in Poetry documentation, You should commit the poetry.lock file to your project repo so that all people working on the project are locked to the same versions of dependencies.

It uses the following variables:

Name	description	default value
PYTHON_POETRY_EXTRAS	Poetry extra sets of dependencies to include, space separated	none

Jobs

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.

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
TEST_REQUIREMENTS_FILE	Path to test requirements file (relative to $PYTHON_PROJECT_DIR)	test-requirements.txt
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).

⚠️ 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

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

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

Name	description	default value
TEST_REQUIREMENTS_FILE	Path to test requirements file (relative $PYTHON_PROJECT_DIR)	test-requirements.txt
PYTEST_ARGS	Additional pytest or pytest-cov CLI options	none

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

• JUnit test report (with the --junit-xml argument)
• code coverage report (cobertura xml format).

⚠️ 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-nosetest job

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

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