@@ -5,14 +5,15 @@ Tool recommendations
5
5
====================
6
6
7
7
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.
16
17
17
18
18
19
Virtual environments
@@ -26,16 +27,18 @@ the Python standard library, though missing some features of virtualenv).
26
27
Installing packages
27
28
===================
28
29
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
30
31
Package Index (PyPI)> `. It can install into the global environment or into
31
32
virtual environments. You may want to read pip's recommendations for
32
33
:doc: `secure installs <pip:topics/secure-installs >`. Pip is available by default
33
34
in most Python installations.
34
35
35
36
Alternatively, for installing Python command line applications specifically,
36
37
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 >`).
39
42
40
43
For scientific software specifically, consider :ref: `Conda ` or :ref: `Spack `.
41
44
@@ -65,11 +68,12 @@ Popular :term:`build backends <build backend>` for pure-Python packages include:
65
68
Hatch as well). Hatchling is extensible through a plugin system.
66
69
67
70
- :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).
69
73
70
74
If you use setuptools, please be aware that it contains many deprecated
71
75
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
73
77
(cf. :ref: `setup-py-deprecated `), the ``python_requires `` argument to
74
78
``setup() `` (use the :ref: `[build-system] table
75
79
<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:
84
88
- Poetry-core, part of :ref: `Poetry ` (but usable standalone). It is extensible
85
89
through plugins.
86
90
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
89
93
setuptools.
90
94
91
95
For packages with :term: `extension modules <extension module> `, you may use
0 commit comments