Skip to content

Commit 0a5069e

Browse files
committed
Apply suggestions by @warsawnv
1 parent 641e748 commit 0a5069e

File tree

1 file changed

+14
-9
lines changed

1 file changed

+14
-9
lines changed

peps/pep-0771.rst

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ packages.
100100
Rationale
101101
=========
102102

103-
A number of possible solutions have been extensively discussed by
103+
A number of possible solutions have been discussed extensively by
104104
the community for several years, including in `this DPO thread
105105
<https://discuss.python.org/t/adding-a-default-extra-require-environment/4898>`__
106106
as well as in numerous issues and pull requests. The solution that is
@@ -214,7 +214,8 @@ once with no extras specified.
214214

215215
An empty set of extras, such as ``package[]`` should be interpreted as meaning
216216
that the package should be installed *without* any default extras (unless
217-
``package`` appears elsewhere in the dependency tree as mentioned above). This
217+
``package`` appears elsewhere in the dependency tree, in which case, the default
218+
extra *would* be installed as mentioned above). This
218219
would provide a universal way of obtaining a minimal installation of a package.
219220

220221
We also note that some tools such as `pip`_ currently ignore unrecognized
@@ -300,7 +301,7 @@ meaning that installing:
300301
301302
$ pip install astropy
302303
303-
would then also install optional but important optional dependencies such as
304+
would then also install optional but recommended dependencies such as
304305
`scipy <https://www.scipy.org>`_. Advanced users who want a minimal install
305306
could then use:
306307

@@ -483,14 +484,14 @@ Ideally, one may want the following behavior:
483484
$ pip install package[backend1, frontend2] # installs backend1 and frontend2
484485
485486
However, this PEP chooses not to provide a mechanism for making it so that e.g., if
486-
``backend1`` is specified, this disabling the default backend but keeps the default
487-
frontend, since this adds complexity.
487+
``backend1`` is specified, the default backend would be disabled, but the
488+
default frontend would be enabled, since this adds complexity.
488489

489490
Maintainers should instead for now document that if a backend or frontend is
490491
explicitly specified, both backend and frontend need to be specified.
491492
Discoverability for users who want to do this should not be an issue however since users
492493
need to read the documentation in any case to find out what backends or frontends are
493-
available, so they can be shown at the same time how do properly use the extras for
494+
available, so they can be shown at the same time how to properly use the extras for
494495
backends and frontends.
495496

496497
One option to increase user friendliness is that maintainers can create extras
@@ -671,10 +672,14 @@ mean that all extras need to be defaults, and there is still scope for users to
671672
explicitly opt in to non-default extras.
672673

673674
In essence, default extras should be considered just as 'weighty' as a required
674-
dependency. In some cases, if a package is widely used by many others, if it
675+
dependency. In some cases, if a package is widely used by many others and
675676
adds a default extra, then unless all downstream packages update their
676677
dependencies to specifically request a minimal installation, the defaults will
677-
Default extras should generally be treated with the same "weight" as required dependencies. When a package is widely used, introducing a default extra will result in that extra's dependencies being transitively included -- unless all downstream packages are updated to explicitly opt out using minimal installation specifications.
678+
Default extras should generally be treated with the same "weight" as required
679+
dependencies. When a package is widely used, introducing a default extra will
680+
result in that extra's dependencies being transitively included -- unless all
681+
downstream packages are updated to explicitly opt out using minimal installation
682+
specifications.
678683

679684
As an example, the `pytest <https://docs.pytest.org/>`_ package currently has nearly 1,500 plugins that depend on it. If pytest were to add a default extra and those plugins were not updated accordingly, installing a plugin would include the default extras' dependencies. This doesn’t preclude the use of default extras, but addition of default extras requires careful evaluation of its downstream effects.
680685

@@ -741,7 +746,7 @@ solved by changing the dependency tree to instead be::
741746
└── package2
742747
└── package1[]
743748

744-
assuming that ``package2`` indeed does not depend on any features provided by
749+
assuming that indeed ``package2`` does not depend on any features provided by
745750
the extra dependencies of ``package1``. Authors therefore need to carefully
746751
consider a migration plan, coordinating with the authors of ``package2``.
747752

0 commit comments

Comments
 (0)