Python Roles

build-python-release

Build sdist and wheel for Python projects.

Role Variables

release_python
Default: python

The python interpreter to use. Set it to “python3” to use python 3, for example.

bdist_wheel_xargs
Default: ''

Extra arguments to pass to the bdist_wheel command when building packages.

build-releasenotes

Build releasenotes for a project, optionally incorporating translations.

Role Variables

zuul_work_virtualenv
Default: ~/.venv

Virtualenv location in which to install things.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to build releasenotes in.

ensure-babel

Ensure babel is installed

Role Variables

constraints_file

Optional path to a pip constraints file for installing python libraries.

ensure-python

Ensure specified python interpreter and development files are installed

Note

This role is only available for Debian based platforms currently.

Role Variables

python_version

Optional version of python interpreter to install, such as 3.7.

python_use_pyenv

:default: false

Whether to optionally use pyenv to install python instead of distro packages.

ensure-sphinx

Ensure sphinx is installed

Installs sphinx. Also installs any dependencies needed in the first of doc/requirements.txt and test-requirements.txt to be found.

All pip installs are done with a provided constraints file, if given.

Role Variables

constraints_file

Optional path to a pip constraints file for installing python libraries.

doc_building_packages
Default: ``list``

List of python packages to install for building docs. The default package list is based on the python version in use.

doc_building_extra_packages
Default: ``list``

List of python additional packages to install for building docs. By default this list is empty.

sphinx_python
Default: python2

Version of python to use, either python2 or python3.

zuul_work_virtualenv
Default: ~/.venv

Virtualenv location in which to install things.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to operate in.

ensure-tox

Ensure tox is installed

If tox is not already installed, it will be installed via pip in the user install directory (i.e., “pip install –user”).

Role Variables

tox_executable
Default: ``tox``

Optional path to point tox executable

tox_prefer_python2
Default: ``true``

If tox is not detected, prefer to install tox inside Python 2 instead of Python 3.

ensure-twine

Ensure twine is installed.

Role Variables

twine_python
Default: python

The python interpreter to use to install twine if it is not already installed. Set it to “python3” to use python 3, for example.

fetch-coverage-output

Collect output from a coverage run

By default, this copies the output from a coverage run on the worker to the log root of the executor.

Role Variables

zuul_executor_dest
Default: {{ zuul.executor.log_root }}

The destination directory on the executor. By default, the log root.

coverage_output_src
Default: {{ zuul.project.src_dir }}/cover/

The location on the worker from which to fetch the coverage output detail. By default, the cover dir of the current project.

fetch-python-sdist-output

Collect output from a python sdist build

fetch-sphinx-output

Collect output from a sphinx build

By default, this copies the output from the sphinx build on the worker to the log root of the executor.

Role Variables

zuul_executor_dest
Default: {{ zuul.executor.log_root }}

The destination directory on the executor. By default, the log root.

sphinx_build_dir
Default: doc/build

Directory relative to zuul_work_dir where build output will be put.

sphinx_output_suffix
Default: ''

Suffix to use for constructing the path. This is normally an empty string. If set to ‘/’ then, rsync will remove the last part from the original path.

sphinx_output_src
Default: {{ zuul_work_dir }}/{{ sphinx_build_dir }}/html{{ sphinx_output_suffix }}

The location on the worker from which to fetch the generated sphinx content. By default, the HTML doc build dir of the current project.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

The location of the main working directory of the job.

fetch-sphinx-tarball

Collect output from a sphinx build as a tarball

By default, this copies the output from the sphinx build on the worker to the log root of the executor as a tarball, and then extracts the archive into the log root for viewing.

Role Variables

sphinx_build_dir
Default: doc/build

Directory relative to zuul_work_dir where build output should be found.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

The location of the main working directory of the job.

sphinx_pdf_files
Default: list

A list of file names of PDF files to collect. By default, the list contains as entry only doc-{{ zuul.project.short_name }}.pdf.

