repo_helper.blocks

Reusable blocks of reStructuredText.

Classes:

ShieldsBlock(username, repo_name, version, *)

Create the shields block for insertion into the README, documentation etc.

Functions:

create_docs_install_block(repo_name, username)	Create the installation instructions for insertion into the documentation.
create_docs_links_block(username, repo_name)	Create the documentation links block.
create_readme_install_block(modname, username)	Create the installation instructions for insertion into the README.
create_short_desc_block(short_desc)	Creates the short description block insertion into the README, documentation etc.
get_docs_links_block_template()	Loads the docs_links_block template from file and returns a jinja2 jinja2.environment.Template for it.
get_readme_installation_block_no_pypi_template()	Loads the readme_installation_block_no_pypi template from file and returns a jinja2 jinja2.environment.Template for it.
get_readme_installation_block_template()	Loads the readme_installation_block template from file and returns a jinja2 jinja2.environment.Template for it.

Data:

installation_regex	Regular expression to match the installation block placeholder.
links_regex	Regular expression to match the links block placeholder.
shields_regex	Regular expression to match the shields block placeholder.
short_desc_regex	Regular expression to match the short description block placeholder.

class ShieldsBlock(username, repo_name, version, *, conda=True, tests=True, docs=True, docs_url='https://{}.readthedocs.io/en/latest/?badge=latest', pypi_name=None, conda_name=None, unique_name='', docker_shields=False, docker_name='', platforms=None, on_pypi=True, primary_conda_channel=None, linters=True)

Bases: object

Create the shields block for insertion into the README, documentation etc.

Parameters

• username (str) – The username of the GitHub account that owns the repository.

• repo_name (str) – The name of the repository.

• version (Union[str, int])

• conda (bool) – Default True.

• tests (bool) – Default True.

• docs (bool) – Default True.

• docs_url (str) – Default 'https://{}.readthedocs.io/en/latest/?badge=latest'.

• pypi_name (Optional[str]) – The name of the project on PyPI. Defaults to the value of repo_name if unset. Default None.

• conda_name (Optional[str]) – The name of the project on conda. Defaults to the value of repo_name if unset. Default None.

• unique_name (str) – An optional unique name for the reST substitutions. Default ''.

• docker_shields (bool) – Whether to show shields for Docker. Default False. Default False.

• docker_name (str) – The name of the Docker image on DockerHub. Default ''.

• platforms (Optional[Iterable[str]]) – List of supported platforms. Default None.

• on_pypi (bool) – Default True.

• primary_conda_channel (Optional[str]) – The Conda channel the package can be downloaded from. Default None.

• linters (bool) – Whether to show badges for linters (mypy and flake8). Default True.

New in version 2020.12.11.

New in version 2025.6.3: Added conda_name option.

New in version $VERSION: Added linters option.

Methods:

make()	Constructs the contents of the shields block.
set_docs_mode()	Create shields for insertion into Sphinx documentation.
set_readme_mode()	Create shields for insertion into README.rst.

Attributes:

sections	This list controls which sections are included, and their order.
substitutions	This list controls which substitutions are included, and their order.

make()

Constructs the contents of the shields block.

Return type

StringList

sections = ('Docs', 'Tests', 'PyPI', 'Anaconda', 'Activity', 'QA', 'Docker', 'Other')

Type:    tuple

This list controls which sections are included, and their order.

set_docs_mode()

Create shields for insertion into Sphinx documentation.

set_readme_mode()

Create shields for insertion into README.rst.

substitutions = ('docs', 'docs_check', 'actions_linux', 'actions_windows', 'actions_macos', 'actions_flake8', 'actions_mypy', 'requires', 'coveralls', 'codefactor', 'pypi-version', 'supported-versions', 'supported-implementations', 'wheel', 'conda-version', 'conda-platform', 'license', 'language', 'commits-since', 'commits-latest', 'maintained', 'pypi-downloads', 'docker_build', 'docker_automated', 'docker_size')

Type:    tuple

This list controls which substitutions are included, and their order.

create_docs_install_block(repo_name, username, conda=True, pypi=True, pypi_name=None, conda_name=None, conda_channels=None)

Create the installation instructions for insertion into the documentation.

Parameters

• repo_name (str) – The name of the GitHub repository.

• username (str) – The username of the GitHub account that owns the repository. (Not used; ensures API compatibility with create_readme_install_block())

• conda (bool) – Whether to show Anaconda installation instructions. Default True.

• pypi (bool) – Whether to show PyPI installation instructions. Default True.

• pypi_name (Optional[str]) – The name of the project on PyPI. Defaults to the value of repo_name if unset. Default None.

• conda_name (Optional[str]) – The name of conda package for the project. Defaults to the value of repo_name if unset. Default None.

• conda_channels (Optional[Sequence[str]]) – List of required Conda channels. Default None.

Return type

str

Returns

The installation block created from the above settings.

create_docs_links_block(username, repo_name)

Create the documentation links block.

Parameters

• username (str) – The username of the GitHub account that owns the repository.

• repo_name (str) – The name of the GitHub repository.

Return type

str

Returns

The documentation links block created from the above settings.

create_readme_install_block(modname, username, conda=True, pypi=True, pypi_name=None, conda_name=None, conda_channels=None)

Create the installation instructions for insertion into the README.

Parameters

• modname (str) – The name of the program / library.

• username (str) – The username of the GitHub account that owns the repository.

• conda (bool) – Whether to show Anaconda installation instructions. Default True.

• pypi (bool) – Whether to show PyPI installation instructions. Default True.

• pypi_name (Optional[str]) – The name of the project on PyPI. Defaults to the value of repo_name if unset. Default None.

• conda_name (Optional[str]) – The name of conda package for the project. Defaults to the value of repo_name if unset. Default None.

• conda_channels (Optional[Sequence[str]]) – List of required Conda channels. Default None.

Return type

str

Returns

The installation block created from the above settings.

create_short_desc_block(short_desc)

Creates the short description block insertion into the README, documentation etc.

Parameters

short_desc (str) – A short description of the program / library.

Return type

str

Returns

The short description block created from the above settings.

get_docs_links_block_template()

Loads the docs_links_block template from file and returns a jinja2 jinja2.environment.Template for it.

Return type

Template

get_readme_installation_block_no_pypi_template()

Loads the readme_installation_block_no_pypi template from file and returns a jinja2 jinja2.environment.Template for it.

New in version 2020.12.1.

Return type

Template

get_readme_installation_block_template()

Loads the readme_installation_block template from file and returns a jinja2 jinja2.environment.Template for it.

Return type

Template

installation_regex

Type:    Pattern

Regular expression to match the installation block placeholder.

Pattern	(.. start installation)(.*?)(.. end installation)
Flags	re.DOTALL

links_regex

Type:    Pattern

Regular expression to match the links block placeholder.

Pattern	(.. start links)(.*?)(.. end links)
Flags	re.DOTALL

shields_regex

Type:    Pattern

Regular expression to match the shields block placeholder.

Pattern	(.. start shields)(.*?)(.. end shields)
Flags	re.DOTALL

short_desc_regex

Type:    Pattern

Regular expression to match the short description block placeholder.

Pattern	(.. start short[-_]desc)(.*?)(.. end short[-_]desc)
Flags	re.DOTALL