Skip to content

Commit 620222c

Browse files
jeanaswebknjaz
authored andcommitted
Address review comments from @webknjaz and @eli-schwartz
1 parent f5df941 commit 620222c

1 file changed

Lines changed: 27 additions & 20 deletions

File tree

source/guides/tool-recommendations.rst

Lines changed: 27 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,10 @@ Tool recommendations
66

77
The Python packaging landscape consists of many different tools. For many tasks,
88
the :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
1010
maintains 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'
1313
needs better than the previously unique backend, setuptools. This guide does
1414
point to some tools that are widely recognized, and also makes some
1515
recommendations of tools that you should *not* use because they are deprecated
@@ -31,14 +31,15 @@ Installing packages
3131
Package Index (PyPI)>`. It can install into the global environment or into
3232
virtual 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
3840
application 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

4344
For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`.
4445

@@ -64,10 +65,10 @@ Build backends
6465

6566
Popular :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

9192
Do **not** use :ref:`distutils`, which is deprecated, and has been removed from
9293
the standard library in Python 3.12, although it still remains available from
9394
setuptools.
9495

9596
For 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

136139
These are tools that combine many features in one command line application, such
137140
as 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

Comments
 (0)