@@ -6,10 +6,10 @@ Tool recommendations
66
77The Python packaging landscape consists of many different tools. For many tasks,
88the :term: `Python Packaging Authority <Python Packaging Authority (PyPA)> `
9- (PyPA, the umbrella organization which encompasses many packaging tools and
9+ (PyPA, the working group which encompasses many packaging tools and
1010maintains this guide) purposefully does not make a blanket recommendation; for
11- example, the reason there exist many build backends is that the landscape was
12- opened in order to enable the development of new backends serving certain users'
11+ example, the reason there are many build backends is that the landscape was
12+ opened up in order to enable the development of new backends serving certain users'
1313needs better than the previously unique backend, setuptools. This guide does
1414point to some tools that are widely recognized, and also makes some
1515recommendations of tools that you should *not * use because they are deprecated
@@ -31,14 +31,15 @@ Installing packages
3131Package Index (PyPI)> `. It can install into the global environment or into
3232virtual environments. You may want to read pip's recommendations for
3333:doc: `secure installs <pip:topics/secure-installs >`. Pip is available by default
34- in most Python installations.
34+ in most Python installations through the standard library package
35+ :doc: `ensurepip <python:library/ensurepip >`.
3536
36- Alternatively, for installing Python command line applications specifically,
37- consider :ref: `pipx `, which is a wrapper around pip that installs each
37+ Alternatively, consider :ref: `pipx ` for the specific use case of installing Python
38+ command line applications that are distributed through PyPI.
39+ Pipx is a wrapper around pip and venv that installs each
3840application into a dedicated virtual environment. This avoids conflicts between
39- the dependencies of different applications. On Linux, pipx is especially
40- important because it also avoids conflicts with the system (which are the reason
41- for :ref: `externally managed environments <externally-managed-environments >`).
41+ the dependencies of different applications, and also with the system
42+ (especially on Linux).
4243
4344For scientific software specifically, consider :ref: `Conda ` or :ref: `Spack `.
4445
@@ -64,10 +65,10 @@ Build backends
6465
6566Popular :term: `build backends <build backend> ` for pure-Python packages include:
6667
67- - Hatchling , which is part of :ref: `Hatch ` ( but can be used without
68- Hatch as well) . Hatchling is extensible through a plugin system.
68+ - Hatchling _ , which is developed along with :ref: `Hatch `, but is separate and can
69+ be used without Hatch . Hatchling is extensible through a plugin system.
6970
70- - :ref: `setuptools `, the historical build backend. It can be configured
71+ - :ref: `setuptools ` (which used to be the only build backend) . It can be configured
7172 programmatically through the :file: `setup.py ` file (but for basic metadata,
7273 :file: `pyproject.toml ` is preferred).
7374
@@ -79,23 +80,25 @@ Popular :term:`build backends <build backend>` for pure-Python packages include:
7980 <pyproject-guide-build-system-table>` of :file: `pyproject.toml ` instead), or
8081 the ``easy_install `` command (cf. :ref: `pip vs easy_install `).
8182
82- - Flit-core, part of :ref: `Flit ` (but usable standalone ). It is meant to be a
83+ - Flit-core _ (developed with but separate from :ref: `Flit `). It is meant to be a
8384 minimal and opinionated build backend. It is not extensible.
8485
85- - PDM-backend _, part of :ref: `PDM ` (but usable standalone ). It provides build
86+ - PDM-backend _ (developed with but separate from :ref: `PDM `). It provides build
8687 hooks for extensibility.
8788
88- - Poetry-core, part of :ref: `Poetry ` (but usable standalone ). It is extensible
89+ - Poetry-core _ (developed with but separate from :ref: `Poetry `). It is extensible
8990 through plugins.
9091
9192Do **not ** use :ref: `distutils `, which is deprecated, and has been removed from
9293the standard library in Python 3.12, although it still remains available from
9394setuptools.
9495
9596For packages with :term: `extension modules <extension module> `, you may use
96- setuptools, but consider using a build system dedicated to the language the
97- extension is written in, such as Meson or CMake for C/C++, or Cargo for Rust,
98- and bridging this build system to Python using a dedicated build backend:
97+ setuptools. However, you can also use a build system with dedicated support for
98+ the language the extension is written in. For example, you could choose Meson or
99+ CMake for C, C++, Fortran and many other compiled languages; or Cargo for Rust
100+ specifically. You can then bridge this build system to Python using a dedicated
101+ build backend:
99102
100103- :ref: `meson-python ` for Meson,
101104
@@ -135,13 +138,17 @@ Integrated workflow tools
135138
136139These are tools that combine many features in one command line application, such
137140as automatically managing virtual environments for a project, building
138- distributions, uploading to PyPI, or creating and using lock files.
141+ distributions, uploading to PyPI, or creating and using (tool-specific) lock
142+ files. They often call the tools mentioned above under the hood.
139143
140144- :ref: `Hatch `,
141145- :ref: `Flit `,
142146- :ref: `PDM `,
143147- :ref: `Poetry `.
148+ - :ref: `Pipenv `
144149
145150
146-
151+ .. _flit-core : https://pypi.org/project/flit-core/
152+ .. _hatchling : https://pypi.org/project/hatchling/
147153.. _pdm-backend : https://backend.pdm-project.org
154+ .. _poetry-core : https://pypi.org/project/poetry-core/
0 commit comments