fetch-subunit-output

Collect subunit outputs

Role Variables

zuul_work_dir
Default: {{ ansible_user_dir }}/{{ zuul.project.src_dir }}

Directory to work in. It has to be a fully qualified path.

fetch_subunit_output_additional_dirs
Default: []

List of additional directories which contains subunit files to collect. The content of zuul_work_dir is always checked, so it should not be added here.

tox_envlist

tox environment that was used to run the tests originally.

zuul_use_fetch_output
Default: false

Whether to synchronize files to the executor work dir, or to copy them on the test instance. When set to false, the role synchronizes the file to the executor. When set to true, the job needs to use the fetch-output role later.

fetch-tox-output

Collect log output from a tox build

Role Variables

tox_envlist
Default: venv

Which tox environment to fetch log output from.

tox_executable
Default: tox

Location of the tox executable.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory tox was run in.

zuul_use_fetch_output
Default: false

Whether to synchronize files to the executor work dir, or to copy them on the test instance. When set to false, the role synchronizes the file to the executor. When set to true, the job needs to use the fetch-output role later.

find-constraints

Find a pip constraints file

Sets a variable upper_constraints which can be passed to a pip invocation.

Role Variables

constraints_file

Optional path to a pip constraints file for installing python libraries.

install-if-python

Install the contents of a directory if they contain a python project.

Installs into a virtualenv.

Role Variables

install_package
Default: true

Flag indicating whether or not the software in the zuul_work_dir should be installed.

error_on_failure

Flag that indicates installation errors should result in failure. Failures in installing the target directory are ignored by default.

constraints_file

Optional path to a pip constraints file to use when installing.

zuul_work_virtualenv
Default: ~/.venv

Virtualenv location in which to install things.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to operate in.

sphinx

Run sphinx to generate documentation

Role Variables

sphinx_source_dir
Default: doc/source

Directory relative to zuul_work_dir that contains the Sphinx sources.

sphinx_build_dir
Default: doc/build

Directory relative to zuul_work_dir where build output will be put.

sphinx_builders
Default: ['html']

Which sphinx builders to run.

sphinx_warning_is_error

Whether to treat sphinx build warnings as errors. Defaults to the value of [build_sphinx] warning-is-error in setup.cfg if defined, False if the [build_sphinx] section is present but the warning-is-error option is undefined, or True if the entire section is undefined.

zuul_work_virtualenv
Default: ~/.venv

Virtualenv that sphinx is installed in.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to operate in.

tox

Runs tox for a project

Role Variables

tox_environment

Environment variables to pass in to the tox run.

tox_envlist
Default: venv

Which tox environment to run.

tox_executable
Default: tox

Location of the tox executable.

tox_extra_args
Default: -vv

String of extra command line options to pass to tox.

tox_constraints_file

Path to a pip constraints file. Will be provided to tox via TOX_CONSTRAINTS_FILE (deprecated but currently still supported name is UPPER_CONSTRAINTS_FILE) environment variable if it exists.

tox_install_siblings
Default: true

Flag controlling whether to attempt to install python packages from any other source code repos zuul has checked out. Defaults to True.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to run tox in.

upload-pypi

Upload python packages to PyPI

Role Variables

pypi_info

Complex argument which contains the information about the PyPI server as well as the authentication information needed. It is expected that this argument comes from a Secret.

pypi_info.username

Username to use to log in to PyPI.

pypi_info.password

Password to use to log in to PyPI.

pypi_info.repository
Default: pypi

Name of the repository to upload to.

pypi_info.repository_url
Default: The built-in twine default for the production pypi.org service.

URL of the PyPI repostory.

pypi_path
Default: src/{{ zuul.project.canonical_name }}/dist

Path containing artifacts to upload.

pypi_twine_executable
Default: twine

Path to twine executable.

pypi_register_first
Default: false

Whether the role should register the package before uploading it. This may be required when uploading for the first time to a devPI instance.