pbr package

Subpackages

Submodules

pbr.build module

PEP-517 / PEP-660 support

Add:

[build-system]
requires = ["pbr>=6.0.0", "setuptools>=64.0.0"]
build-backend = "pbr.build"

to pyproject.toml to use this.

pbr.build.build_editable(wheel_directory, config_settings=None, metadata_directory=None)
pbr.build.build_sdist(sdist_directory, config_settings=None)
pbr.build.build_wheel(wheel_directory, config_settings=None, metadata_directory=None)
pbr.build.get_requires_for_build_editable(config_settings=None)
pbr.build.get_requires_for_build_sdist(config_settings=None)
pbr.build.get_requires_for_build_wheel(config_settings=None)
pbr.build.prepare_metadata_for_build_editable(metadata_directory, config_settings=None)
pbr.build.prepare_metadata_for_build_wheel(metadata_directory, config_settings=None)

pbr.core module

pbr.core.pbr(dist, attr, value)

Implements the actual pbr setup() keyword.

When used, this should be the only keyword in your setup() aside from setup_requires.

If given as a string, the value of pbr is assumed to be the relative path to the setup.cfg file to use. Otherwise, if it evaluates to true, it simply assumes that pbr should be used, and the default ‘setup.cfg’ is used.

This works by reading the setup.cfg file, parsing out the supported metadata and command options, and using them to rebuild the DistributionMetadata object and set the newly added command options.

The reason for doing things this way is that a custom Distribution class will not play nicely with setup_requires; however, this implementation may not work well with distributions that do use a Distribution subclass.

pbr.extra_files module

pbr.extra_files.get_extra_files()
pbr.extra_files.set_extra_files(extra_files)

pbr.find_package module

pbr.find_package.smart_find_packages(package_list)

Run find_packages the way we intend.

pbr.git module

pbr.git.generate_authors(git_dir=None, dest_dir='.', option_dict={})

Create AUTHORS file using git commits.

pbr.git.get_git_short_sha(git_dir=None)

Return the short sha for this repo, if it exists.

pbr.git.get_is_release(git_dir)
pbr.git.write_git_changelog(git_dir=None, dest_dir='.', option_dict=None, changelog=None)

Write a changelog based on the git changelog.

pbr.options module

pbr.options.get_boolean_option(option_dict, option_name, env_name)

pbr.packaging module

Utilities with minimum-depends for use in setup.py

class pbr.packaging.InstallWithGit(dist)

Bases: install

Extracts ChangeLog and AUTHORS from git then installs.

This is useful for e.g. readthedocs where the package is installed and then docs built.

command_name = 'install'
run()

Runs the command.

class pbr.packaging.LocalDebVersion(dist: Distribution, **kw)

Bases: Command

Output the deb compatible version string of this package

command_name = 'deb_version'
description = 'Output the deb *compatible* version string of this package'
finalize_options()

Set final values for all the options that this command supports. This is always called as late as possible, ie. after any option assignments from the command-line or from other commands have been done. Thus, this is the place to code option dependencies: if ‘foo’ depends on ‘bar’, then it is safe to set ‘foo’ from ‘bar’ as long as ‘foo’ still has the same value it was assigned in ‘initialize_options()’.

This method must be implemented by all command classes.

initialize_options()

Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, ‘initialize_options()’ implementations are just a bunch of “self.foo = None” assignments.

This method must be implemented by all command classes.

run()

A command’s raison d’etre: carry out the action it exists to perform, controlled by the options initialized in ‘initialize_options()’, customized by other commands, the setup script, the command-line, and config files, and finalized in ‘finalize_options()’. All terminal output and filesystem interaction should be done by ‘run()’.

This method must be implemented by all command classes.

user_options = []
class pbr.packaging.LocalDevelop(dist: Distribution, **kw)

Bases: develop

command_name = 'develop'
install_wrapper_scripts(dist)
class pbr.packaging.LocalEggInfo(dist: Distribution, **kw)

Bases: egg_info

Override the egg_info command to regenerate SOURCES.txt sensibly.

command_name = 'egg_info'
find_sources()

Generate SOURCES.txt only if there isn’t one already.

If we are in an sdist command, then we always want to update SOURCES.txt. If we are not in an sdist command, then it doesn’t matter one flip, and is actually destructive. However, if we’re in a git context, it’s always the right thing to do to recreate SOURCES.txt

class pbr.packaging.LocalInstall(dist)

Bases: install

Runs python setup.py install in a sensible manner.

Force a non-egg installed in the manner of single-version-externally-managed, which allows us to install manpages and config files.

