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.
pip install pbrVerified import paths — ran on the pinned version, not inferred.
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`.
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.
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.
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.
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.
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.
Ensure a `setup.cfg` file exists in the project root directory. It should contain at least a `[metadata]` section and a `[pbr]` section with `autodoc_index_modules = True` or `skip_authors = True` and `skip_changelog = True` if not using those features.
Ensure a `setup.cfg` file is present in your project's root directory when `pbr=True` is used in `setup.py`. Even if it's minimal (e.g., an empty file or just a `[metadata]` section), it must exist.
Ensure pbr is installed in the correct environment using `pip install pbr` or `pip3 install pbr`. If using a virtual environment, activate it before installing.
When developing, clone the repository using `git clone` instead of downloading a zip. Ensure Git tags are correctly formatted and preferably signed (`git tag -s v1.0.0`). For distribution, create a source distribution (`python setup.py sdist`) from a Git-enabled directory before packaging.
Upgrade setuptools to the latest version (`pip install --upgrade setuptools`). If the issue persists, ensure all direct and transitive dependencies are compatible and consider running `pip install pbr --upgrade`.