repo_helper.utils

General utilities.

Classes:

IniConfigurator(base_path)

Base class to generate .ini configuration files.

Functions:

commit_changes(repo[, message])

Commit staged changes.

discover_entry_points(group_name[, match_func])

Returns a list of entry points in the given category, optionally filtered by match_func.

get_license_text(license_name, …)

Obtain the license text for the given license.

indent_join(iterable)

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, predicate])

Adds '\t' to the beginning of selected lines in ‘text’.

no_dev_versions(versions)

Returns the subset of versions which does not end with -dev.

normalize(name)

Normalize the given name for PyPI et al.

pformat_tabs(obj[, width, depth, compact])

Format a Python object into a pretty-printed representation.

reformat_file(filename, yapf_style, …)

Reformat the given file.

resource(package, resource)

Retrieve the path to a resource inside a package.

set_gh_actions_versions(py_versions)

Convert development Python versions into the appropriate versions for GitHub Actions.

sort_paths(*paths)

Sort the paths by directory, then by file.

stage_changes(repo, files)

Stage any files that have been updated, added or removed.

Data:

license_lookup

Mapping of license short codes to license names used in trove classifiers.

today

Under normal circumstances returns datetime.date.today().
class IniConfigurator(base_path)[source]

Bases: object

Base class to generate .ini configuration 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()

Write out to the .ini file.
copy_existing_value(section, key)[source]

Copy the existing value for key, if present, to the new configuration.

Parameters

  • section (Section)

  • key (str)

merge_existing(ini_file)[source]

Merge existing sections in the configuration file into the new configuration.

Parameters

ini_file (Path) – The existing .ini file.

write_out()[source]

Write out to the .ini file.

commit_changes(repo, message="Updated files with 'repo_helper'.")[source]

Commit staged changes.

Parameters

  • repo (Union[str, Path, PathLike, Repo]) – The repository to commit in.

  • message (str) – The commit message to use. Default "Updated files with 'repo_helper'.".

Return type

str

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

  • group_name (str) – The entry point group name, e.g. 'entry_points'.

  • match_func (Optional[Callable[[Any], bool]]) – Function taking an object and returning True if the object is to be included in the output. Default None, which includes all objects.

Return type

List[Any]

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.

Return type

str

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.

Parameters

iterable (Iterable[str])

Return type

str

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. Default 1.

  • predicate (Optional[Callable[[str], bool]]) – If given, '\t' will only be added to the lines where predicate(line) is :py:obj`True`. If predicate is not provided, it will default to adding '\t' to all non-empty lines that do not consist solely of whitespace characters. Default None.

Return type

str

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:    dict

Mapping of license short codes to license names used in trove classifiers.

no_dev_versions(versions)[source]

Returns the subset of versions which does not end with -dev.

Parameters

versions (Iterable[str])

Return type

List[str]

normalize(name)[source]

Normalize the given name for PyPI et al.

From PEP 503 (public domain).

Parameters

name (str) – The project name.

Return type

str

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.

Parameters

  • obj (object) – The object to format.

  • width (int) – The maximum width of the output. Default 80.

  • depth (Optional[int]) – Default None.

  • compact (bool) – Default False.

Return type

str

reformat_file(filename, yapf_style, isort_config_file)[source]

Reformat the given file.

Parameters

  • filename (Union[str, Path, PathLike])

  • yapf_style (str) – The name of the yapf style, or the path to the yapf style file.

  • isort_config_file (str) – The filename of the isort configuration file.

Return type

int

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.

Parameters

py_versions (Iterable[str])

Return type

List[str]

sort_paths(*paths)[source]

Sort the paths by directory, then by file.

New in version 2.6.0.

Parameters

paths

Return type

List[PathPlus]

stage_changes(repo, files)[source]

Stage any files that have been updated, added or removed.

Parameters
Return type

List[PathPlus]

Returns

A list of staged files. Not all files in files will have been changed, and only changes are staged.

New in version 2020.11.23.

today = datetime.date(2023, 11, 20)

Type:    date

Under normal circumstances returns datetime.date.today().