pbr package

Submodules

pbr.builddoc module

class pbr.builddoc.LocalBuildDoc(dist)

Bases: sphinx.setup_command.BuildDoc

builders = [‘html’]
command_name = ‘build_sphinx’
finalize_options()
generate_autoindex(excluded_modules=None)
initialize_options()
run()
sphinx_initialized = False

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=u’.’, 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, **kw)

Bases: setuptools.command.install.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 = u’install’
run()
class pbr.packaging.LocalDebVersion(dist, **kw)

Bases: setuptools.Command

Output the deb compatible version string of this package

command_name = u’deb_version’
description = u’Output the deb *compatible* version string of this package’
finalize_options()
initialize_options()
run()
user_options = []
class pbr.packaging.LocalDevelop(dist, **kw)

Bases: setuptools.command.develop.develop

command_name = u’develop’
install_wrapper_scripts(dist)
class pbr.packaging.LocalEggInfo(dist, **kw)

Bases: setuptools.command.egg_info.egg_info

Override the egg_info command to regenerate SOURCES.txt sensibly.

command_name = u’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, **kw)

Bases: setuptools.command.install.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 = u’install’
run()
class pbr.packaging.LocalInstallScripts(dist, **kw)

Bases: setuptools.command.install_scripts.install_scripts

Intercepts console scripts entry_points.

command_name = u’install_scripts’
run()
class pbr.packaging.LocalManifestMaker(dist, **kw)

Bases: setuptools.command.egg_info.manifest_maker

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

add_defaults()
class pbr.packaging.LocalRPMVersion(dist, **kw)

Bases: setuptools.Command

Output the rpm compatible version string of this package

command_name = u’rpm_version’
description = u’Output the rpm *compatible* version string of this package’
finalize_options()
initialize_options()
run()
user_options = []
class pbr.packaging.LocalSDist(dist, **kw)

Bases: setuptools.command.sdist.sdist

Builds the ChangeLog and Authors files from VC first.

command_name = u’sdist’
run()
class pbr.packaging.TestrTest(dist)

Bases: pbr.testr_command.TestrReal

Make setup.py test do the right thing.

command_name = u’test’
run()
pbr.packaging.append_text_list(config, key, text_list)

Append a separated list to possibly existing value.

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/jenkins/workspace/pbr-docs-ubuntu-xenial/.tox/venv/bin/python’, is_wininst=False)

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.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 TestrReal

class pbr.testr_command.TestrFake(dist)

Bases: distutils.cmd.Command

description = ‘Run unit tests using testr’
finalize_options()
initialize_options()
run()
user_options = []
class pbr.testr_command.TestrReal(dist)

Bases: distutils.cmd.Command

boolean_options = [‘coverage’, ‘slowest’, ‘no_parallel’]
description = ‘Run unit tests using testr’
finalize_options()
initialize_options()
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: collections.defaultdict

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

get(key, default=None)
class pbr.util.IgnoreDict(ignore)

Bases: dict

A dictionary that ignores any insertions in which the key is a string matching any string in ignore. The ignore list can also contain wildcard patterns using ‘*’.

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 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.monkeypatch_method(cls)

A function decorator to monkey-patch a method of the same name on the given class.

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.run_command_hooks(cmd_obj, hook_kind)

Run hooks registered for that command and phase.

cmd_obj is a finalized command object; hook_kind is either ‘pre_hook’ or ‘post_hook’.

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

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

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.util.wrap_command(cmd, cmdclass, hooks)
pbr.util.wrap_commands(kwargs)

pbr.version module

Utilities for consuming the version from pkg_resources.

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(klass, 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