command_name = 'install'
run()

Runs the command.

class pbr.packaging.LocalInstallScripts(dist: Distribution, **kw)

Bases: install_scripts

Intercepts console scripts entry_points.

command_name = 'install_scripts'
run()

A command’s raison d’etre: carry out the action it exists to perform, controlled by the options initialized in ‘initialize_options()’, customized by other commands, the setup script, the command-line, and config files, and finalized in ‘finalize_options()’. All terminal output and filesystem interaction should be done by ‘run()’.

This method must be implemented by all command classes.

class pbr.packaging.LocalManifestMaker(dist: Distribution, **kw)

Bases: manifest_maker

Add any files that are in git and some standard sensible files.

add_defaults()

Add all the default files to self.filelist:

Extends the functionality provided by distutils to also included additional sane defaults, such as the AUTHORS and ChangeLog files generated by pbr.

Warns if (README or README.txt) or setup.py are missing; everything else is optional.

class pbr.packaging.LocalRPMVersion(dist: Distribution, **kw)

Bases: Command

Output the rpm compatible version string of this package

command_name = 'rpm_version'
description = 'Output the rpm *compatible* version string of this package'
finalize_options()

Set final values for all the options that this command supports. This is always called as late as possible, ie. after any option assignments from the command-line or from other commands have been done. Thus, this is the place to code option dependencies: if ‘foo’ depends on ‘bar’, then it is safe to set ‘foo’ from ‘bar’ as long as ‘foo’ still has the same value it was assigned in ‘initialize_options()’.

This method must be implemented by all command classes.

initialize_options()

Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, ‘initialize_options()’ implementations are just a bunch of “self.foo = None” assignments.

This method must be implemented by all command classes.

run()

A command’s raison d’etre: carry out the action it exists to perform, controlled by the options initialized in ‘initialize_options()’, customized by other commands, the setup script, the command-line, and config files, and finalized in ‘finalize_options()’. All terminal output and filesystem interaction should be done by ‘run()’.

This method must be implemented by all command classes.

user_options = []
class pbr.packaging.LocalSDist(dist: Distribution, **kw)

Bases: sdist

Builds the ChangeLog and Authors files from VC first.

checking_reno()

Ensure reno is installed and configured.

We can’t run reno-based commands if reno isn’t installed/available, and don’t want to if the user isn’t using it.

command_name = 'sdist'
make_distribution()

Workaround for #516

run()

A command’s raison d’etre: carry out the action it exists to perform, controlled by the options initialized in ‘initialize_options()’, customized by other commands, the setup script, the command-line, and config files, and finalized in ‘finalize_options()’. All terminal output and filesystem interaction should be done by ‘run()’.

This method must be implemented by all command classes.

sub_commands = [('build_reno', <function LocalSDist.checking_reno>), ('check', <function sdist.checking_metadata>)]
class pbr.packaging.TestrTest(dist)

Bases: TestrFake

Make setup.py test do the right thing.

command_name = 'test'
description = 'DEPRECATED: Run unit tests using testr'
run()

A command’s raison d’etre: carry out the action it exists to perform, controlled by the options initialized in ‘initialize_options()’, customized by other commands, the setup script, the command-line, and config files, and finalized in ‘finalize_options()’. All terminal output and filesystem interaction should be done by ‘run()’.

This method must be implemented by all command classes.

pbr.packaging.append_text_list(config, key, text_list)

Append a separated list to possibly existing value.

pbr.packaging.egg_fragment(match)
pbr.packaging.generate_script(group, entry_point, header, template)

Generate the script based on the template.

Parameters:

  • group (str) – The entry-point group name, e.g., “console_scripts”.

  • header (str) – The first line of the script, e.g., “!#/usr/bin/env python”.

  • template (str) – The script template.

Returns:

The templated script content

Return type:

str

pbr.packaging.get_reqs_from_files(requirements_files)
pbr.packaging.get_requirements_files()
pbr.packaging.get_version(package_name, pre_version=None)

Get the version of the project.

First, try getting it from PKG-INFO or METADATA, if it exists. If it does, that means we’re in a distribution tarball or that install has happened. Otherwise, if there is no PKG-INFO or METADATA file, pull the version from git.

We do not support setup.py version sanity in git archive tarballs, nor do we support packagers directly sucking our git repo into theirs. We expect that a source tarball be made from our git repo - or that if someone wants to make a source tarball from a fork of our repo with additional tags in it that they understand and desire the results of doing that.

Parameters:

