repo_helper¶
A tool to manage configuration files, build scripts etc. across multiple projects.
This project is in an early stage, and some things might not work correctly or break in a new release.
Note
The autocommit functionality is currently broken on Windows, but works OK on Linux and macOS.
Docs |
|
|---|---|
Tests |
|
PyPI |
|
Anaconda |
|
Activity |
|
QA |
|
Other |
|
Installation¶
python3 -m pip install repo_helper --user
First add the required channels
conda config --add channels https://conda.anaconda.org/conda-forge
conda config --add channels https://conda.anaconda.org/domdfcoding
Then install
conda install repo_helper
python3 -m pip install git+https://github.com/repo-helper/repo_helper@master --user
Overview¶
Place configuration options in a file called repo_helper.yml in the repository root.
Options are defined like so:
modname: repo_helper
copyright_years: "2020"
author: "Dominic Davis-Foster"
email: "dominic@example.com"
version: "0.0.1"
username: "domdfcoding"
license: 'LGPLv3+'
short_desc: 'Update multiple configuration files, build scripts etc. from a single location'
Metadata¶
The name of the package author.
Example:
author: Dominic Davis-Foster
Required: yes
Type: String
- classifiers¶
A list of “trove classifiers” for PyPI.
Example:
classifiers: - "Environment :: Console"
Classifiers are automatically added for the supported Python versions and implementations, and for most licenses.
Required: no
Default: [ ]
Type: Sequence of String
- primary_conda_channel¶
The Conda channel the package can be downloaded from.
This is automatically added to
conda_channels.Defaults to
usernameif unset.Example:
username: repo-helper primary_conda_channel: domdfcoding
New in version 2020.12.17.
Required: no
Default: The value of
usernameType: String
- copyright_years¶
The copyright_years of the package.
Examples:
version: 2020
or
version: 2014-2019
Required: yes
Type: String or Integer
- email¶
The email address of the author or maintainer.
Example:
email: dominic@example.com
Required: yes
Type: String
- import_name¶
The name the package is imported with, if different to
modname.Example:
import_name: repo_helper
Required: no
Default: The value of
modnameType: String
- keywords¶
A list of keywords for the project.
Example:
keywords: - version control - git - template
Required: no
Default: [ ]
Type: Sequence of String
- license¶
The license for the project.
Example:
license: GPLv3+
Currently understands
LGPLv3,LGPLv3,GPLv3,GPLv3,GPLv2andBSD.Required: yes
Type: String
- modname¶
The name of the package.
Example:
modname: repo_helper
Required: yes
Type: String
- on_pypi¶
Flag to indicate the package is available on PyPI.
Example:
on_pypi: True
Required: no
Default:
TrueType: Boolean
- pure_python¶
Flag to indicate the package is pure Python.
Example:
pure_python: True
Required: no
Default:
TrueType: Boolean
- pypi_name¶
The name of project on PyPI, if different to
modname.Example:
pypi_name: git-helper
Required: no
Default: The value of
modnameType: String
- repo_name¶
The name of GitHub repository, if different to
modname.Example:
repo_name: repo_helper
Required: no
Default: The value of
modnameType: String
- short_desc¶
A short description of the project. Used by PyPI.
Example:
short_desc: This is a short description of my project.
Required: yes
Type: String
- source_dir¶
The directory containing the source code of the project.
Example:
source_dir: src
By default this is the repository root
Required: no
Default: <blank>
Type: String
- stubs_package¶
Flag to indicate the package is a PEP 561 stubs package.
Example:
stubs_package: True
Required: no
Default:
FalseType: Boolean
- username¶
The username of the GitHub account hosting the repository.
Example:
username: domdfcoding
Required: yes
Type: String
- version¶
The version of the package.
Example:
version: 0.0.1
Required: yes
Type: String or Float
Optional features¶
- docker_name¶
The name of the docker image on dockerhub.
Example:
docker_name: domdfcoding/fancy_docker_image
Required: no
Default: <blank>
Type: String
- docker_shields¶
Whether shields for docker container image size and build status should be shown.
Example:
docker_shields: True
Required: no
Default:
FalseType: Boolean
Python versions¶
- python_deploy_version¶
The version of Python to use on Travis when deploying to PyPI, Anaconda and GitHub releases.
Example:
python_deploy_version: 3.8
Required: no
Default: 3.6
Type: String or Float
- python_versions¶
A list of the version(s) of Python to use when performing tests with Tox, e.g.
python_versions: - 3.6 - 3.7 - 3.8 - pypy3
If undefined the value of
python_deploy_versionis used instead.For more advanced configuration, this may instead be a mapping of version number strings to mappings of options, e.g.:
python_versions: 3.6: 3.7: 3.8: pypy3: experimental: false
PyPy 3.7 and prerelease versions of CPython are treated as experimental by default unless overridden.
Changed in version 2022.4.4: Added support for mappings as well as lists.
Required: no
Default: The value of
_default_python_versionsType: Sequence or Mapping
- requires_python¶
The minimum required version of Python.
Example:
requires_python: 3.6.1
New in version 2021.2.18.
Required: no
Default: None
Type: String or Float
- third_party_version_matrix¶
A mapping of third party library names to the version number(s) to test.
The special value “latest” indicates the latest version of the library should be used.
third_party_version_matrix: attrs: - 19.3 - 20.1 - 20.2 - latest
This would translate into the following tox testenvs:
py36-attrs{19.3,20.1,20.2,latest}
and the following tox requirements:
attrs19.3: attrs~=19.3.0 attrs20.1: attrs~=20.1.0 attrs20.2: attrs~=20.2.0 attrslatest: attrs
which is
<name>~={<version>).0.New in version 2020.12.21.
Note
Currently matrices are only supported for a single third-party requirement.
Required: no
Default: { }
Type: Mapping of String to Sequence of String or Float
The lowest version of Python given above is used to set the minimum supported version for Pip, PyPI, setuptools etc.
Packaging¶
- additional_requirements_files¶
A list of files containing additional requirements.
These may define “extras” (see
extras_require). Used in.readthedocs.yml.Example:
additional_requirements_files: - submodule/requirements.txt
This list is automatically populated with any filenames specified in
extras_require.Any files specified here are listed in
MANIFEST.infor inclusion in distributions.Required: no
Default: [ ]
Type: Sequence of String
- additional_setup_args¶
A dictionary of additional keyword arguments for
setuptools.setup(). The values can refer to variables in__pkginfo__.py. String values must be enclosed in quotes here.Example:
additional_setup_args: author: "'Dominic Davis-Foster'" entry_points: "None"
Required: no
Default: { }
Type: Mapping of String to String
- console_scripts¶
A list of entries for
console_scriptsinsetup.py. Each entry must follow the same format as required insetup.py.Example:
console_scripts: - "repo_helper = repo_helper.__main__:main" - "git-helper = repo_helper.__main__:main"
Required: no
Default: [ ]
Type: Sequence of String
- extras_require¶
A dictionary of extra requirements, where the keys are the names of the extras and the values are a list of requirements.
Example:
extras_require: extra_a: - pytz >=2019.1
or
extras_require: extra_a: pytz >=2019.1
or
extras_require: extra_a: < a filename >
Required: no
Default: { }
Type: Mapping of String to String
- manifest_additional¶
A list of additional entries for
MANIFEST.in.Example:
manifest_additional: - "recursive-include: repo_helper/templates *"
Required: no
Default: [ ]
Type: Sequence of String
- platforms¶
A case-insensitive list of platforms to perform tests for.
Example:
platforms: - Windows - macOS - Linux
These values determine the GitHub test workflows to enable, and the Trove classifiers used on PyPI.
Required: no
Default: [‘Windows’, ‘macOS’, ‘Linux’]
Type: Sequence of ‘Windows’ or ‘macOS’ or ‘Linux’
Allowed values:
Windows,macOS,Linux
- py_modules¶
A list of values for
py_modulesinsetup.py, which indicate the single-file modules to include in the distributions.Example:
py_modules: - domdf_spreadsheet_tools
Required: no
Default: [ ]
Type: Sequence of String
- setup_pre¶
A list of additional python lines to insert at the beginnning of
setup.py.Example:
setup_pre: - import datetime - print(datetim.datetime.today())
Required: no
Default: [ ]
Type: Sequence of String
- entry_points¶
A mapping of entry point categories to a list of entries for each category.
Each entry should be valid as per https://packaging.python.org/specifications/entry-points/
Example:
entry_points: pytest11: - "nbval = nbval.plugin"
Required: no
Default: { }
Type: Mapping of String to Sequence of String
Documentation¶
- docs_dir¶
The directory containing the docs code of the project.
Example:
docs_dir: docs
Required: no
Default:
doc-sourceType: String
- enable_docs¶
Whether documentation should be built and deployed.
Example:
enable_docs: True
Required: no
Default:
TrueType: Boolean
- extra_sphinx_extensions¶
A list of additional extensions to enable for Sphinx.
Example:
extra_sphinx_extensions: - "sphinxcontrib.httpdomain"
These must also be listed in
doc-source/requirements.txt.Required: no
Default: [ ]
Type: Sequence of String
- html_context¶
A dictionary of configuration values for the documentation HTML context.
String values must be encased in quotes.
Example:
html_context: display_github: True github_user: "'domdfcoding'"
Required: no
Default: { }
Type: Mapping of String to anything
- html_theme_options¶
A dictionary of configuration values for the documentation HTML theme.
String values must be encased in quotes.
Example:
html_theme_options: logo_only: False fixed_sidebar: "'false'" github_type: "'star'"
Required: no
Default: { }
Type: Mapping of String to anything
- intersphinx_mapping¶
A list of additional entries for
intersphinx_mappingfor Sphinx.Each entry must be enclosed in double quotes.
Example:
intersphinx_mapping: - "'rtd': ('https://docs.readthedocs.io/en/latest/', None)"
Required: no
Default: [ ]
Type: Sequence of String
- preserve_custom_theme¶
Whether custom documentation theme styling in
_static/style.cssand_templates/layout.htmlshould be preserved.Example:
preserve_custom_theme: True
Required: no
Default:
FalseType: Boolean
The name of the author to show on ReadTheDocs, if different.
Example:
rtfd_author: Dominic Davis-Foster and Joe Bloggs
Required: no
Default: The value of
authorType: String
- sphinx_conf_epilogue¶
Like
sphinx_conf_preamble, but the lines are inserted at the end of the file.Indent lines with a single tab to form part of the
setupfunction.Required: no
Default: [ ]
Type: Sequence of String
- sphinx_conf_preamble¶
A list of lines of Python code to add to the top of
conf.py.These could be additional settings for Sphinx or calls to extra scripts that must be executed before building the documentation.
Example:
sphinx_conf_preamble: - "import datetime" - "now = datetime.datetime.now()" - "strftime = now.strftime('%H:%M')" - "print(f'Starting building docs at {strftime}.')"
Required: no
Default: [ ]
Type: Sequence of String
- sphinx_html_theme¶
The HTML theme to use for Sphinx.
Also adds the appropriate values to
extra_sphinx_extensions,html_theme_options, andhtml_context_options.Example:
sphinx_html_theme: alabaster
Currently, the supported themes are sphinx_rtd_theme, domdf_sphinx_theme, alabaster, and furo.
Required: no
Default:
domdf-sphinx-themeType: ‘sphinx_rtd_theme’ or ‘sphinx-rtd-theme’ or ‘alabaster’ or ‘repo_helper_sphinx_theme’ or ‘repo-helper-sphinx-theme’ or ‘domdf_sphinx_theme’ or ‘domdf-sphinx-theme’ or ‘furo’
Allowed values:
sphinx_rtd_theme,sphinx-rtd-theme,alabaster,repo_helper_sphinx_theme,repo-helper-sphinx-theme,domdf_sphinx_theme,domdf-sphinx-theme,furo
- standalone_contrib_guide¶
Whether the contributing guide for the documentation should be a standlone page.
Example:
standalone_contrib_guide: True
Required: no
Default:
FalseType: Boolean
- docs_url¶
The URL of the documentation, if it uses a custom domain. Default
https://{repo_name}.readthedocs.io.Example:
docs_url: docs.repo-helper.uk
Required: no
Default: None
Type: String
Testing¶
- enable_tests¶
Whether tests should be performed with pytest.
Example:
enable_tests: True
Required: no
Default:
TrueType: Boolean
- mypy_deps¶
A list of additional packages to install in Tox when running mypy. Usually type stubs.
mypy_deps: - docutils-stubs - webcolors-stubs - gi-stubs
Required: no
Default: [ ]
Type: Sequence of String
- extra_lint_paths¶
A list of additional files or directories to check with flake8 and mypy.
extra_lint_paths: - tools - utils - demo.py
New in version 2022.4.4.
Required: no
Default: [ ]
Type: Sequence of String
- extra_testenv_commands¶
A list of additional commands to run in the primary testenv, after running the tests themselves.
extra_testenv_commands: - python coverage-fixup.py
New in version 2022.4.4.
Required: no
Default: [ ]
Type: Sequence of String
- mypy_plugins¶
A list of plugins to enable for mypy.
Example:
mypy_plugins: - /one/plugin.py - other.plugin - custom_plugin:custom_entry_point
See https://mypy.readthedocs.io/en/stable/extending_mypy.html#extending-mypy-using-plugins for more info.
Required: no
Default: [ ]
Type: Sequence of String
- tests_dir¶
The directory containing tests, relative to the repository root.
tests_dir: "tests"
If undefined it is assumed to be
tests.Required: no
Default:
testsType: String
- tox_build_requirements¶
A list of additional Python build requirements for Tox.
Example:
tox_build_requirements: - setuptools
Required: no
Default: [ ]
Type: Sequence of String
- tox_requirements¶
A list of additional Python requirements for Tox.
Example:
tox_requirements: - flake8
Required: no
Default: [ ]
Type: Sequence of String
- tox_testenv_extras¶
The “Extra” requirement to install when installing the package in the Tox testenv.
Example:
tox_testenv_extras: - docs
Required: no
Default: <blank>
Type: String
- mypy_version¶
The version of
mypyto use.Example:
mypy_version: 0.790
Changed in version 2021.2.18: The default is now
0.800Changed in version 2021.8.11: The default is now
0.910Changed in version 2022.4.4: The default is now
0.931Required: no
Default:
0.942Type: String or Float
- enable_devmode¶
Enable Python Development Mode when running tests.
Example:
enable_devmode: True
Required: no
Default:
TrueType: Boolean
- tox_unmanaged¶
A list of section names in
tox.iniwhich should not be managed byrepo-helper.Example:
tox_unmanaged: - "testenv" - "flake8"
Required: no
Default: [ ]
Type: Sequence of String
- min_coverage¶
The minimum permitted test coverage percentage.
Example:
mypy_version: 0.790
New in version 2020.1.27.
Required: no
Default:
80Type: String or Float
- github_ci_requirements¶
Additional steps to run in GitHub actions before and after installing dependencies.
New in version 2021.8.11.
Example:
github_ci_requirements: Linux: pre: - sudo apt update - sudo apt install python3-gi macOS: post: - "Installation Complete!"
Required: no
Default: { }
Type: Mapping of String to Mapping of String to Sequence of String
Travis¶
Options for configuring Travis.
- travis_additional_requirements¶
A list of additional Python requirements for Travis.
Example:
travis_additional_requirements: - pbr
Required: no
Default: [ ]
Type: Sequence of String
- travis_extra_install_post¶
Additional steps to run in Travis after installing dependencies.
Example:
travis_extra_install_post: - echo "Installation Complete!"
Required: no
Default: [ ]
Type: Sequence of String
- travis_extra_install_pre¶
Additional steps to run in Travis before installing dependencies.
Example:
travis_extra_install_pre: - sudo apt update - sudo apt install python3-gi
Required: no
Default: [ ]
Type: Sequence of String
- travis_ubuntu_version¶
The Travis Ubuntu version.
Example:
travis_ubuntu_version: "xenial"
Required: no
Default:
focalType: ‘focal’ or ‘bionic’ or ‘xenial’ or ‘trusty’ or ‘precise’
Allowed values:
focal,bionic,xenial,trusty,precise
Conda & Anaconda¶
- conda_channels¶
A list of Anaconda channels required to build and use the Conda package.
Example:
conda_channels: - domdfcoding - conda-forge - bioconda
Required: no
Default: [ ]
Type: Sequence of String
- conda_extras¶
A list of extras (see
extras_require) to include as requirements in the Conda package.The special keywordallindicates all extras should be included.The special keywordnoneindicates no extras should be included.Example:
conda_extras: - plotting - xml
New in version 2020.11.12.
Required: no
Default: [‘all’]
Type: Sequence of String
- conda_description¶
A short description of the project for Anaconda.
Example:
conda_description: This is a short description of my project.
A list of required Anaconda channels is automatically appended.
Required: no
Default: The value of
short_descType: String
Other¶
- additional_ignore¶
A list of additional entries for
.gitignore.Example:
additional_ignore: - "*.pyc"
Required: no
Default: [ ]
Type: Sequence of String
- exclude_files¶
A list of files not to manage with repo_helper.
exclude_files: - conf - tox
Valid values are as follows:
Value
File(s) that will not be managed
lint_roller
lint_roller.shstale_bot
.github/stale.ymlauto_assign
.github/workflow/assign.ymland.github/auto_assign.ymlreadme
README.rstdoc_requirements
doc-source/requirements.txtpylintrc
.pylintrcmanifest
MANIFEST.insetup
setup.pypkginfo
__pkginfo__.pyconf
doc-source/conf.pygitignore
.gitignorertfd
.readthedocs.ymltravis
.travis.ymltox
tox.initest_requirements
tests_dir/requirements.txtdependabot
.dependabot/config.ymlmake_conda_recipe
make_conda_recipe.pybumpversion
.bumpversion.cfgissue_templates
.github/ISSUE_TEMPLATE/bug_report.mdand.github/ISSUE_TEMPLATE/feature_request.md404
<docs_dir>/not-found.pngand<docs_dir>/404.rstmake_isort
isort.cfgRequired: no
Default: [ ]
Type: Sequence of String
- imgbot_ignore¶
A list of additional glob ignores for imgbot.
Example:
imgbot_ignore: - "**/*.svg"
Required: no
Default: [ ]
Type: Sequence of String
- yapf_exclude¶
A list of regular expressions to use to exclude files and directories from autoformatting.
Example:
yapf_exclude: - ".*/templates/.*"
Required: no
Default: [ ]
Type: Sequence of String
- pre_commit_exclude¶
Regular expression for files that should not be checked by pre_commit.
pre_commit_exclude: "^.*\\._py$"
Required: no
Default:
^$Type: String
- desktopfile¶
A key value mapping of entries for a Linux
.desktopfile.desktopfile: Exec: wxIconSaver Icon: document-save
Version,NameandCommentare pre-populated fromversion,modnameandshort_desc.New in version 2020.11.15.
Required: no
Default: { }
Type: Mapping of String to String
repo-helper¶
Update files in the given repositories, based on settings in ‘repo_helper.yml’.
repo-helper [OPTIONS] COMMAND [ARGS]...
Options
-
-f,--force¶ Run ‘repo_helper’ even when the git working directory is not clean.
-
-y,--commit,-n,--no-commit¶ Commit or do not commit any changed files.
- Default
Ask first
-
-m,--message<message>¶ The commit message to use.
- Default
Updated files with ‘repo_helper’.
-
--version¶ Show the version and exit.
repo-helper add¶
Add metadata.
New in version 2021.8.11.
repo-helper broomstick¶
Clean up build and test artefacts 🧹.
Removes the following:
build
.mypy_cache
.pytest_cache
**/__pytest__
*.egg-info
repo-helper broomstick [OPTIONS]
Options
-
-v,--verbose¶ Show verbose output.
-
--rm-tox¶ Also remove the ‘.tox’ directory
repo-helper init¶
Initialise the repository with some boilerplate files.
repo-helper init [OPTIONS]
Options
-
-m,--message<message>¶ The commit message to use.
- Default
Initialised repository with ‘repo_helper’.
-
-y,--commit,-n,--no-commit¶ Commit or do not commit any changed files.
- Default
Commit automatically
-
-f,--force¶ Run ‘repo_helper’ even when the git working directory is not clean.
repo-helper make-recipe¶
Register the schema mapping for repo_helper.yml with PyCharm.
repo-helper make-recipe
This command takes no options.
repo-helper release¶
Make a release 🚀.
repo-helper release [OPTIONS] COMMAND [ARGS]...
Commands
-
major Bump to the next major version.
-
minor Bump to the next minor version.
-
patch Bump to the next patch version.
-
today Bump to the calver version for today’s date, such as 2020.12.25.
-
<version> Bump to the given version.
Options
Each command takes the following options:
-
-m,--message<message>¶ The commit message to use.
- Default
Bump version {current_version} -> {new_version}
-
-y,--commit,-n,--no-commit¶ Commit or do not commit any changed files.
- Default
Commit automatically
-
-f,--force¶ Make a release even when the git working directory is not clean.
repo-helper show¶
Show information about the repository.
log¶
Show git commit log.
repo-helper show log [OPTIONS]
Options
-
--no-pager¶ Disable the output pager.
-
--colour,--no-colour¶ Whether to use coloured output.
-
--from-tag<from_tag>¶ Show commits after the given tag.
-
--from-date<from_date>¶ Show commits after the given date.
-
-r,--reverse¶ Print entries in reverse order.
-
-n,--entries<entries>¶ Maximum number of entries to display.
changelog¶
Show commits since the last version tag.
repo-helper show changelog [OPTIONS]
Options
-
--no-pager¶ Disable the output pager.
-
--colour,--no-colour¶ Whether to use coloured output.
-
-r,--reverse¶ Print entries in reverse order.
-
-n,--entries<entries>¶ Maximum number of entries to display.
requirements¶
Lists the requirements of this library, and their dependencies.
repo-helper show requirements [OPTIONS]
Options
-
--no-venv¶ Don’t search a ‘venv’ directory in the repository for the requirements.
-
-c,--concise¶ Show a consolidated list of all dependencies.
-
-d,--depth<depth>¶ The maximum depth to display. -1 means infinite depth.
- Default
-1
-
--no-pager¶ Disable the output pager.
Changed in version 2020.12.3: Added the -c / --concise option.
repo-helper suggest¶
Suggest trove classifiers and keywords.
classifiers¶
Suggest trove classifiers based on repository metadata.
repo-helper suggest classifiers [OPTIONS]
Options
-
-l,--library,--not-library¶ Indicates this project is a library for developers.
-
-s,--status<status>¶ The Development Status of this project.
-
--add,--no-add¶ Add the classifiers to the ‘repo_helper.yml’ file.
repo-helper wizard¶
Run the wizard 🧙 to create a repo_helper.yml file.
repo-helper wizard
This command takes no options.
repo_helper.blocks¶
Reusable blocks of reStructuredText.
Classes:
|
Create the shields block for insertion into the README, documentation etc. |
Functions:
|
Create the installation instructions for insertion into the documentation. |
|
Create the documentation links block. |
|
Create the installation instructions for insertion into the README. |
|
Creates the short description block insertion into the README, documentation etc. |
Loads the docs_installation_block template from file and returns a jinja2 |
|
Loads the docs_links_block template from file and returns a jinja2 |
|
Loads the readme_installation_block_no_pypi template from file and returns a jinja2 |
|
Loads the readme_installation_block template from file and returns a jinja2 |
Data:
Regular expression to match the installation block placeholder. |
|
Regular expression to match the links block placeholder. |
|
Regular expression to match the shields block placeholder. |
|
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, unique_name='', docker_shields=False, docker_name='', platforms=None, pre_commit=False, on_pypi=True, primary_conda_channel=None)[source]¶ Bases:
objectCreate 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.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 ofrepo_nameif unset. DefaultNone.unique_name (
str) – An optional unique name for the reST substitutions. Default''.docker_shields (
bool) – Whether to show shields for Docker. DefaultFalse. DefaultFalse.docker_name (
str) – The name of the Docker image on DockerHub. Default''.platforms (
Optional[Iterable[str]]) – List of supported platforms. DefaultNone.primary_conda_channel (
Optional[str]) – The Conda channel the package can be downloaded from. DefaultNone.
New in version 2020.12.11.
Methods:
make()Constructs the contents of the shields block.
Create shields for insertion into Sphinx documentation.
Create shields for insertion into
README.rst.Attributes:
This list controls which sections are included, and their order.
This list controls which substitutions are included, and their order.
-
sections= ('Docs', 'Tests', 'PyPI', 'Anaconda', 'Activity', 'QA', 'Docker', 'Other')¶ Type:
tupleThis list controls which sections are included, and their order.
-
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:
tupleThis list controls which substitutions are included, and their order.
-
create_docs_install_block(repo_name, username, conda=True, pypi=True, pypi_name=None, conda_channels=None)[source]¶ 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 withcreate_readme_install_block())conda (
bool) – Whether to show Anaconda installation instructions. DefaultTrue.pypi (
bool) – Whether to show PyPI installation instructions. DefaultTrue.pypi_name (
Optional[str]) – The name of the project on PyPI. Defaults to the value ofrepo_nameif unset. DefaultNone.conda_channels (
Optional[Sequence[str]]) – List of required Conda channels. DefaultNone.
- Return type
- Returns
The installation block created from the above settings.
-
create_readme_install_block(modname, username, conda=True, pypi=True, pypi_name=None, conda_channels=None)[source]¶ 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. DefaultTrue.pypi (
bool) – Whether to show PyPI installation instructions. DefaultTrue.pypi_name (
Optional[str]) – The name of the project on PyPI. Defaults to the value ofrepo_nameif unset. DefaultNone.conda_channels (
Optional[Sequence[str]]) – List of required Conda channels. DefaultNone.
- Return type
- Returns
The installation block created from the above settings.
-
create_short_desc_block(short_desc)[source]¶ Creates the short description block insertion into the README, documentation etc.
-
get_docs_installation_block_template()[source]¶ Loads the docs_installation_block template from file and returns a jinja2
jinja2.environment.Templatefor it.- Return type
Template
-
get_docs_links_block_template()[source]¶ Loads the docs_links_block template from file and returns a jinja2
jinja2.environment.Templatefor it.- Return type
Template
-
get_readme_installation_block_no_pypi_template()[source]¶ Loads the readme_installation_block_no_pypi template from file and returns a jinja2
jinja2.environment.Templatefor it.New in version 2020.12.1.
- Return type
Template
-
get_readme_installation_block_template()[source]¶ Loads the readme_installation_block template from file and returns a jinja2
jinja2.environment.Templatefor it.- Return type
Template
-
installation_regex¶ Type:
PatternRegular expression to match the installation block placeholder.
Pattern
(.. start installation)(.*?)(.. end installation)Flags
-
links_regex¶ Type:
PatternRegular expression to match the links block placeholder.
Pattern
(.. start links)(.*?)(.. end links)Flags
repo_helper.conda¶
Utilities for Conda packages.
Functions:
|
Make a Conda |
repo_helper.core¶
Core functionality of repo_helper.
Classes:
|
Repo Helper: Manage configuration files with ease. |
Functions:
Returns a list of all registered functions. |
-
class
RepoHelper(target_repo, managed_message="This file is managed by 'repo_helper'. Don't edit it directly.")[source]¶ Repo Helper: Manage configuration files with ease.
- Parameters
Attributes:
A tuple of excluded files that should NOT be managed by Git Helper.
List of functions to manage files.
Message placed at the top of files to indicate that they are managed by
repo_helper.The name of the repository being managed.
The target repository
Provides the templates and stores the configuration.
Methods:
load_settings([allow_unknown_keys])Load settings from the
repo_helper.ymlfile in the repository.run()Run Git Helper for the repository and update all managed files.
-
property
exclude_files¶ A tuple of excluded files that should NOT be managed by Git Helper.
-
files¶ Type:
ManagementList of functions to manage files.
-
load_settings(allow_unknown_keys=False)[source]¶ Load settings from the
repo_helper.ymlfile in the repository.- Parameters
allow_unknown_keys (
bool) – Whether unknown keys should be allowed in the configuration file. DefaultFalse.
Changed in version 2021.2.18:This method is no longer called automatically when instantiating the
RepoHelperclass.Added the
allow_unknown_keysargument.
-
property
managed_message¶ Message placed at the top of files to indicate that they are managed by
repo_helper.- Return type
-
templates¶ Type:
EnvironmentProvides the templates and stores the configuration.
repo_helper.release¶
Functions for making tagged releases.
New in version 2020.12.29.
Classes:
|
Class to bump the repository version. |
Represents the subset of |
-
class
Bumper(repo_path, force=False)[source]¶ Bases:
objectClass to bump the repository version.
- Parameters
Methods:
bump(new_version, commit, message)Bump to the given version.
bump_version_for_file(filename, config)Bumps the version for the given file.
get_bumpversion_config(current_version, …)Returns the bumpversion config.
Returns the current version from the
repo_helper.ymlconfiguration file.major(commit, message)Bump to the next major version.
minor(commit, message)Bump to the next minor version.
patch(commit, message)Bump to the next patch version.
today(commit, message)Bump to the calver version for today’s date.
Attributes:
The path to the bumpversion configuration file.
-
bump(new_version, commit, message)[source]¶ Bump to the given version.
- Parameters
Changed in version 2021.8.11: Now takes a
packaging.version.Versionrather than adomdf_python_tools.versions.Version.
-
bump_version_for_file(filename, config)[source]¶ Bumps the version for the given file.
- Parameters
config (
BumpversionFileConfig)
-
bumpversion_file¶ The path to the bumpversion configuration file.
-
current_version¶
-
get_bumpversion_config(current_version, new_version)[source]¶ Returns the bumpversion config.
- Parameters
- Return type
-
get_current_version()[source]¶ Returns the current version from the
repo_helper.ymlconfiguration file.- Return type
-
repo¶
repo_helper.shields¶
Create a variety of shields, most powered by https://shields.io/.
Functions:
|
Create a shield to indicate the status of the tests on Linux. |
|
Create a shield to indicate the status of the tests on macOS. |
|
Create a shield to indicate the status of the tests on Linux. |
|
Create a shield to indicate the status of the tests on Windows. |
|
Create a shield to show the number of commits to the GitHub repository since the last release. |
|
Create a shield to show the Codefactor code quality grade. |
|
Create a shield to show the supported Conda platforms. |
|
Create a shield to show the version on Conda. |
|
Create a shield to show the code coverage from Coveralls. |
Create a shield to indicate the Docker automated build status. |
|
|
Create a shield to indicate the Docker image build status. |
|
Create a shield to indicate the size of a docker image. |
|
Create a shield for the GitHub Actions “Docs Check” status. |
|
Create a shield to show the primary language of the GitHub repository. |
|
Create a shield to indicate when the last commit to the GitHub repository occurred. |
|
Create a shield to show the license of the GitHub repository. |
Create a shield to indicate that the project is maintained. |
|
|
Create a shield to show the pre-commit.ci status. |
Create a shield to show that a repository is configured for use with pre-commit. |
|
|
Create a shield to show the PyPI download statistics. |
|
Create a shield to show the version on PyPI. |
|
Create a shield to show the supported Python implementations for the library. |
|
Create a shield to show the supported Python versions for the library. |
|
Create a shield to show the dependency-dash requirements status. |
|
Create a shield for the ReadTheDocs documentation build status. |
Create a shield to show that a library has PEP 484 Type Hints / Annotations. |
|
|
Create a shield to show whether the library has a wheel on PyPI. |
-
make_actions_linux_shield(repo_name, username)[source]¶ Create a shield to indicate the status of the tests on Linux.
-
make_actions_macos_shield(repo_name, username)[source]¶ Create a shield to indicate the status of the tests on macOS.
-
make_actions_shield(repo_name, username, name, alt)[source]¶ Create a shield to indicate the status of the tests on Linux.
- Parameters
- Return type
- Returns
The shield.
New in version 2020.12.16.
-
make_actions_windows_shield(repo_name, username)[source]¶ Create a shield to indicate the status of the tests on Windows.
-
make_activity_shield(repo_name, username, version)[source]¶ Create a shield to show the number of commits to the GitHub repository since the last release.
-
make_codefactor_shield(repo_name, username)[source]¶ Create a shield to show the Codefactor code quality grade.
-
make_conda_platform_shield(pypi_name, username)[source]¶ Create a shield to show the supported Conda platforms.
-
make_conda_version_shield(pypi_name, username)[source]¶ Create a shield to show the version on Conda.
-
make_coveralls_shield(repo_name, username)[source]¶ Create a shield to show the code coverage from Coveralls.
-
make_docker_automated_build_shield(docker_name, username)[source]¶ Create a shield to indicate the Docker automated build status.
-
make_docker_build_status_shield(docker_name, username)[source]¶ Create a shield to indicate the Docker image build status.
-
make_docker_size_shield(docker_name, username)[source]¶ Create a shield to indicate the size of a docker image.
-
make_docs_check_shield(repo_name, username)[source]¶ Create a shield for the GitHub Actions “Docs Check” status.
-
make_language_shield(repo_name, username)[source]¶ Create a shield to show the primary language of the GitHub repository.
-
make_last_commit_shield(repo_name, username)[source]¶ Create a shield to indicate when the last commit to the GitHub repository occurred.
-
make_license_shield(repo_name, username)[source]¶ Create a shield to show the license of the GitHub repository.
-
make_maintained_shield()[source]¶ Create a shield to indicate that the project is maintained.
- Returns
The shield.
- Return type
-
make_pre_commit_ci_shield(repo_name, username)[source]¶ Create a shield to show the pre-commit.ci status.
-
make_pre_commit_shield()[source]¶ Create a shield to show that a repository is configured for use with pre-commit.
- Returns
The shield.
- Return type
-
make_pypi_downloads_shield(pypi_name)[source]¶ Create a shield to show the PyPI download statistics.
-
make_python_implementations_shield(pypi_name)[source]¶ Create a shield to show the supported Python implementations for the library.
-
make_python_versions_shield(pypi_name)[source]¶ Create a shield to show the supported Python versions for the library.
-
make_requires_shield(repo_name, username)[source]¶ Create a shield to show the dependency-dash requirements status.
-
make_rtfd_shield(repo_name, target='https://{}.readthedocs.io/en/latest/?badge=latest')[source]¶ Create a shield for the ReadTheDocs documentation build status.
repo_helper.templates¶
Contains the pathlib.Path objects representing the templates directory (template_dir),
and the directory representing the files used to initialise a new repository (init_repo_template_dir).
-
template_dir¶ Type:
PosixPathPlusThe templates directory.
-
init_repo_template_dir¶ Type:
PosixPathPlusThe directory representing the files used to initialise a new repository
repo_helper.testing¶
Helpers for running tests with pytest.
Attention
This module has the following additional requirements:
check-wheel-contents>=0.2.0 coincidence>=0.2.0 pytest>=6.2.0
These can be installed as follows:
python -m pip install repo-helper[testing]
New in version 2020.11.17.
Functions:
Pytest fixture to create a jinja2 environment for use in tests. |
|
Returns the contents of the example |
|
Returns |
|
|
Pytest fixture to return an empty git repository in a temporary location. |
|
Pytest fixture to return a git repository in a temporary location. |
-
fixture
demo_environment[source]¶ Scope: function
Pytest fixture to create a jinja2 environment for use in tests.
The environment has the following variables available by default:
{ "username": "octocat", "assignee": "octocat", "imgbot_ignore": [], "travis_ubuntu_version": "xenial", "github_ci_requirements": {"Linux": {"pre": [], "post": []}}, "travis_additional_requirements": [], "conda_channels": ["conda-forge"], "python_versions": ["3.6", "3.7"], "enable_tests": true, "enable_conda": true, "enable_docs": true, "enable_releases": true, "python_deploy_version": "3.6", "min_py_version": "3.6", "modname": "hello-world", "repo_name": "hello-world", "import_name": "hello_world", "platforms": ["Windows"], "pypi_name": "hello-world", "py_modules": [], "extra_lint_paths": [], "extra_testenv_commands": [], "manifest_additional": [], "additional_requirements_files": [], "source_dir": "", "tests_dir": "tests", "additional_setup_args": {}, "setup_pre": [], "docs_dir": "doc-source", "sphinx_html_theme": "alabaster", "additional_ignore": ["foo", "bar", "fuzz"], "join_path": "os.path.join", "pure_python": true, "stubs_package": false, "managed_message": "This file is managed by 'repo_helper'. Don't edit it directly.", "short_desc": "a short description", "on_pypi": true, "docs_fail_on_warning": false, "requires_python": "3.6.1", "third_party_version_matrix": {}, "use_whey": false, "use_flit": false }
plus
lint_warn_list=repo_helper.files.linting.lint_warn_list.Additional options can be set and values changed at the start of tests as follows:
def test(demo_environment): demo_environment.templates.globals["source_dir"] = "src"
- Return type
Environment
-
fixture
example_config[source]¶ Scope: session
Returns the contents of the example
repo_helper.ymlfile.- Return type
-
fixture
temp_empty_repo[source]¶ Scope: function
Pytest fixture to return an empty git repository in a temporary location.
repo_helper.utils.todayis monkeypatched to return 25th July 2020.- Return type
-
fixture
temp_repo[source]¶ Scope: function
Pytest fixture to return a git repository in a temporary location.
The repository will contain a
repo_helper.ymlyaml file, the contents of which can be seen at https://github.com/domdfcoding/repo_helper/blob/master/repo_helper/testing/repo_helper_example.yml.repo_helper.utils.todayis monkeypatched to return 25th July 2020.- Return type
repo_helper.utils¶
General utilities.
Classes:
|
Base class to generate |
Functions:
|
Commit staged changes. |
|
Returns a list of entry points in the given category, optionally filtered by |
|
Obtain the license text for the given license. |
|
Join an iterable of strings with newlines, and indent each line with a tab if there is more then one element. |
|
Adds |
|
Returns the subset of |
|
Normalize the given name for PyPI et al. |
|
Format a Python object into a pretty-printed representation. |
|
Reformat the given file. |
|
Retrieve the path to a resource inside a package. |
|
Convert development Python versions into the appropriate versions for GitHub Actions. |
|
Sort the |
|
Stage any files that have been updated, added or removed. |
Data:
Mapping of license short codes to license names used in trove classifiers. |
|
Under normal circumstances returns |
-
class
IniConfigurator(base_path)[source]¶ Bases:
objectBase class to generate
.iniconfiguration files.- Parameters
base_path (
Path)
Methods:
copy_existing_value(section, key)Copy the existing value for
key, if present, to the new configuration.merge_existing(ini_file)Merge existing sections in the configuration file into the new configuration.
Write out to the
.inifile.-
copy_existing_value(section, key)[source]¶ Copy the existing value for
key, if present, to the new configuration.- Parameters
section (
Section)key (
str)
-
commit_changes(repo, message="Updated files with 'repo_helper'.")[source]¶ Commit staged changes.
- Parameters
- Return type
- Returns
The SHA of the commit.
New in version 2020.11.23.
-
discover_entry_points(group_name, match_func=None)[source]¶ Returns a list of entry points in the given category, optionally filtered by
match_func.New in version 1.1.0.
- Parameters
- Return type
- Returns
List of matching objects.
-
get_license_text(license_name, copyright_years, author, project_name)[source]¶ Obtain the license text for the given license.
New in version 2022.4.4.
- Parameters
license_name (
str) – The name of the license.copyright_years (
Union[str,int]) – The copyright years (e.g.'2019-2021') to display in the license. Not supported by all licenses.author (
str) – The name of the author/copyright holder to display in the license. Not supported by all licenses.project_name (
str) – The name of the project to display in the license. Not supported by all licenses.
Licenses are obtained from https://github.com/licenses/license-templates.
-
indent_join(iterable)[source]¶ Join an iterable of strings with newlines, and indent each line with a tab if there is more then one element.
-
indent_with_tab(text, depth=1, predicate=None)[source]¶ Adds
'\t'to the beginning of selected lines in ‘text’.- Parameters
text (
str) – The text to indent.depth (
int) – The depth of the indentation. Default1.predicate (
Optional[Callable[[str],bool]]) – If given,'\t'will only be added to the lines wherepredicate(line)is :py:obj`True`. Ifpredicateis not provided, it will default to adding'\t'to all non-empty lines that do not consist solely of whitespace characters. DefaultNone.
- Return type
-
license_lookup= {'AAL': 'Attribution Assurance License', 'AFL-1.1': 'Academic Free License (AFL)', 'AFL-1.2': 'Academic Free License (AFL)', 'AFL-2.0': 'Academic Free License (AFL)', 'AFL-2.1': 'Academic Free License (AFL)', 'AFL-3.0': 'Academic Free License (AFL)', 'AGPL-3.0': 'GNU Affero General Public License v3', 'AGPL-3.0+': 'GNU Affero General Public License v3 or later (AGPLv3+)', 'AGPL-3.0-only': 'GNU Affero General Public License v3', 'AGPL-3.0-or-later': 'GNU Affero General Public License v3 or later (AGPLv3+)', 'APSL-1.0': 'Apple Public Source License', 'APSL-1.1': 'Apple Public Source License', 'APSL-1.2': 'Apple Public Source License', 'APSL-2.0': 'Apple Public Source License', 'Apache': 'Apache Software License', 'Apache-1.0': 'Apache Software License', 'Apache-1.1': 'Apache Software License', 'Apache-2.0': 'Apache Software License', 'Artistic-1.0': 'Artistic License', 'BSD': 'BSD License', 'BSD-2-Clause': 'BSD License', 'BSD-3-Clause': 'BSD License', 'BSL-1.0': 'Boost Software License 1.0 (BSL-1.0)', 'CDDL-1.0': 'Common Development and Distribution License 1.0 (CDDL-1.0)', 'CNRI-Python': 'Python License (CNRI Python License)', 'CPL-1.0': 'Common Public License', 'EFL-1.0': 'Eiffel Forum License', 'EFL-2.0': 'Eiffel Forum License', 'EPL-1.0': 'Eclipse Public License 1.0 (EPL-1.0)', 'EPL-2.0': 'Eclipse Public License 2.0 (EPL-2.0)', 'EUPL 1.0': 'European Union Public Licence 1.0 (EUPL 1.0)', 'EUPL 1.1': 'European Union Public Licence 1.1 (EUPL 1.1)', 'EUPL 1.2': 'European Union Public Licence 1.2 (EUPL 1.2)', 'FDL': 'GNU Free Documentation License (FDL)', 'GFDL-1.1': 'GNU Free Documentation License (FDL)', 'GFDL-1.1-only': 'GNU Free Documentation License (FDL)', 'GFDL-1.1-or-later': 'GNU Free Documentation License (FDL)', 'GFDL-1.2': 'GNU Free Documentation License (FDL)', 'GFDL-1.2-only': 'GNU Free Documentation License (FDL)', 'GFDL-1.2-or-later': 'GNU Free Documentation License (FDL)', 'GFDL-1.3': 'GNU Free Documentation License (FDL)', 'GFDL-1.3-only': 'GNU Free Documentation License (FDL)', 'GFDL-1.3-or-later': 'GNU Free Documentation License (FDL)', 'GPL': 'GNU General Public License (GPL)', 'GPL-1.0-only': 'GNU General Public License (GPL)', 'GPL-1.0-or-later': 'GNU General Public License (GPL)', 'GPL-2.0-only': 'GNU General Public License v2 (GPLv2)', 'GPL-2.0-or-later': 'GNU General Public License v2 or later (GPLv2+)', 'GPL-3.0-only': 'GNU General Public License v3 (GPLv3)', 'GPL-3.0-or-later': 'GNU General Public License v3 or later (GPLv3+)', 'GPLv2': 'GNU General Public License v2 (GPLv2)', 'GPLv2+': 'GNU General Public License v2 or later (GPLv2+)', 'GPLv3': 'GNU General Public License v3 (GPLv3)', 'GPLv3+': 'GNU General Public License v3 or later (GPLv3+)', 'HPND': 'Historical Permission Notice and Disclaimer (HPND)', 'IPL-1.0': 'IBM Public License', 'ISCL': 'ISC License (ISCL)', 'Intel': 'Intel Open Source License', 'LGPL': 'GNU Library or Lesser General Public License (LGPL)', 'LGPL-3.0-only': 'GNU Lesser General Public License v3 (LGPLv3)', 'LGPL-3.0-or-later': 'GNU Lesser General Public License v3 or later (LGPLv3+)', 'LGPLv2': 'GNU Lesser General Public License v2 (LGPLv2)', 'LGPLv2+': 'GNU Lesser General Public License v2 or later (LGPLv2+)', 'LGPLv3': 'GNU Lesser General Public License v3 (LGPLv3)', 'LGPLv3+': 'GNU Lesser General Public License v3 or later (LGPLv3+)', 'MIT': 'MIT License', 'MPL': 'Mozilla Public License 1.0 (MPL)', 'MPL 1.1': 'Mozilla Public License 1.1 (MPL 1.1)', 'MPL 2.0': 'Mozilla Public License 2.0 (MPL 2.0)', 'MPL-1.0': 'Mozilla Public License 1.0 (MPL)', 'MirOS': 'MirOS License (MirOS)', 'Motosoto': 'Motosoto License', 'NCSA': 'University of Illinois/NCSA Open Source License', 'NGPL': 'Nethack General Public License', 'Nokia': 'Nokia Open Source License', 'OFL-1.1': 'SIL Open Font License 1.1 (OFL-1.1)', 'OGTSL': 'Open Group Test Suite License', 'OSL-3.0': 'Open Software License 3.0 (OSL-3.0)', 'Other': 'Other/Proprietary License', 'PD': 'Public Domain', 'PSF-2.0': 'Python Software Foundation License', 'PostgreSQL': 'PostgreSQL License', 'Proprietary': 'Other/Proprietary License', 'Public Domain': 'Public Domain', 'QPL-1.0': 'Qt Public License (QPL)', 'RSCPL': 'Ricoh Source Code Public License', 'SISSL': 'Sun Industry Standards Source License (SISSL)', 'SISSL-1.2': 'Sun Industry Standards Source License (SISSL)', 'SPL-1.0': 'Sun Public License', 'Sleepycat': 'Sleepycat License', 'UPL': 'Universal Permissive License (UPL)', 'UPL-1.0': 'Universal Permissive License (UPL)', 'VSL-1.0': 'Vovida Software License 1.0', 'W3C': 'W3C License', 'Xnet': 'X.Net License', 'ZPL-1.1': 'Zope Public License', 'ZPL-2.0': 'Zope Public License', 'ZPL-2.1': 'Zope Public License', 'Zlib': 'zlib/libpng License'}¶ Type:
dictMapping of license short codes to license names used in trove classifiers.
-
pformat_tabs(obj, width=80, depth=None, *, compact=False)[source]¶ Format a Python object into a pretty-printed representation.
Indentation is set at one tab.
-
resource(package, resource)[source]¶ Retrieve the path to a resource inside a package.
New in version 2022.4.4.
- Parameters
package – The name of the package, or a module object representing it.
resource – The name of the resource.
-
set_gh_actions_versions(py_versions)[source]¶ Convert development Python versions into the appropriate versions for GitHub Actions.
-
stage_changes(repo, files)[source]¶ Stage any files that have been updated, added or removed.
- Parameters
- Return type
- Returns
A list of staged files. Not all files in
fileswill have been changed, and only changes are staged.
New in version 2020.11.23.
-
today= datetime.date(2022, 4, 4)¶ Type:
dateUnder normal circumstances returns
datetime.date.today().
repo_helper.files¶
The files subpackage contains most of the functions for managing files.
-
Manager¶ Type hint for a function that manages files.
-
class
Management(*args, **kwargs)[source]¶ Bases:
UserList[Tuple[Callable[[Path,Environment],List[str]],str,Sequence[str]]]Class to store functions that manage files.
The syntax of each entry is:
the function,
a string to use in
exclude_filesto disable this function,a list of strings representing config values that must be true to call the function.
Methods:
register(exclude_name[, …])Decorator to register a function.
-
register(exclude_name, exclude_unless_true=(), *, name=None)[source]¶ Decorator to register a function.
The function must have the following signature:
def function( repo_path: pathlib.Path, templates: jinja2.Environment, ) -> List[str]: ...
- Parameters
exclude_name (
str) – A string to use in ‘exclude_files’ to disable this function.exclude_unless_true (
Sequence[str]) – A list of strings representing config values that must be true to call the function. Default().name (
Optional[str]) – Optional name to use for the function in the output. Defaults to the name of the function.
- Return type
- Returns
The registered function.
- Raises
SyntaxErrorif the decorated function does not take the correct arguments.
-
is_registered(obj)[source]¶ Return whether
objis a registered function.- Parameters
obj (
Any)
- Return type
bots¶
Manage configuration files for bots.
Functions:
|
Add configuration for |
|
Add configuration for |
|
Add configuration for |
|
Add configuration for |
|
Add configuration for |
-
make_auto_assign_action(repo_path, templates)[source]¶ Add configuration for
auto-assignto the desired repo.
-
make_dependabot(repo_path, templates)[source]¶ Add configuration for
dependabotto the desired repo.- Parameters
repo_path (
Path) – Path to the repository root.templates (
Environment)
Deprecated since version 2020.12.11.
-
make_dependabotv2(repo_path, templates)[source]¶ Add configuration for
dependabotto the desired repo.- Parameters
repo_path (
Path) – Path to the repository root.templates (
Environment)
New in version 2020.12.11.
ci_cd¶
Manage configuration files for continuous integration / continuous deployment.
Classes:
|
Responsible for creating, updating and removing GitHub Actions workflows. |
Functions:
|
Add configuration for |
|
Returns an iterable of filenames to have the version number bumped in. |
|
Add script to build Conda package and deploy to Anaconda. |
|
Add script to close milestones on release. |
|
Add configuration for testing conda packages on GitHub Actions to the desired repo. |
|
Add configuration for GitHub Actions to the desired repo. |
|
Add configuration for GitHub Actions documentation check to the desired repo. |
|
Add configuration for the Flake8 GitHub Action. |
|
Add configuration for GitHub Actions manylinux wheel builds the desired repo. |
|
Add configuration for the mypy GitHub Action. |
|
Add configuration for the OctoCheese GitHub Action. |
-
class
ActionsManager(repo_path, templates)[source]¶ Bases:
objectResponsible for creating, updating and removing GitHub Actions workflows.
- Parameters
repo_path (
Path) – Path to the repository root.templates (
Environment)
New in version 2020.12.18.
Methods:
Determines the matrix of Python versions used in GitHub Actions.
Prepares the mapping of Python versions to tox testenvs for use with GitHub Actions.
Returns the Python requirements to run tests for on Linux.
Returns the Python versions to run tests for on Linux.
Returns the Python requirements to run tests for on Linux.
Returns the Python requirements to run tests for on macOS.
Returns the Python versions to run tests for on macOS.
Returns the Python requirements to run tests for on Windows.
Returns the Python versions to run tests for on Windows.
Create, update or remove the flake8 action, as appropriate.
Create, update or remove the Linux action, as appropriate.
Create, update or remove the macOS action, as appropriate.
Create, update or remove the mypy action, as appropriate.
Create, update or remove the RustPython action, as appropriate.
Create, update or remove the Windows action, as appropriate.
-
get_gh_actions_matrix()[source]¶ Determines the matrix of Python versions used in GitHub Actions.
New in version 2022.4.4.
-
get_gh_actions_python_versions()[source]¶ Prepares the mapping of Python versions to tox testenvs for use with GitHub Actions.
New in version 2020.12.21.
-
make_flake8()[source]¶ Create, update or remove the flake8 action, as appropriate.
New in version 2021.8.11.
- Return type
-
make_mypy()[source]¶ Create, update or remove the mypy action, as appropriate.
New in version 2020.1.27.
- Return type
-
ensure_bumpversion(repo_path, templates)[source]¶ Add configuration for
bumpversionto the desired repo.
-
get_bumpversion_filenames(templates)[source]¶ Returns an iterable of filenames to have the version number bumped in.
New in version 2021.3.8.
-
make_actions_deploy_conda(repo_path, templates)[source]¶ Add script to build Conda package and deploy to Anaconda.
-
make_conda_actions_ci(repo_path, templates)[source]¶ Add configuration for testing conda packages on GitHub Actions to the desired repo.
-
make_github_ci(repo_path, templates)[source]¶ Add configuration for GitHub Actions to the desired repo.
-
make_github_docs_test(repo_path, templates)[source]¶ Add configuration for GitHub Actions documentation check to the desired repo.
-
make_github_manylinux(repo_path, templates)[source]¶ Add configuration for GitHub Actions manylinux wheel builds the desired repo.
contributing¶
Contributing information for GitHub and documentation, plus GitHub issue templates.
Functions:
|
Formats the given commands in a reStructuredText bash code block suitable for rendering on GitHub. |
|
Add |
|
Add CONTRIBUTING.rst to the documentation directory of the repo. |
|
Add issue templates for GitHub to the desired repo. |
-
github_bash_block(*commands)[source]¶ Formats the given commands in a reStructuredText bash code block suitable for rendering on GitHub.
docs¶
Configuration for documentation with Sphinx and ReadTheDocs.
Functions:
|
Copy custom styling for documentation to the desired repository. |
|
Ensure |
|
|
Make the custom stylesheet for the alabaster Sphinx theme. |
|
|
Add |
|
Create the “License” page in the documentation. |
|
Create the “Source” page in the documentation, and add the associated image. |
|
Add configuration for |
Make the custom stylesheet for the ReadTheDocs Sphinx theme. |
|
|
Add configuration for |
|
Update blocks in the documentation |
-
copy_docs_styling(repo_path, templates)[source]¶ Copy custom styling for documentation to the desired repository.
-
ensure_doc_requirements(repo_path, templates)[source]¶ Ensure
<docs_dir>/requirements.txtcontains the required entries.
-
make_alabaster_theming()[source]¶ Make the custom stylesheet for the alabaster Sphinx theme.
- Return type
- Returns
The custom stylesheet.
-
make_docs_license_rst(repo_path, templates)[source]¶ Create the “License” page in the documentation.
-
make_docs_source_rst(repo_path, templates)[source]¶ Create the “Source” page in the documentation, and add the associated image.
-
make_readthedocs_theming()[source]¶ Make the custom stylesheet for the ReadTheDocs Sphinx theme.
- Return type
- Returns
The custom stylesheet.
-
make_rtfd(repo_path, templates)[source]¶ Add configuration for
ReadTheDocs.See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
gitignore¶
Configuration for the .gitignore file.
Functions:
|
Add .gitignore file to the given repository. |
linting¶
Configuration for various linting tools, such as Flake8 and Pylint.
Functions:
|
Copy |
packaging¶
Manage configuration files for packaging tools.
Functions:
|
Update the |
|
Update the |
|
Create the |
|
Update the |
|
Update the |
pre_commit¶
Configuration for pre-commit.
Data:
Instance of |
Classes:
Represents a pre-commit hook. |
|
|
Represents a repository providing a pre-commit hooks. |
Functions:
|
Construct a URL to a GitHub repository from a username and repository name. |
|
Add configuration for |
-
GITHUB_COM= URL('https://github.com')¶ Type:
URLInstance of
apeye.url.URLthat points to the GitHub website.
-
typeddict
Hook[source]¶ Bases:
dictRepresents a pre-commit hook.
- Required Keys
id (
str) – Which hook from the repository to use.
- Optional Keys
alias (
str) – Allows the hook to be referenced using an additional id when using pre-commit run <hookid>.name (
str) – Override the name of the hook - shown during hook execution.language_version (
str) – Override the language version for the hook. See https://pre-commit.com/#overriding-language-versionfiles (
str) – Override the default pattern for files to run on.exclude (
str) – File exclude pattern.types (
List[str]) – Override the default file types to run on. See https://pre-commit.com/#filtering-files-with-types.args (
List[str]) – List of additional parameters to pass to the hook.stages (
List[Literal['commit','merge-commit','push','prepare-commit-msg','commit-msg','manual']]) – Confines the hook to the commit, merge-commit, push, prepare-commit-msg, commit-msg, post-checkout, or manual stage. See https://pre-commit.com/#confining-hooks-to-run-at-certain-stages.additional_dependencies (
List[str]) – A list of dependencies that will be installed in the environment where this hook gets run. One useful application is to install plugins for hooks such as eslint.always_run (
bool) – IfTrue, this hook will run even if there are no matching files.verbose (
bool) – IfTrue, forces the output of the hook to be printed even when the hook passes.log_file (
str) – If present, the hook output will additionally be written to a file.
-
class
Repo(repo, rev, hooks)[source]¶ Bases:
objectRepresents a repository providing a pre-commit hooks.
Methods:
__eq__(other)Method generated by attrs for class Repo.
__ge__(other)Method generated by attrs for class Repo.
__gt__(other)Method generated by attrs for class Repo.
__le__(other)Method generated by attrs for class Repo.
__lt__(other)Method generated by attrs for class Repo.
__ne__(other)Method generated by attrs for class Repo.
__repr__()Method generated by attrs for class Repo.
to_dict()Returns a dictionary representation of the
Repo.Attributes:
The repository url to git clone from.
The revision or tag to clone at.
-
__eq__(other)¶ Method generated by attrs for class Repo.
-
__ge__(other)¶ Method generated by attrs for class Repo.
-
__gt__(other)¶ Method generated by attrs for class Repo.
-
__le__(other)¶ Method generated by attrs for class Repo.
-
__lt__(other)¶ Method generated by attrs for class Repo.
-
__ne__(other)¶ Method generated by attrs for class Repo.
-
__repr__()¶ Method generated by attrs for class Repo.
-
-
make_github_url(username, repository)[source]¶ Construct a URL to a GitHub repository from a username and repository name.
-
make_pre_commit(repo_path, templates)[source]¶ Add configuration for
pre-commit.https://github.com/pre-commit/pre-commit
# See https://pre-commit.com for more information # See https://pre-commit.com/hooks.html for more hooks
readme¶
Functions to update README files.
Functions:
|
Update blocks in the |
testing¶
Configuration for testing and code formatting tools.
Classes:
|
Generates the |
Functions:
|
Ensure |
|
Add configuration for |
|
Remove the |
|
Add configuration for |
|
Add configuration for |
-
class
ToxConfig(repo_path, templates)[source]¶ Bases:
IniConfiguratorGenerates the
tox.iniconfiguration file.- Parameters
repo_path (
Path) – Path to the repository root.templates (
Environment)
Methods:
__getitem__(item)Passthrough to
templates.globals.[check-wheel-contents].[coverage:report].[coverage:run].envlists()[envlists].flake8()[flake8].Compile the list of mypy commands.
Compile the list of mypy dependencies.
Compile the list of source files.
Returns information about the matrix of third party versions.
merge_existing(ini_file)Merge existing sections in the configuration file into the new configuration.
pytest()[pytest].testenv()[testenv].[testenv:build].[testenv:coverage].[testenv:docs].[testenv:lint].[testenv:mypy].[testenv:pyup].tox()[tox].-
get_third_party_version_matrix()[source]¶ Returns information about the matrix of third party versions.
The returned object is a three-element tuple, comprising:
The name of the third party library.
A list of version strings.
The testenv suffix, e.g.
-attrs{19.3,20.1}.
- Return type
Tuple[str,DelimitedList,str]
-
ensure_tests_requirements(repo_path, templates)[source]¶ Ensure
tests/requirements.txtcontains the required entries.
Overview¶
repo_helper uses tox to automate testing and packaging,
and pre-commit to maintain code quality.
Install pre-commit with pip and install the git hook:
python -m pip install pre-commit
pre-commit install
Coding style¶
formate is used for code formatting.
It can be run manually via pre-commit:
pre-commit run formate -a
Or, to run the complete autoformatting suite:
pre-commit run -a
Automated tests¶
Tests are run with tox and pytest.
To run tests for a specific Python version, such as Python 3.6:
tox -e py36
To run tests for all Python versions, simply run:
tox
Build documentation locally¶
The documentation is powered by Sphinx. A local copy of the documentation can be built with tox:
tox -e docs
Downloading source code¶
The repo_helper source code is available on GitHub,
and can be accessed from the following URL: https://github.com/repo-helper/repo_helper
If you have git installed, you can clone the repository with the following command:
git clone https://github.com/repo-helper/repo_helper
Cloning into 'repo_helper'...
remote: Enumerating objects: 47, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (41/41), done.
remote: Total 173 (delta 16), reused 17 (delta 6), pack-reused 126
Receiving objects: 100% (173/173), 126.56 KiB | 678.00 KiB/s, done.
Resolving deltas: 100% (66/66), done.
Downloading a ‘zip’ file of the source code¶
Building from source¶
The recommended way to build repo_helper is to use tox:
tox -e build
The source and wheel distributions will be in the directory dist.
If you wish, you may also use pep517.build or another PEP 517-compatible build tool.
License¶
repo_helper is licensed under the GNU Lesser General Public License v3.0
Permissions of this copyleft license are conditioned on making available complete source code of licensed works and modifications under the same license or the GNU GPLv3. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. However, a larger work using the licensed work through interfaces provided by the licensed work may be distributed under different terms and without source code for the larger work.
| Permissions | Conditions | Limitations |
|---|---|---|
|
|
GNU LESSER GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
This version of the GNU Lesser General Public License incorporates
the terms and conditions of version 3 of the GNU General Public
License, supplemented by the additional permissions listed below.
0. Additional Definitions.
As used herein, "this License" refers to version 3 of the GNU Lesser
General Public License, and the "GNU GPL" refers to version 3 of the GNU
General Public License.
"The Library" refers to a covered work governed by this License,
other than an Application or a Combined Work as defined below.
An "Application" is any work that makes use of an interface provided
by the Library, but which is not otherwise based on the Library.
Defining a subclass of a class defined by the Library is deemed a mode
of using an interface provided by the Library.
A "Combined Work" is a work produced by combining or linking an
Application with the Library. The particular version of the Library
with which the Combined Work was made is also called the "Linked
Version".
The "Minimal Corresponding Source" for a Combined Work means the
Corresponding Source for the Combined Work, excluding any source code
for portions of the Combined Work that, considered in isolation, are
based on the Application, and not on the Linked Version.
The "Corresponding Application Code" for a Combined Work means the
object code and/or source code for the Application, including any data
and utility programs needed for reproducing the Combined Work from the
Application, but excluding the System Libraries of the Combined Work.
1. Exception to Section 3 of the GNU GPL.
You may convey a covered work under sections 3 and 4 of this License
without being bound by section 3 of the GNU GPL.
2. Conveying Modified Versions.
If you modify a copy of the Library, and, in your modifications, a
facility refers to a function or data to be supplied by an Application
that uses the facility (other than as an argument passed when the
facility is invoked), then you may convey a copy of the modified
version:
a) under this License, provided that you make a good faith effort to
ensure that, in the event an Application does not supply the
function or data, the facility still operates, and performs
whatever part of its purpose remains meaningful, or
b) under the GNU GPL, with none of the additional permissions of
this License applicable to that copy.
3. Object Code Incorporating Material from Library Header Files.
The object code form of an Application may incorporate material from
a header file that is part of the Library. You may convey such object
code under terms of your choice, provided that, if the incorporated
material is not limited to numerical parameters, data structure
layouts and accessors, or small macros, inline functions and templates
(ten or fewer lines in length), you do both of the following:
a) Give prominent notice with each copy of the object code that the
Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the object code with a copy of the GNU GPL and this license
document.
4. Combined Works.
You may convey a Combined Work under terms of your choice that,
taken together, effectively do not restrict modification of the
portions of the Library contained in the Combined Work and reverse
engineering for debugging such modifications, if you also do each of
the following:
a) Give prominent notice with each copy of the Combined Work that
the Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the Combined Work with a copy of the GNU GPL and this license
document.
c) For a Combined Work that displays copyright notices during
execution, include the copyright notice for the Library among
these notices, as well as a reference directing the user to the
copies of the GNU GPL and this license document.
d) Do one of the following:
0) Convey the Minimal Corresponding Source under the terms of this
License, and the Corresponding Application Code in a form
suitable for, and under terms that permit, the user to
recombine or relink the Application with a modified version of
the Linked Version to produce a modified Combined Work, in the
manner specified by section 6 of the GNU GPL for conveying
Corresponding Source.
1) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (a) uses at run time
a copy of the Library already present on the user's computer
system, and (b) will operate properly with a modified version
of the Library that is interface-compatible with the Linked
Version.
e) Provide Installation Information, but only if you would otherwise
be required to provide such information under section 6 of the
GNU GPL, and only to the extent that such information is
necessary to install and execute a modified version of the
Combined Work produced by recombining or relinking the
Application with a modified version of the Linked Version. (If
you use option 4d0, the Installation Information must accompany
the Minimal Corresponding Source and Corresponding Application
Code. If you use option 4d1, you must provide the Installation
Information in the manner specified by section 6 of the GNU GPL
for conveying Corresponding Source.)
5. Combined Libraries.
You may place library facilities that are a work based on the
Library side by side in a single library together with other library
facilities that are not Applications and are not covered by this
License, and convey such a combined library under terms of your
choice, if you do both of the following:
a) Accompany the combined library with a copy of the same work based
on the Library, uncombined with any other library facilities,
conveyed under the terms of this License.
b) Give prominent notice with the combined library that part of it
is a work based on the Library, and explaining where to find the
accompanying uncombined form of the same work.
6. Revised Versions of the GNU Lesser General Public License.
The Free Software Foundation may publish revised and/or new versions
of the GNU Lesser General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the
Library as you received it specifies that a certain numbered version
of the GNU Lesser General Public License "or any later version"
applies to it, you have the option of following the terms and
conditions either of that published version or of any later version
published by the Free Software Foundation. If the Library as you
received it does not specify a version number of the GNU Lesser
General Public License, you may choose any version of the GNU Lesser
General Public License ever published by the Free Software Foundation.
If the Library as you received it specifies that a proxy can decide
whether future versions of the GNU Lesser General Public License shall
apply, that proxy's public statement of acceptance of any version is
permanent authorization for you to choose that version for the
Library.
View the Function Index or browse the Source Code.