`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

repo (Union[str, Path, PathLike, Repo]) – The repository.
files (Iterable[Union[str, Path, PathLike]]) – List of files to stage.

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, 5, 26)¶

Type: date

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

repo_helper.utils¶

`repo_helper.utils`¶