Debian Codegraph @

doc/source/user/using.rst

raw
1 =======
2 Usage
3 =======
4
5 *pbr* is a *setuptools* plugin and so to use it you must use *setuptools* and
6 call ``setuptools.setup()``. While the normal *setuptools* facilities are
7 available, *pbr* makes it possible to express them through static data files.
8
9 .. _setup_py:
10
11 ``setup.py``
12 ------------
13
14 *pbr* only requires a minimal ``setup.py`` file compared to a standard
15 *setuptools* project. This is because most configuration is located in static
16 configuration files. This recommended minimal ``setup.py`` file should look
17 something like this:
18
19 .. code-block:: python
20
21 #!/usr/bin/env python
22
23 from setuptools import setup
24
25 setup(
26 setup_requires=['pbr'],
27 pbr=True,
28 )
29
30 .. note::
31
32 It is necessary to specify ``pbr=True`` to enabled *pbr* functionality.
33
34 .. note::
35
36 While one can pass any arguments supported by setuptools to ``setup()``,
37 any conflicting arguments supplied in ``pyproject.toml`` or ``setup.cfg``
38 will take precedence.
39
40 Once configured, you can place your configuration into either
41 ``pyproject.toml`` or ``setup.cfg``.
42
43 ``pyproject.toml``
44 ------------------
45
46 *If your project only supports Python 3.7 or newer*, PBR can be configured as a
47 PEP517 build-system in ``pyproject.toml``. The main benefits are that you can
48 control the versions of PBR and setuptools that are used avoiding easy_install
49 invocation. Your ``[build-system]`` block in ``pyproject.toml`` will need to
50 look like this:
51
52 .. code-block:: toml
53
54 [build-system]
55 requires = ["pbr>=6.1.1"]
56 build-backend = "pbr.build"
57
58 Eventually PBR may grow its own direct support for PEP517 build hooks, but
59 until then it will continue to need setuptools with a minimal ``setup.py`` and
60 ``setup.cfg`` as follows. First, ``setup.py``:
61
62 .. code-block:: python
63
64 import setuptools
65 setuptools.setup(pbr=True)
66
67 Then ``setup.cfg``:
68
69 .. code-block:: ini
70
71 [metadata]
72 name = my_project
73
74 Almost all other metadata can be placed into ``pyproject.toml``. A simple example:
75
76 .. code-block:: toml
77
78 [project]
79 name = "my_project"
80 description = "A brief one-line descriptive title of my project"
81 authors = [
82 {name = "John Doe", email = "[email protected]"},
83 ]
84 requires-python = ">=3.10"
85 classifiers = [
86 "Development Status :: 5 - Production/Stable",
87 "Environment :: Console",
88 "Intended Audience :: Developers",
89 "Intended Audience :: Information Technology",
90 "License :: OSI Approved :: Apache Software License",
91 "Operating System :: OS Independent",
92 "Programming Language :: Python",
93 "Programming Language :: Python :: 3",
94 "Programming Language :: Python :: 3.10",
95 "Programming Language :: Python :: 3.11",
96 "Programming Language :: Python :: 3.12",
97 "Programming Language :: Python :: 3.13",
98 "Topic :: Utilities",
99 ]
100 keywords = ["commandline", "utility"]
101 readme = "README.rst"
102
103 [project.scripts]
104 my-project = "my_project.cmd:main"
105
106 [project.urls]
107 Homepage = "https://my-project.example.org/"
108 "Bug Tracker" = "https://my-project.example.org/bugs/"
109 Documentation = "https://my-project.example.org/docs/"
110 "Release Notes" = "https://my-project.example.org/releasenotes/"
111 "Source Code" = "https://my-project.example.org/code/"
112
113 [tool.setuptools]
114 packages = ["my_project"]
115
116 .. _setup_cfg:
117
118 ``setup.cfg``
119 -------------
120
121 The ``setup.cfg`` file is an INI-like file that can mostly replace the
122 ``setup.py`` file. It is similar to the ``setup.cfg`` file found in recent
123 versions of `setuptools`__. As with setuptools itself, you need to retain a
124 minimal ``setup.py`` as follows:
125
126 .. code-block:: python
127
128 import setuptools
129 setuptools.setup(pbr=True)
130
131 All other metadata can be placed in your ``setup.cfg``. A simple example:
132
133 .. code-block:: ini
134
135 [metadata]
136 name = my_project
137 description = A brief one-line descriptive title of my project
138 author = John Doe
139 author_email = [email protected]
140 classifiers =
141 Development Status :: 5 - Production/Stable
142 Environment :: Console
143 Intended Audience :: Developers
144 Intended Audience :: Information Technology
145 License :: OSI Approved :: Apache Software License
146 Operating System :: OS Independent
147 Programming Language :: Python
148 Programming Language :: Python :: 3
149 Programming Language :: Python :: 3.10
150 Programming Language :: Python :: 3.11
151 Programming Language :: Python :: 3.12
152 Programming Language :: Python :: 3.13
153 Topic :: Utilities
154 keywords = commandline utility
155 long_description = file: README.rst
156 long_description_content_type = text/x-rst; charset=UTF-8
157 project_urls =
158 Homepage = https://my-project.example.org/
159 Bug Tracker = https://my-project.example.org/bugs/
160 Documentation = https://my-project.example.org/docs/
161 Release Notes = https://my-project.example.org/releasenotes/
162 Source Code = https://my-project.example.org/code/
163
164 [options]
165 python_requires = >=3.10
166 packages =
167 my_project
168
169 [options.entry_points]
170 console_scripts =
171 my-project = my_project.cmd:main
172
173 Recent versions of `setuptools`_ provide many of the same sections as *pbr*.
174 *pbr*'s support for setup.cfg predates that of setuptools'. For this reason
175 *pbr* supports sections and functionality that setuptools never adopted.
176 These sections are:
177
178 - ``files`` (deprecated)
179 - ``entry_points`` (deprecated)
180 - ``backwards_compat`` (deprecated)
181 - ``pbr``
182
183 In addition, there are some modifications to other sections:
184
185 - ``metadata``
186
187 For all other sections, you should refer to either the `setuptools`_
188 documentation or the documentation of the package that provides the section,
189 such as the ``extract_messages`` section provided by Babel__.
190
191 .. note::
192
193 Comments may be used in ``setup.cfg``, however all comments should start
194 with a ``#`` and may be on a single line, or in line, with at least one
195 white space character immediately preceding the ``#``. Semicolons are not a
196 supported comment delimiter. For instance:
197
198 .. code-block:: ini
199
200 [section]
201 # A comment at the start of a dedicated line
202 key =
203 value1 # An in line comment
204 value2
205 # A comment on a dedicated line
206 value3
207
208 .. note::
209
210 On Python 3 ``setup.cfg`` is explicitly read as UTF-8. On Python 2 the
211 encoding is dependent on the terminal encoding.
212
213 __ http://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files
214 __ http://babel.pocoo.org/en/latest/setup.html
215
216 ``files``
217 ~~~~~~~~~
218
219 The ``files`` section defines the install location of files in the package.
220
221 .. deprecated:: 7.0.0
222
223 `setuptools v30.3.0`__ introduced built-in support for configuring the
224 below information via the ``[options]`` section in ``setup.cfg``, while
225 `setuptools v68.1.0`__ adds support for doing this via ``pyproject.toml``
226 using the ``[tool.setuptools]`` section. For example, given the following
227 ``setup.cfg`` configuration:
228
229 .. code-block:: ini
230
231 [files]
232 packages =
233 foo
234 namespace_packages =
235 fooext
236 data_files =
237 etc/foo = etc/foo/*
238 etc/foo-api =
239 etc/api-paste.ini
240 etc/init.d = foo.init
241
242 You can represent this in ``setup.cfg`` like so:
243
244 .. code-block:: ini
245
246 [options]
247 packages =
248 foo
249 namespace_packages =
250 fooext
251
252 [options.data_files]
253 etc/foo = etc/foo/*
254 etc/foo-api =
255 etc/api-paste.ini
256 etc/init.d = foo.init
257
258 Neither namespace packages nor non-package data files are supported in
259 ``pyproject.toml`` format so only ``[files] packages`` can be migrated in
260 this example:
261
262 .. code-block:: toml
263
264 [tool.setuptools]
265 packages = ["foo"]
266
267 For more information, refer to the `Configuring setuptools using setup.cfg
268 files`__, `Package Discovery and Namespace Packages`__ and `Data Files
269 Support`__ documents in the setuptools docs.
270
271 .. __: https://pypi.org/project/setuptools/30.3.0/
272 .. __: https://pypi.org/project/setuptools/68.1.0/
273 .. __: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html
274 .. __: https://setuptools.pypa.io/en/latest/userguide/package_discovery.html
275 .. __: https://setuptools.pypa.io/en/latest/userguide/datafiles.html
276
277 The ``files`` section uses three fundamental keys: ``packages``,
278 ``namespace_packages``, and ``data_files``.
279
280 ``packages``
281 A list of top-level packages that should be installed. The behavior of
282 packages is similar to ``setuptools.find_packages`` in that it recurses the
283 Python package hierarchy below the given top level and installs all of it. If
284 ``packages`` is not specified, it defaults to the value of the ``name`` field
285 given in the ``[metadata]`` section. For example:
286
287 .. code-block:: ini
288
289 [files]
290 packages =
291 pbr
292
293 ``namespace_packages``
294 Similar to ``packages``, but is a list of packages that provide namespace
295 packages. For example:
296
297 .. code-block:: ini
298
299 [files]
300 namespace_packages =
301 pbrext
302
303 ``data_files``
304 A list of files to be installed. The format is an indented block that
305 contains key value pairs which specify target directory and source file to
306 install there. More than one source file for a directory may be indicated
307 with a further indented list. Source files are stripped of leading
308 directories. Additionally, *pbr* supports a simple file globbing syntax for
309 installing entire directory structures. For example:
310
311 .. code-block:: ini
312
313 [files]
314 data_files =
315 etc/pbr = etc/pbr/*
316 etc/neutron =
317 etc/api-paste.ini
318 etc/dhcp-agent.ini
319 etc/init.d = neutron.init
320
321 This will result in ``/etc/neutron`` containing ``api-paste.ini`` and
322 ``dhcp-agent.ini``, both of which *pbr* will expect to find in the ``etc``
323 directory in the root of the source tree. Additionally, ``neutron.init`` from
324 that directory will be installed in ``/etc/init.d``. All of the files and
325 directories located under ``etc/pbr`` in the source tree will be installed
326 into ``/etc/pbr``.
327
328 Note that this behavior is relative to the effective root of the environment
329 into which the packages are installed, so depending on available permissions
330 this could be the actual system-wide ``/etc`` directory or just a top-level
331 ``etc`` subdirectory of a *virtualenv*.
332
333 ``entry_points``
334 ~~~~~~~~~~~~~~~~
335
336 The ``entry_points`` section defines entry points for generated console scripts
337 and Python libraries.
338
339 .. deprecated:: 7.0.0
340
341 `setuptools v30.3.0`__ introduced built-in support for configuring the
342 below information via the ``[options.entry_points]`` section in
343 ``setup.cfg``, while `setuptools v68.1.0`__ adds support for doing this via
344 ``pyproject.toml`` using the ``[project.scripts]`` section. For example,
345 given the following ``setup.cfg`` configuration:
346
347 .. code-block:: ini
348
349 [entry_points]
350 console_scripts =
351 pbr = pbr.cmd:main
352 pbr.config.drivers =
353 plain = pbr.cfg.driver:Plain
354 fancy = pbr.cfg.driver:Fancy
355
356 You can represent this in ``setup.cfg`` like so:
357
358 .. code-block:: ini
359
360 [options.entry_points]
361 console_scripts =
362 pbr = pbr.cmd:main
363 pbr.config.drivers =
364 plain = pbr.cfg.driver:Plain
365 fancy = pbr.cfg.driver:Fancy
366
367 Or in ``pyproject.toml`` like so:
368
369 .. code-block:: toml
370
371 [project.scripts]
372 pbr = "pbr.cmd:main"
373
374 [project.entry-points."pbr.config.drivers"]
375 plain = "pbr.cfg.driver:Plain"
376 fancy = "pbr.cfg.driver:Fancy"
377
378 For more information, refer to the `Entry Points`__ document in the
379 setuptools docs.
380
381 .. __: https://pypi.org/project/setuptools/30.3.0/
382 .. __: https://pypi.org/project/setuptools/68.1.0/
383 .. __: https://setuptools.pypa.io/en/latest/userguide/entry_point.html
384
385 The general syntax of specifying entry points is a top level name indicating
386 the entry point group name, followed by one or more key value pairs naming the
387 entry point to be installed. For example:
388
389 .. code-block:: ini
390
391 [entry_points]
392 console_scripts =
393 pbr = pbr.cmd:main
394 pbr.config.drivers =
395 plain = pbr.cfg.driver:Plain
396 fancy = pbr.cfg.driver:Fancy
397
398 Will cause a console script called *pbr* to be installed that executes the
399 ``main`` function found in ``pbr.cmd``. Additionally, two entry points will be
400 installed for ``pbr.config.drivers``, one called ``plain`` which maps to the
401 ``Plain`` class in ``pbr.cfg.driver`` and one called ``fancy`` which maps to
402 the ``Fancy`` class in ``pbr.cfg.driver``.
403
404 ``backwards_compat``
405 ~~~~~~~~~~~~~~~~~~~~~
406
407 .. todo:: Describe this section
408
409 .. _pbr-setup-cfg:
410
411 ``pbr``
412 ~~~~~~~
413
414 The ``pbr`` section controls *pbr*-specific options and behaviours.
415
416 ``skip_git_sdist``
417 If enabled, *pbr* will not generate a manifest file from *git* commits. If
418 this is enabled, you may need to define your own `manifest template`__.
419
420 This can also be configured using the ``SKIP_GIT_SDIST`` environment
421 variable, as described :ref:`here <packaging-tarballs>`.
422
423 __ https://packaging.python.org/tutorials/distributing-packages/#manifest-in
424
425 ``skip_changelog``
426 If enabled, *pbr* will not generated a ``ChangeLog`` file from *git* commits.
427
428 This can also be configured using the ``SKIP_WRITE_GIT_CHANGELOG``
429 environment variable, as described :ref:`here <packaging-authors-changelog>`
430
431 ``skip_authors``
432 If enabled, *pbr* will not generate an ``AUTHORS`` file from *git* commits.
433
434 This can also be configured using the ``SKIP_GENERATE_AUTHORS`` environment
435 variable, as described :ref:`here <packaging-authors-changelog>`
436
437 ``skip_reno``
438 If enabled, *pbr* will not generate a ``RELEASENOTES.txt`` file if `reno`_ is
439 present and configured.
440
441 This can also be configured using the ``SKIP_GENERATE_RENO`` environment
442 variable, as described :ref:`here <packaging-releasenotes>`.
443
444 .. versionchanged:: 6.0
445
446 The ``autodoc_tree_index_modules``, ``autodoc_tree_excludes``,
447 ``autodoc_index_modules``, ``autodoc_exclude_modules`` and ``api_doc_dir``
448 settings are all removed.
449
450 .. versionchanged:: 4.2
451
452 The ``autodoc_tree_index_modules``, ``autodoc_tree_excludes``,
453 ``autodoc_index_modules``, ``autodoc_exclude_modules`` and ``api_doc_dir``
454 settings are all deprecated.
455
456 .. versionchanged:: 2.0
457
458 The ``pbr`` section used to take a ``warnerrors`` option that would enable
459 the ``-W`` (Turn warnings into errors.) option when building Sphinx. This
460 feature was broken in 1.10 and was removed in pbr 2.0 in favour of the
461 ``[build_sphinx] warning-is-error`` provided in Sphinx 1.5+.
462
463 ``metadata``
464 ~~~~~~~~~~~~
465
466 .. todo:: Describe this section
467
468 .. _build_sphinx-setup-cfg:
469
470 ``build_sphinx``
471 ~~~~~~~~~~~~~~~~
472
473 .. versionchanged:: 3.0
474
475 The ``build_sphinx`` plugin used to default to building both HTML and man
476 page output. This is no longer the case, and you should explicitly set
477 ``builders`` to ``html man`` if you wish to retain this behavior.
478
479 .. deprecated:: 4.2
480
481 This feature has been superseded by the `sphinxcontrib-apidoc`_ (for
482 generation of API documentation) and :ref:`pbr.sphinxext` (for configuration
483 of versioning via package metadata) extensions. It has been removed in
484 version 6.0.
485
486 Requirements
487 ------------
488
489 Requirements files are used in place of the ``install_requires`` and
490 ``extras_require`` attributes. Requirement files should be given one of the
491 below names. This order is also the order that the requirements are tried in:
492
493 * ``requirements.txt``
494 * ``tools/pip-requires``
495
496 Only the first file found is used to install the list of packages it contains.
497
498 .. versionchanged:: 5.0
499
500 Previously you could specify requirements for a given major version of
501 Python using requirements files with a ``-pyN`` suffix. This was deprecated
502 in 4.0 and removed in 5.0 in favour of environment markers.
503
504 .. _extra-requirements:
505
506 Extra requirements
507 ~~~~~~~~~~~~~~~~~~
508
509 Groups of optional dependencies, or `"extra" requirements`__, can be described
510 in your ``setup.cfg``, rather than needing to be added to ``setup.py``. An
511 example (which also demonstrates the use of environment markers) is shown
512 below.
513
514 __ https://www.python.org/dev/peps/pep-0426/#extras-optional-dependencies
515
516 Environment markers
517 ~~~~~~~~~~~~~~~~~~~
518
519 Environment markers are `conditional dependencies`__ which can be added to the
520 requirements (or to a group of extra requirements) automatically, depending on
521 the environment the installer is running in. They can be added to requirements
522 in the requirements file, or to extras defined in ``setup.cfg``, but the format
523 is slightly different for each.
524
525 For ``requirements.txt``::
526
527 argparse; python_version=='2.6'
528
529 This will result in the package depending on ``argparse`` only if it's being
530 installed into Python 2.6.
531
532 For extras specified in ``setup.cfg``, add an ``extras`` section. For instance,
533 to create two groups of extra requirements with additional constraints on the
534 environment, you can use:
535
536 .. code-block:: ini
537
538 [extras]
539 security =
540 aleph
541 bet:python_version=='3.2'
542 gimel:python_version=='2.7'
543 testing =
544 quux:python_version=='2.7'
545
546 __ https://www.python.org/dev/peps/pep-0426/#environment-markers
547
548
549 Sphinx ``conf.py``
550 ------------------
551
552 As described in :doc:`/user/features`, *pbr* provides a Sphinx extension to
553 automatically configure the version numbers for your documentation using *pbr*
554 metadata.
555
556 To enable this extension, you must add it to the list of extensions in
557 your ``conf.py`` file:
558
559 .. code-block:: python
560
561 extensions = [
562 'pbr.sphinxext',
563 # ... other extensions
564 ]
565
566 You should also unset/remove the ``version`` and ``release`` attributes from
567 this file.
568
569 .. _setuptools: http://www.sphinx-doc.org/en/stable/setuptools.html
570 .. _sphinxcontrib-apidoc: https://pypi.org/project/sphinxcontrib-apidoc/
571 .. _reno: https://docs.openstack.org/reno/latest/