Debian Codegraph @

doc/source/user/features.rst

raw
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`.