| 1 |
========== |
| 2 |
Features |
| 3 |
========== |
| 4 |
|
| 5 |
To understand what *pbr* can do for you, it's probably best to look at two |
| 6 |
projects: one using pure *setuptools*, and another using *pbr*. First, let's |
| 7 |
look at the *setuptools* project. |
| 8 |
|
| 9 |
.. code-block:: none |
| 10 |
|
| 11 |
$ tree -L 1 |
| 12 |
. |
| 13 |
├── AUTHORS |
| 14 |
├── CHANGES |
| 15 |
├── LICENSE |
| 16 |
├── MANIFEST.in |
| 17 |
├── README.rst |
| 18 |
├── requirements.txt |
| 19 |
├── setup.cfg |
| 20 |
├── setup.py |
| 21 |
└── somepackage |
| 22 |
|
| 23 |
$ cat setup.py |
| 24 |
setuptools.setup( |
| 25 |
name='mypackage', |
| 26 |
version='1.0.0', |
| 27 |
description='A short description', |
| 28 |
long_description="""A much longer description...""", |
| 29 |
author="John Doe", |
| 30 |
author_email='[email protected]', |
| 31 |
license='BSD', |
| 32 |
) |
| 33 |
|
| 34 |
Here's a similar package using *pbr*: |
| 35 |
|
| 36 |
.. code-block:: none |
| 37 |
|
| 38 |
$ tree -L 1 |
| 39 |
. |
| 40 |
├── LICENSE |
| 41 |
├── README.rst |
| 42 |
├── setup.cfg |
| 43 |
├── setup.py |
| 44 |
└── somepackage |
| 45 |
|
| 46 |
$ cat setup.py |
| 47 |
setuptools.setup( |
| 48 |
pbr=True |
| 49 |
) |
| 50 |
|
| 51 |
$ cat setup.cfg |
| 52 |
[metadata] |
| 53 |
name = mypackage |
| 54 |
description = A short description |
| 55 |
description_file = README.rst |
| 56 |
author = John Doe |
| 57 |
author_email = [email protected] |
| 58 |
license = BSD |
| 59 |
|
| 60 |
From this, we note a couple of the main features of *pbr*: |
| 61 |
|
| 62 |
- Extensive use of ``setup.cfg`` for configuration |
| 63 |
- Automatic package metadata generation (``version``) |
| 64 |
- Automatic metadata file generation (``AUTHOR``, ``ChangeLog``, |
| 65 |
``MANIFEST.in``, ``RELEASENOTES.txt``) |
| 66 |
|
| 67 |
In addition, there are other things that you don't see here but which *pbr* |
| 68 |
will do for you: |
| 69 |
|
| 70 |
- Helpful extensions to *setuptools* commands |
| 71 |
|
| 72 |
setup.cfg |
| 73 |
--------- |
| 74 |
|
| 75 |
.. admonition:: Summary |
| 76 |
|
| 77 |
*pbr* uses ``setup.cfg`` for all configuration, though ``setup.py`` is |
| 78 |
still required. |
| 79 |
|
| 80 |
One of the main features of *distutils2* was the use of a ``setup.cfg`` |
| 81 |
INI-style configuration file. This was used to define a package's metadata and |
| 82 |
other options that were normally supplied to the ``setup()`` function. |
| 83 |
|
| 84 |
Recent versions of `setuptools`__ have implemented some of this support, but |
| 85 |
*pbr* still allows for the definition of the following sections in |
| 86 |
``setup.cfg``: |
| 87 |
|
| 88 |
- ``files`` |
| 89 |
- ``entry_points`` |
| 90 |
- ``backwards_compat`` |
| 91 |
|
| 92 |
For more information on these sections, refer to :doc:`/user/using`. |
| 93 |
|
| 94 |
__ https://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files |
| 95 |
|
| 96 |
Package Metadata |
| 97 |
---------------- |
| 98 |
|
| 99 |
.. admonition:: Summary |
| 100 |
|
| 101 |
*pbr* removes the need to define a lot of configuration in either |
| 102 |
``setup.py`` or ``setup.cfg`` by extracting this information from Git. |
| 103 |
|
| 104 |
Version |
| 105 |
~~~~~~~ |
| 106 |
|
| 107 |
.. admonition:: Summary |
| 108 |
|
| 109 |
*pbr* will automatically configure your version for you by parsing |
| 110 |
semantically-versioned Git tags. |
| 111 |
|
| 112 |
Versions can be managed two ways - *post-versioning* and *pre-versioning*. |
| 113 |
*Post-versioning* is the default while *pre-versioning* is enabled by setting |
| 114 |
``version`` in the ``setup.cfg`` ``metadata`` section. In both cases the actual |
| 115 |
version strings are inferred from Git. |
| 116 |
|
| 117 |
If the currently checked out revision is tagged, that tag is used as |
| 118 |
the version. |
| 119 |
|
| 120 |
If the currently checked out revision is not tagged, then we take the |
| 121 |
last tagged version number and increment it to get a minimum target |
| 122 |
version. |
| 123 |
|
| 124 |
.. note:: |
| 125 |
|
| 126 |
*pbr* supports both bare version tag (e.g. ``0.1.0``) and version prefixed |
| 127 |
with ``v`` or ``V`` (e.g. ``v0.1.0``) |
| 128 |
|
| 129 |
We then walk Git history back to the last release. Within each commit we look |
| 130 |
for a ``Sem-Ver:`` pseudo header and, if found, parse it looking for keywords. |
| 131 |
Unknown symbols are not an error (so that folk can't wedge *pbr* or break their |
| 132 |
tree), but we will emit an info-level warning message. The following symbols |
| 133 |
are recognized: |
| 134 |
|
| 135 |
- ``feature`` |
| 136 |
- ``api-break`` |
| 137 |
- ``deprecation`` |
| 138 |
- ``bugfix`` |
| 139 |
|
| 140 |
A missing ``Sem-Ver`` line is equivalent to ``Sem-Ver: bugfix``. The ``bugfix`` |
| 141 |
symbol causes a patch level increment to the version. The ``feature`` and |
| 142 |
``deprecation`` symbols cause a minor version increment. The ``api-break`` |
| 143 |
symbol causes a major version increment. |
| 144 |
|
| 145 |
If *post-versioning* is in use, we use the resulting version number as the target |
| 146 |
version. |
| 147 |
|
| 148 |
If *pre-versioning* is in use, we check that the version set in the metadata |
| 149 |
section of ``setup.cfg`` is greater than the version we infer using the above |
| 150 |
method. If the inferred version is greater than the *pre-versioning* value we |
| 151 |
raise an error, otherwise we use the version from ``setup.cfg`` as the target. |
| 152 |
|
| 153 |
We then generate dev version strings based on the commits since the last |
| 154 |
release and include the current Git SHA to disambiguate multiple dev versions |
| 155 |
with the same number of commits since the release. |
| 156 |
|
| 157 |
.. note:: |
| 158 |
|
| 159 |
*pbr* expects Git tags to be signed for use in calculating versions. |
| 160 |
|
| 161 |
The versions are expected to be compliant with :doc:`semver`. |
| 162 |
|
| 163 |
The ``version.SemanticVersion`` class can be used to query versions of a |
| 164 |
package and present it in various forms - ``debian_version()``, |
| 165 |
``release_string()``, ``rpm_string()``, ``version_string()``, or |
| 166 |
``version_tuple()``. |
| 167 |
|
| 168 |
Long Description |
| 169 |
~~~~~~~~~~~~~~~~ |
| 170 |
|
| 171 |
.. admonition:: Summary |
| 172 |
|
| 173 |
*pbr* can extract the contents of a ``README`` and use this as your long |
| 174 |
description |
| 175 |
|
| 176 |
There is no need to maintain two long descriptions and your ``README`` file is |
| 177 |
probably a good long_description. So we'll just inject the contents of your |
| 178 |
``README.rst``, ``README.txt`` or ``README`` file into your empty |
| 179 |
``long_description``. |
| 180 |
|
| 181 |
You can also specify the exact file you want to use using the |
| 182 |
``description_file`` parameter. |
| 183 |
|
| 184 |
You can set the ``description_content_type`` to a MIME type that may |
| 185 |
help rendering of the description; for example ``text/markdown`` or |
| 186 |
``text/x-rst; charset=UTF-8``. |
| 187 |
|
| 188 |
Requirements |
| 189 |
~~~~~~~~~~~~ |
| 190 |
|
| 191 |
.. admonition:: Summary |
| 192 |
|
| 193 |
*pbr* will extract requirements from ``requirements.txt`` files and |
| 194 |
automatically populate the ``install_requires`` argument to ``setup`` with |
| 195 |
them. |
| 196 |
|
| 197 |
You may not have noticed, but there are differences in how pip |
| 198 |
``requirements.txt`` files work and how *setuptools* wants to be told about |
| 199 |
requirements. The *pip* way is nicer because it sure does make it easier to |
| 200 |
populate a *virtualenv* for testing or to just install everything you need. |
| 201 |
Duplicating the information, though, is super lame. To solve this issue, *pbr* |
| 202 |
will let you use ``requirements.txt``-format files to describe the requirements |
| 203 |
for your project and will then parse these files, split them up appropriately, |
| 204 |
and inject them into the ``install_requires`` argument to ``setup``. Voila! |
| 205 |
|
| 206 |
Finally, it is possible to specify groups of optional dependencies, or |
| 207 |
:ref:`"extra" requirements <extra-requirements>`, in your ``setup.cfg`` rather |
| 208 |
than ``setup.py``. |
| 209 |
|
| 210 |
.. versionchanged:: 7.0 |
| 211 |
|
| 212 |
Previously, the ``tests_require`` and ``dependency_links`` setup arguments |
| 213 |
were also populated by *pbr*. The ``tests_require`` argument is no longer |
| 214 |
supported as of `setuptools v72.0.0`__, while the ``dependency_links`` |
| 215 |
argument is deprecated and ignored by `pip 19.0 or later`__. |
| 216 |
|
| 217 |
.. __: https://setuptools.pypa.io/en/stable/history.html#v72-0-0 |
| 218 |
.. __: https://github.com/pypa/pip/pull/6060 |
| 219 |
|
| 220 |
.. versionchanged:: 5.0 |
| 221 |
|
| 222 |
Previously, you could specify requirements for a given major version of |
| 223 |
Python using requirments files with a ``-pyN`` suffix. This was deprecated |
| 224 |
in 4.0 and removed in 5.0 in favour of environment markers. |
| 225 |
|
| 226 |
Automatic File Generation |
| 227 |
------------------------- |
| 228 |
|
| 229 |
.. admonition:: Summary |
| 230 |
|
| 231 |
*pbr* can automatically generate a couple of files, which would normally |
| 232 |
have to be maintained manually, by using Git data. |
| 233 |
|
| 234 |
AUTHORS, ChangeLog |
| 235 |
~~~~~~~~~~~~~~~~~~ |
| 236 |
|
| 237 |
.. admonition:: Summary |
| 238 |
|
| 239 |
*pbr* will automatically generate an ``AUTHORS`` and a ``ChangeLog`` file |
| 240 |
using Git logs. |
| 241 |
|
| 242 |
Why keep an ``AUTHORS`` or a ``ChangeLog`` file when Git already has all of the |
| 243 |
information you need? ``AUTHORS`` generation supports filtering/combining based |
| 244 |
on a standard ``.mailmap`` file. |
| 245 |
|
| 246 |
Manifest |
| 247 |
~~~~~~~~ |
| 248 |
|
| 249 |
.. admonition:: Summary |
| 250 |
|
| 251 |
*pbr* will automatically generate a ``MANIFEST.in`` file based on the files |
| 252 |
Git is tracking. |
| 253 |
|
| 254 |
Just like ``AUTHORS`` and ``ChangeLog``, why keep a list of files you wish to |
| 255 |
include when you can find many of these in Git. ``MANIFEST.in`` generation |
| 256 |
ensures almost all files stored in Git, with the exception of ``.gitignore``, |
| 257 |
``.gitreview`` and ``.pyc`` files, are automatically included in your |
| 258 |
distribution. In addition, the generated ``AUTHORS`` and ``ChangeLog`` files |
| 259 |
are also included. In many cases, this removes the need for an explicit |
| 260 |
``MANIFEST.in`` file, though one can be provided to exclude files that are |
| 261 |
tracked via Git but which should not be included in the final release, such as |
| 262 |
test files. |
| 263 |
|
| 264 |
.. note:: |
| 265 |
|
| 266 |
``MANIFEST.in`` files have no effect on binary distributions such as wheels. |
| 267 |
Refer to the `Python packaging tutorial`__ for more information. |
| 268 |
|
| 269 |
__ https://packaging.python.org/tutorials/distributing-packages/#manifest-in |
| 270 |
|
| 271 |
Release Notes |
| 272 |
~~~~~~~~~~~~~ |
| 273 |
|
| 274 |
.. admonition:: Summary |
| 275 |
|
| 276 |
*pbr* will automatically use *reno* \'s ``build_reno`` setuptools command |
| 277 |
to generate a release notes file, if reno is available and configured. |
| 278 |
|
| 279 |
If using *reno*, you may wish to include a copy of the release notes in your |
| 280 |
packages. *reno* provides a ``build_reno`` `setuptools command`__ and, if reno |
| 281 |
is present and configured, *pbr* will automatically call this to generate a |
| 282 |
release notes file for inclusion in your package. |
| 283 |
|
| 284 |
__ https://docs.openstack.org/reno/latest/user/setuptools.html |
| 285 |
|
| 286 |
Setup Commands |
| 287 |
-------------- |
| 288 |
|
| 289 |
.. _build_sphinx: |
| 290 |
|
| 291 |
``build_sphinx`` |
| 292 |
~~~~~~~~~~~~~~~~ |
| 293 |
|
| 294 |
.. versionremoved:: 6.0 |
| 295 |
|
| 296 |
*Sphinx* deprecated the ``build_sphinx`` distutils commands in *Sphinx* |
| 297 |
v5.0.0 and removed it in *Sphinx* v7.0.0. *pbr* deprecated its override of |
| 298 |
this command in *pbr* v4.2.0 and removed it in *pbr* v6.0.0. |
| 299 |
|
| 300 |
For automated generation of API documentation, consider either the |
| 301 |
`sphinx.ext.apidoc`__ extension, provided in Sphinx since v8.2.0, or the |
| 302 |
`sphinxcontrib-apidoc`__ extension if you are stuck with older versions of |
| 303 |
Sphinx. |
| 304 |
|
| 305 |
For configuration of versioning via package metadata, consider the |
| 306 |
:ref:`pbr.sphinxext` extension. |
| 307 |
|
| 308 |
.. __: https://www.sphinx-doc.org/en/master/usage/extensions/apidoc.html |
| 309 |
.. __: https://pypi.org/project/sphinxcontrib-apidoc/ |
| 310 |
|
| 311 |
``test`` |
| 312 |
~~~~~~~~ |
| 313 |
|
| 314 |
.. versionremoved:: 7.0 |
| 315 |
|
| 316 |
*pbr* previously aliased the ``test`` command to use the testing tool of |
| 317 |
your choice. However, the two test runners it supported - ``testr`` and |
| 318 |
``nose`` - are no longer maintained. The override of this command was |
| 319 |
therefore removed in *pbr* v7.0.0. |
| 320 |
|
| 321 |
If you relied on this command, you should switch to calling the test runner |
| 322 |
directly. |
| 323 |
|
| 324 |
.. _pbr.sphinxext: |
| 325 |
|
| 326 |
Sphinx Extension |
| 327 |
---------------- |
| 328 |
|
| 329 |
.. admonition:: Summary |
| 330 |
|
| 331 |
*pbr* provides a Sphinx extension to allow you to use *pbr* version |
| 332 |
metadata in your Sphinx documentation. |
| 333 |
|
| 334 |
.. versionadded:: 4.2 |
| 335 |
|
| 336 |
*pbr* provides a Sphinx extension which can be used to configure version |
| 337 |
numbers for documentation. The package does not need to be installed for this |
| 338 |
to function. |
| 339 |
|
| 340 |
.. note:: |
| 341 |
|
| 342 |
The ``openstackdocstheme`` Sphinx theme provides similar functionality. |
| 343 |
This should be preferred for official OpenStack projects. Refer to the |
| 344 |
`documentation`__ for more information. |
| 345 |
|
| 346 |
__ https://docs.openstack.org/openstackdocstheme/ |
| 347 |
|
| 348 |
For more information on the extension, refer to :doc:`/user/using`. |