# pbr package

## Subpackages

- pbr.cmd package
  - Submodules
  - pbr.cmd.main module
    - `freeze()`
    - `get_info()`
    - `get_sha()`
    - `main()`
  - Module contents
- pbr.hooks package
  - Submodules
  - pbr.hooks.backwards module
    - `BackwardsCompatConfig`
      - `BackwardsCompatConfig.hook()`
      - `BackwardsCompatConfig.section`
  - pbr.hooks.base module
    - `BaseConfig`
      - `BaseConfig.hook()`
      - `BaseConfig.run()`
      - `BaseConfig.save()`
      - `BaseConfig.section`
  - pbr.hooks.files module
    - `FilesConfig`
      - `FilesConfig.add_man_page()`
      - `FilesConfig.add_man_path()`
      - `FilesConfig.expand_globs()`
      - `FilesConfig.get_man_sections()`
      - `FilesConfig.hook()`
      - `FilesConfig.save()`
      - `FilesConfig.section`
    - `get_man_section()`
    - `get_manpath()`
    - `unquote_path()`
  - pbr.hooks.metadata module
    - `MetadataConfig`
      - `MetadataConfig.get_name()`
      - `MetadataConfig.hook()`
      - `MetadataConfig.section`
  - Module contents
    - `setup_hook()`

## 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.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=None)

  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

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

  Append a separated list to possibly existing value.

pbr.packaging.egg_fragment(match)

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.parse_dependency_links(requirements_files=None)

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

## pbr.pbr_json module

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

## pbr.setupcfg module

pbr.setupcfg.get_entry_points(config)

  Process the [entry_points] section of setup.cfg.

pbr.setupcfg.get_extension_modules(config)

  Handle extension modules

pbr.setupcfg.has_get_option(config, section, option)

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

  Implements the 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.setupcfg.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.setupcfg.setup_cfg_to_args(path='setup.cfg', script_args=None)

  Parse setup.cfg file.

  Parse a setup.cfg file and tranform pbr-specific options to the underlying setuptools opts.

  Parameters:

    - path – The setup.cfg path.

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

  Returns:

    A dictionary of kwargs to set on the underlying Distribution object.

  Raises:

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

pbr.setupcfg.setup_cfg_to_setup_kwargs(config, script_args=None)

  Convert config options to kwargs.

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

pbr.setupcfg.shlex_split(path)

pbr.setupcfg.split_csv(value)

  Special behaviour when we have a comma separated options

pbr.setupcfg.split_multiline(value)

  Special behaviour when we have a multi line options

## pbr.sphinxext module

pbr.sphinxext.setup(app)

## 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

this page last updated: 2026-02-08 22:52:26

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug