@@ -5,14 +5,15 @@ Tool recommendations
55====================
66
77The 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
1819Virtual environments
@@ -26,16 +27,18 @@ the Python standard library, though missing some features of virtualenv).
2627Installing 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
3031Package Index (PyPI)> `. It can install into the global environment or into
3132virtual environments. You may want to read pip's recommendations for
3233:doc: `secure installs <pip:topics/secure-installs >`. Pip is available by default
3334in most Python installations.
3435
3536Alternatively, for installing Python command line applications specifically,
3637consider :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
4043For 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
8993setuptools.
9094
9195For packages with :term: `extension modules <extension module> `, you may use
0 commit comments