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.

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”).

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.

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.

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.