I would like to get an overview document added to the PyPA documentation, to be listed ahead of, or right beside, the Tutorial. As an outsider, the publishing flow is unclear.
There’s discussion in the “modernising my packages” thread about why I think we need a concise overview of the flow. I’ll repeat here what my design objectives for the document are:
This document is supposed to:
be short - a layout of the flow to distribute something, describing the pieces and their relationships
not be a tutorial; there’s a nice tutorial already
with some examples but not prescriptive except in the sense of prescribing “you need to make some distribution files”
So:
it has a point list of the objectives, starting at the author and arriving at the end user
it goes over each of those points in a little detail after the main list, to make them clear
it has some references to the places where relevant things are specified (PEPs, tools)
Use very simple English. Avoid synonyms and any words that a beginner, non-native English speaker, or reader from different technical background might mistake for technical terminology.
Most importantly, avoid introducing even more new terminology. Python Packaging already has too many confusing concepts.
Examples: packaging flow, source tree, build artifact, upload facilities, generic wheel, package distribution service, …
They are not in the glossary. They should be added if they are important concepts. They should be replaced by simpler words if they are not important concepts.
Remove filler words like “of course” and vague words like “typically”, “usually”, “including but not limited to”. Remove any sentence, piece of information, any single word not absolutely necessary. For example the entire two first paragraphs should be removed.
Don’t mention PEPs and PEP numbers. They are change proposals, not documentation.
If you’re asking about process, you should be able to create a PR against the packaging user guide here. The maintainers there can help with details of wording, style and layout.
I’d honestly suggest doing that, using your existing document as the starting point for a new bullet point under the Getting Started section, something like “To get an overview of the packaging workflow”. Improving something that’s there is easy, the key thing is to get it added.
I am worried about the use of the word “package”, it is confusing, it is never clear which meaning is implied: “import package” or “distribution package”.
By sinoroc via Discussions on Python.org at 28Jun2022 20:34:
I am worried about the use of the word “package”, it is confusing, it
is never clear which meaning is implied: “import
package”
or “distribution
package”.
I applied this suggestion, like this:
-The document aims to outline the flow involved in publishing a package,
-usually to the `Python Package Index (PyPI)`_.
+The document aims to outline the flow involved in publishing/distributing
+a `distribution package`_, usually to the `Python Package Index
(PyPI)`_.
+.. _distribution package: https://packaging.python.org/en/latest/glossary/#term-Distribution-Package
.. _Python Package Index (PyPI): https://pypi.org/
but on consideration I’ve undone that, because this is about the entire
flow from the author’s source to the end user, and includes both wheels
and sdists. The glossary makes it clear that sdists are not distribution
packages, and the term “import package” in the glossary is vague enough
to bring no clarity to an introductory document like this.
So I’m sticking with “package”, and hoping that people want to publish
their code glom that to the idea of a self contained collection of code
to go out with a name.
I definitely second the concern about the confusion between import packages and distribution packages, given these are distinct concepts that routinely confuse users who conflate them, but are certainly not the same, as discussed in e.g. this recent thread. I haven’t reviewed it in detail, but the guide should at minimum make this distinction this upfront with a link to the glossary definition, and then preferably repeat and/or link the full term whenever needed, and make special note when an import package is discussed to always refer to it as such, with a link to the glossary.
Wait, huh? Where does it do that? The definition of a distribution package states they are
A versioned archive file that contains Python packages, modules, and other resource files that are used to distribute a [Release](Glossary - Python Packaging User Guide … A distribution package is more commonly referred to with the single words “package” or “distribution”.
and then defines a sdist as
A distribution format (usually generated using python setup.py sdist) that provides metadata and the essential source files needed for installing by a tool like pip, or for generating a Built Distribution.
Since it states that sdists are a “distribution” (with that word explicit linked to the definition of “distribution package”, I’m not sure how it gave the impression that sdists are not distribution packages.
By C.A.M. Gerlach via Discussions on Python.org at 28Jun2022 23:45:
I definitely second the concern about the confusion between import
packages and distribution packages, given these are distinct concepts
that routinely confuse users who conflate them, but are certainly not
the same, as discussed in e.g. this recent
thread.
I haven’t reviewed it in detail, but the guide should at minimum make
this distinction this upfront with a link to the glossary definition,
and then preferably repeat and/or link the full term whenever needed,
and make special note when an import package is discussed to always
refer to it as such, with a link to the glossary.
Wait, huh? Where does it do that? The definition of a distribution package states they are
Gah.
I conflated it with the paragraph about a “Built Distribution” directly
above. I think I just let my eyes drift. So I’ll put back my diff using @sinoroc’s suggestion.
It now reads:
The document aims to outline the flow involved in publishing/distributing
a `distribution package`_, usually to the `Python Package Index (PyPI)`_.
.. _distribution package:
https://packaging.python.org/en/latest/glossary/#term-Distribution-Package
.. _Python Package Index (PyPI): https://pypi.org/