Skip to content

Commit 169281d

Browse files
committed
Clarify source distributions
Clarify that "source distributions" generally refer to the files published on PyPI, and when we are referring to publishing them elsewhere. While at it, expand on the size/fallback argument, and mention that some projects install tests as part of the Python package.
1 parent e596609 commit 169281d

File tree

1 file changed

+20
-7
lines changed

1 file changed

+20
-7
lines changed

source/discussions/downstream-packaging.rst

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ a few important reasons to provide a static archive file instead:
9494
How?
9595
~~~~
9696

97-
Ideally, **a source distribution archive should include all the files
97+
Ideally, **a source distribution archive published on PyPI should include all the files
9898
from the package's Git repository** that are necessary to build the package
9999
itself, run its test suite, build and install its documentation, and any other
100100
files that may be useful to end users, such as shell completions, editor
@@ -108,12 +108,22 @@ the files listing these dependencies (for example, ``requirements*.txt`` files)
108108
should also be included, to help downstreams determine the needed dependencies,
109109
and check for changes in them.
110110

111-
Some projects are concerned about increasing the size of source distributions,
112-
or do not wish Python packaging tools to fall back to source distributions
113-
automatically. In these cases, a good compromise may be to publish a separate
114-
source archive for downstream use, for example by attaching it to a GitHub
115-
release. Alternatively, large files, such as test data, can be split into
116-
separate archives.
111+
Some projects have concerns related to Python package managers using source
112+
distributions from PyPI. They do not wish to increase their size with files
113+
that are not used by these tools, or they do not wish to publish source
114+
distributions at all, as they enable a problematic or outright nonfunctional
115+
fallback to building the particular project from source. In these cases, a good
116+
compromise may be to publish a separate source archive for downstream use
117+
elsewhere, for example by attaching it to a GitHub release. Alternatively,
118+
large files, such as test data, can be split into separate archives.
119+
120+
On the other hand, some projects (NumPy_, for instance) decide to install tests
121+
in their Python packages. This has the added advantage of permitting users to
122+
run tests after installing them, for example to check for regressions
123+
after upgrading a dependency. Yet another approach is to split tests or test
124+
data into a separate Python package. Such an approach was taken by
125+
the cryptography_ project, with the large test vectors being split
126+
to cryptography-vectors_ package.
117127

118128
A good idea is to use your source distribution in the release workflow.
119129
For example, the :ref:`build` tool does exactly that — it first builds a source
@@ -459,3 +469,6 @@ as well. Some specific suggestions are:
459469
.. _pytest-rerunfailures: https://pypi.org/project/pytest-rerunfailures/
460470
.. _pytest-timeout: https://pypi.org/project/pytest-timeout/
461471
.. _Django: https://www.djangoproject.com/
472+
.. _NumPy: https://numpy.org/
473+
.. _cryptography: https://pypi.org/project/cryptography/
474+
.. _cryptography-vectors: https://pypi.org/project/cryptography-vectors/

0 commit comments

Comments
 (0)