Skip to content

Commit dc4ff66

Browse files
jeanaswebknjaz
authored andcommitted
Address @chrysle's review
1 parent b9878e6 commit dc4ff66

File tree

1 file changed

+19
-15
lines changed

1 file changed

+19
-15
lines changed

source/guides/tool-recommendations.rst

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,15 @@ Tool recommendations
55
====================
66

77
The Python packaging landscape consists of many different tools. For many tasks,
8-
the Python Packaging Authority (PyPA, the umbrella organization which
9-
encompasses many packaging tools and maintains this guide) purposefully does not
10-
make a blanket recommendation; for example, the reason there exist many build
11-
backends is that the landscape was opened in order to enable the development of
12-
new backends serving certain users' needs better than the previously unique
13-
backend, setuptools. This guide does point to some tools that are widely
14-
recognized, and also makes some recommendations of tools that you should *not*
15-
use because they are deprecated or insecure.
8+
the :term:`Python Packaging Authority <Python Packaging Authority (PyPA)>`
9+
(PyPA, the umbrella organization which encompasses many packaging tools and
10+
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'
13+
needs better than the previously unique backend, setuptools. This guide does
14+
point to some tools that are widely recognized, and also makes some
15+
recommendations of tools that you should *not* use because they are deprecated
16+
or insecure.
1617

1718

1819
Virtual environments
@@ -26,16 +27,18 @@ the Python standard library, though missing some features of virtualenv).
2627
Installing packages
2728
===================
2829

29-
:ref:`Pip` is a standard tool to install packages from :term:`PyPI <Python
30+
:ref:`Pip` is the standard tool to install packages from :term:`PyPI <Python
3031
Package Index (PyPI)>`. It can install into the global environment or into
3132
virtual environments. You may want to read pip's recommendations for
3233
:doc:`secure installs <pip:topics/secure-installs>`. Pip is available by default
3334
in most Python installations.
3435

3536
Alternatively, for installing Python command line applications specifically,
3637
consider :ref:`pipx`, which is a wrapper around pip that installs each
37-
application into a dedicated virtual environment in order to avoid conflicts
38-
with other applications and, on Linux, conflicts with the system.
38+
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>`).
3942

4043
For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`.
4144

@@ -65,11 +68,12 @@ Popular :term:`build backends <build backend>` for pure-Python packages include:
6568
Hatch as well). Hatchling is extensible through a plugin system.
6669

6770
- :ref:`setuptools`, the historical build backend. It can be configured
68-
programmatically through the :file:`setup.py` file.
71+
programmatically through the :file:`setup.py` file (but for basic metadata,
72+
:file:`pyproject.toml` is preferred).
6973

7074
If you use setuptools, please be aware that it contains many deprecated
7175
features which are currently kept for compatibility, but should not be used.
72-
For example, do not use ``python setup.py`` invocations
76+
For example, do **not** use ``python setup.py`` invocations
7377
(cf. :ref:`setup-py-deprecated`), the ``python_requires`` argument to
7478
``setup()`` (use the :ref:`[build-system] table
7579
<pyproject-guide-build-system-table>` of :file:`pyproject.toml` instead), or
@@ -84,8 +88,8 @@ Popular :term:`build backends <build backend>` for pure-Python packages include:
8488
- Poetry-core, part of :ref:`Poetry` (but usable standalone). It is extensible
8589
through plugins.
8690

87-
Do **not** use distutils, which is deprecated, and has been removed from the
88-
standard library in Python 3.12, although it still remains available from
91+
Do **not** use :ref:`distutils`, which is deprecated, and has been removed from
92+
the standard library in Python 3.12, although it still remains available from
8993
setuptools.
9094

9195
For packages with :term:`extension modules <extension module>`, you may use

0 commit comments

Comments
 (0)