Python Build Reasonableness (PBR)

7.0.3 · active · verified Sun Mar 29

PBR (Python Build Reasonableness) is a library developed by OpenStack that injects useful and sensible default behaviors into setuptools-based Python projects. It automates common packaging tasks such as version management based on Git tags, generation of AUTHORS and ChangeLog files from Git history, handling dependencies via requirements files, and automatic long descriptions from READMEs. It aims to simplify the `setup.py` and `setup.cfg` configuration for consistent and repeatable builds. The current version is 7.0.3, with an active release cadence tied to OpenStack development cycles.

Warnings

breaking PBR 7.0.0 introduced significant breaking changes, deprecating or removing many options from `setup.cfg` sections like `[backwards_compat]`, `[metadata]`, `[files]`, and `[entry_points]`. The `tests_require` option was also deprecated.
Fix: Review the official PBR 7.0.0 release notes and documentation for updated configuration options. Migrate deprecated `setup.cfg` options to their new locations or equivalent `pyproject.toml` configurations. For example, `[files]` and `[entry_points]` sections should be moved to `[options]` or `[tools.setuptools]` in `setup.cfg` or `pyproject.toml` respectively.
deprecated PBR has deprecated support for `pyN`-suffixed requirement files in favor of environment markers. Additionally, `testr` and `nose` integration for `setup.py test` has been deprecated.
Fix: Update requirement files to use PEP 508 environment markers. For testing, use `testr` or `nose` directly with their native setuptools commands instead of relying on PBR's integration.
gotcha PBR heavily relies on Git for versioning, AUTHORS, and ChangeLog generation. If your project is not a Git repository, or if Git is not installed/accessible, these features will not work as expected and may result in default versions (e.g., '0.0.1') or build failures.
Fix: Ensure your project is a Git repository and that Git is installed and accessible in the build environment. For production releases, it's recommended to create a Git tag to explicitly define the version.
gotcha Older versions of PBR (e.g., 0.11.0, 1.10.0) had known issues causing `ImportError: No module named pbr.pbr_json` or `ModuleNotFoundError: No module named 'testrepository'` during `pip install` of packages that depend on them. This often occurred when `pbr` was not installed or was an outdated version before its dependencies.
Fix: Ensure `pbr` is explicitly listed as a `setup_requires` dependency in `setup.py` (e.g., `setup_requires=['pbr>=2.0.0']`) and/or update `pyproject.toml` to specify a sufficiently recent version (`pbr>=7.0.0`). Uninstalling and reinstalling `pbr` or clearing problematic `site-packages` entries might also be necessary.
deprecated PBR 7.0.2 removed remaining uses of `pkg_resources` internally, moving towards `importlib.metadata` and `packaging` for better Python 3 compatibility and modern practices.
Fix: While this is an internal change, it's a good practice for downstream projects to also avoid direct `pkg_resources` usage where possible, especially in `setup.py` scripts that PBR interacts with.

Install

pip install pbr Install PBR

Imports

setup
```
from setuptools import setup
```
PBR is primarily configured via setup.cfg and pyproject.toml, with a minimal setup.py calling setuptools.setup().
VersionInfo
```
import pbr.version; version = pbr.version.VersionInfo('my_package').version_string()
```
The version information is typically accessed via the pbr.version module's VersionInfo class, not a direct import of 'version' from 'pbr'.

Quickstart

To use PBR, you need a minimal `setup.py` file that calls `setuptools.setup()` and sets `pbr=True`. Most of your project metadata and configuration (e.g., name, dependencies, entry points, versioning strategy) will reside in `setup.cfg` and, for modern Python packaging, in `pyproject.toml`. PBR then processes these configuration files to provide default behaviors and inject values into `setuptools`.

import setuptools

# setup.py
setuptools.setup(
    setup_requires=['pbr>=2.0.0'],
    pbr=True,
)

# --- setup.cfg ---
# [metadata]
# name = my-package
# author = Your Name
# author-email = your@email.com
# summary = A short summary of my package
# description-file = README.rst
# license = MIT
# classifier =
#     Development Status :: 4 - Beta
#     Programming Language :: Python
# keywords = example, packaging
# 
# [files]
# packages = my_package
# 
# [entry_points]
# console_scripts =
#     my-command = my_package.cli:main
# 
# --- pyproject.toml (for modern projects) ---
# [build-system]
# requires = ["pbr>=7.0.0", "setuptools>=61.0.0", "wheel"]
# build-backend = "pbr.build"

view raw JSON →