pre_version – The version field from setup.cfg - if set then this version will be the next release.

pbr.packaging.have_nose()
pbr.packaging.have_sphinx()
pbr.packaging.have_testr()
pbr.packaging.override_get_script_args(dist, executable='/home/zuul/src/opendev.org/openstack/pbr/.tox/docs/bin/python')

Override entrypoints console_script.

pbr.packaging.parse_requirements(requirements_files=None, strip_markers=False)

pbr.pbr_json module

pbr.pbr_json.write_pbr_json(cmd, basename, filename)

pbr.sphinxext module

pbr.sphinxext.setup(app)

pbr.testr_command module

setuptools/distutils command to run testr via setup.py

PBR will hook in the Testr class to provide “setup.py test” when .testr.conf is present in the repository (see pbr/hooks/commands.py).

If we are activated but testrepository is not installed, we provide a sensible error.

You can pass –coverage which will also export PYTHON=’coverage run –source <your package>’ and automatically combine the coverage from each testr backend test runner after the run completes.

pbr.testr_command.Testr

alias of TestrFake

class pbr.testr_command.TestrFake(dist)

Bases: Command

description = 'Run unit tests using testr'
finalize_options()

Set final values for all the options that this command supports. This is always called as late as possible, ie. after any option assignments from the command-line or from other commands have been done. Thus, this is the place to code option dependencies: if ‘foo’ depends on ‘bar’, then it is safe to set ‘foo’ from ‘bar’ as long as ‘foo’ still has the same value it was assigned in ‘initialize_options()’.

This method must be implemented by all command classes.

initialize_options()

Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, ‘initialize_options()’ implementations are just a bunch of “self.foo = None” assignments.

This method must be implemented by all command classes.

run()

A command’s raison d’etre: carry out the action it exists to perform, controlled by the options initialized in ‘initialize_options()’, customized by other commands, the setup script, the command-line, and config files, and finalized in ‘finalize_options()’. All terminal output and filesystem interaction should be done by ‘run()’.

This method must be implemented by all command classes.

user_options = []
class pbr.testr_command.TestrReal(dist)

Bases: Command

boolean_options = ['coverage', 'slowest', 'no_parallel']
description = 'DEPRECATED: Run unit tests using testr'
finalize_options()

Set final values for all the options that this command supports. This is always called as late as possible, ie. after any option assignments from the command-line or from other commands have been done. Thus, this is the place to code option dependencies: if ‘foo’ depends on ‘bar’, then it is safe to set ‘foo’ from ‘bar’ as long as ‘foo’ still has the same value it was assigned in ‘initialize_options()’.

This method must be implemented by all command classes.

initialize_options()

Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, ‘initialize_options()’ implementations are just a bunch of “self.foo = None” assignments.

This method must be implemented by all command classes.

run()

Set up testr repo, then run testr.

user_options = [('coverage', None, 'Replace PYTHON with coverage and merge coverage from each testr worker.'), ('testr-args=', 't', "Run 'testr' with these args"), ('omit=', 'o', 'Files to omit from coverage calculations'), ('coverage-package-name=', None, 'Use this name to select packages for coverage (one or more, comma-separated)'), ('slowest', None, 'Show slowest test times after tests complete.'), ('no-parallel', None, 'Run testr serially'), ('log-level=', 'l', 'Log level (default: info)')]

pbr.util module

The code in this module is mostly copy/pasted out of the distutils2 source code, as recommended by Tarek Ziade. As such, it may be subject to some change as distutils2 development continues, and will have to be kept up to date.

I didn’t want to use it directly from distutils2 itself, since I do not want it to be an installation dependency for our packages yet–it is still too unstable (the latest version on PyPI doesn’t even install).

class pbr.util.DefaultGetDict

Bases: defaultdict

Like defaultdict, but get() also sets and returns the default value.

get(key, default=None)

Return the value for key if key is in the dictionary, else default.

pbr.util.cfg_to_args(path='setup.cfg', script_args=())

Distutils2 to distutils1 compatibility util.

This method uses an existing setup.cfg to generate a dictionary of keywords that can be used by distutils.core.setup(kwargs**).

Parameters:

  • path – The setup.cfg path.

  • script_args – List of commands setup.py was called with.

Raises:

DistutilsFileError – When the setup.cfg file is not found.

pbr.util.get_entry_points(config)

Process the [entry_points] section of setup.cfg.

Processes setup.cfg to handle setuptools entry points. This is, of course, not a standard feature of distutils2/packaging, but as there is not currently a standard alternative in packaging, we provide support for them.

pbr.util.get_extension_modules(config)

Handle extension modules

pbr.util.has_get_option(config, section, option)
pbr.util.register_custom_compilers(config)

Handle custom compilers.

This has no real equivalent in distutils, where additional compilers could only be added programmatically, so we have to hack it in somehow.

pbr.util.resolve_name(name)

Resolve a name like module.object to an object and return it.

Raise ImportError if the module or name is not found.

pbr.util.setup_cfg_to_setup_kwargs(config, script_args=())

Convert config options to kwargs.

Processes the setup.cfg options and converts them to arguments accepted by setuptools’ setup() function.

pbr.util.shlex_split(path)
pbr.util.split_csv(value)

Special behaviour when we have a comma separated options

pbr.util.split_multiline(value)

Special behaviour when we have a multi line options

pbr.version module

Utilities for consuming the version from importlib-metadata.

class pbr.version.SemanticVersion(major, minor=0, patch=0, prerelease_type=None, prerelease=None, dev_count=None)

Bases: object

A pure semantic version independent of serialisation.

See the pbr doc ‘semver’ for details on the semantics.

brief_string()

Return the short version minus any alpha/beta tags.

debian_string()

Return the version number to use when building a debian package.

This translates the PEP440/semver precedence rules into Debian version sorting operators.

decrement()

Return a decremented SemanticVersion.

Decrementing versions doesn’t make a lot of sense - this method only exists to support rendering of pre-release versions strings into serialisations (such as rpm) with no sort-before operator.

The 9999 magic version component is from the spec on this - pbr-semver.

Returns:

A new SemanticVersion object.

classmethod from_pip_string(version_string)

Create a SemanticVersion from a pip version string.

This method will parse a version like 1.3.0 into a SemanticVersion.

This method is responsible for accepting any version string that any older version of pbr ever created.

Therefore: versions like 1.3.0a1 versions are handled, parsed into a canonical form and then output - resulting in 1.3.0.0a1. Pre pbr-semver dev versions like 0.10.1.3.g83bef74 will be parsed but output as 0.10.1.dev3.g83bef74.

Raises:

ValueError – Never tagged versions sdisted by old pbr result in just the git hash, e.g. ‘1234567’ which poses a substantial problem since they collide with the semver versions when all the digits are numerals. Such versions will result in a ValueError being thrown if any non-numeric digits are present. They are an exception to the general case of accepting anything we ever output, since they were never intended and would permanently mess up versions on PyPI if ever released - we’re treating that as a critical bug that we ever made them and have stopped doing that.

increment(minor=False, major=False)

Return an incremented SemanticVersion.

The default behaviour is to perform a patch level increment. When incrementing a prerelease version, the patch level is not changed - the prerelease serial is changed (e.g. beta 0 -> beta 1).

Incrementing non-pre-release versions will not introduce pre-release versions - except when doing a patch incremental to a pre-release version the new version will only consist of major/minor/patch.

Parameters:

  • minor – Increment the minor version.

  • major – Increment the major version.

Returns:

A new SemanticVersion object.

release_string()

Return the full version of the package.

This including suffixes indicating VCS status.

rpm_string()

Return the version number to use when building an RPM package.

This translates the PEP440/semver precedence rules into RPM version sorting operators. Because RPM has no sort-before operator (such as the ~ operator in dpkg), we show all prerelease versions as being versions of the release before.

to_dev(dev_count)

Return a development version of this semver.

Parameters:

dev_count – The number of commits since the last release.

version_tuple()

Present the version as a version_info tuple.

For documentation on version_info tuples see the Python documentation for sys.version_info.

Since semver and PEP-440 represent overlapping but not subsets of versions, we have to have some heuristic / mapping rules, and have extended the releaselevel field to have alphadev, betadev and candidatedev values. When they are present the dev count is used to provide the serial. - a/b/rc take precedence. - if there is no pre-release version the dev version is used. - serial is taken from the dev/a/b/c component. - final non-dev versions never get serials.

class pbr.version.VersionInfo(package)

Bases: object

cached_version_string(prefix='')

Return a cached version string.

This will return a cached version string if one is already cached, irrespective of prefix. If none is cached, one will be created with prefix and then cached and returned.

canonical_version_string()

Return the short version minus any alpha/beta tags.

release_string()

Return the full version of the package.

This including suffixes indicating VCS status.

semantic_version()

Return the SemanticVersion object for this version.

version_string()

Return the short version minus any alpha/beta tags.

version_string_with_vcs()

Return the full version of the package.

This including suffixes indicating VCS status.

Module contents