@@ -94,7 +94,7 @@ a few important reasons to provide a static archive file instead:
9494How?
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
9898from the package's Git repository ** that are necessary to build the package
9999itself, run its test suite, build and install its documentation, and any other
100100files 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)
108108should also be included, to help downstreams determine the needed dependencies,
109109and 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
118128A good idea is to use your source distribution in the release workflow.
119129For 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