@@ -94,7 +94,7 @@ a few important reasons to provide a static archive file instead:
94
94
How?
95
95
~~~~
96
96
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
98
98
from the package's Git repository ** that are necessary to build the package
99
99
itself, run its test suite, build and install its documentation, and any other
100
100
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)
108
108
should also be included, to help downstreams determine the needed dependencies,
109
109
and check for changes in them.
110
110
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.
117
127
118
128
A good idea is to use your source distribution in the release workflow.
119
129
For example, the :ref: `build ` tool does exactly that — it first builds a source
@@ -459,3 +469,6 @@ as well. Some specific suggestions are:
459
469
.. _pytest-rerunfailures : https://pypi.org/project/pytest-rerunfailures/
460
470
.. _pytest-timeout : https://pypi.org/project/pytest-timeout/
461
471
.. _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