Revisit "Package" vs "Distribution" vs "Distribution Packages" about packaging.python.org HOT 37 CLOSED

By the way, is the word "dist" free for this? It's already sort of familiar to people because we have sdist and bdist.

Also, you should probably include this variant in the glossary ("Distribution Package" I mean).

from packaging.python.org.

See issue #89 for a lot more on the terminology challenges :P

The problem with "dist" is mostly its awkwardness as a word. "dists" is really quite hard to say. I think it may be the best option we have available, given the existing sdist and bdist naming.

from packaging.python.org.

The CPython docs update where I ran into the problem: https://hg.python.org/cpython/rev/3acb94e1bab8

from packaging.python.org.

as much as it pains me to go back and forth on stuff, I'm wondering if the original double meaning of "Package" was actually not so bad, given the alternatives. "Distribution Package" seems so cumbersome to me for the PyPUG. As it is now, you've only tweaked a few titles, but we're still left with a lot of bare uses of "Distribution", so it does feel confusing. I can't imagine saying "Distribution Package" over and over again in the PyPUG, and if "Distribution" alone doesn't work in the core docs, then to me, that leaves "Package", but always linking to the glossary term, so users can get the story and how the term is overloaded, and why we're not using "Distribution" alone. We could even write an Advanced section on the whole analyses of the problem of terminology for this.

from packaging.python.org.

@qwcode I pretty much agree. The word "distribution" feels unnatural every time I use it and I end up mangling sentences to try to work around it. It's unfortunate that "package" means multiple things, but (given Linux distro and Python Distribution) so does "distribution". I think that no matter how much we try to promote a new term, people will keep using "package" in everyday discussion. Maybe it's time to accept that and move on. Practicality beats purity and all...

from packaging.python.org.

I think I see a possibility for agreement. How about if we stop using the word "Distribution" as a stand-alone term for the reasons Nick mentioned, and we use the word "Package" for the reasons @qwcode and @pfmoore mentioned. But we prefix Package as "Distribution Package" whenever it's necessary to avoid ambiguity or be precise (presumably these cases will be rare).

I don't know if the docs ever took that approach in a previous iteration.

A funny thing is that I also think "Distribution" is very cumbersome, and I can't imagine ever saying that I would "install a distribution." But I have no problem whatsoever talking about uploading "source distributions," etc. The combined phrase rolls off the tongue much more easily. As a final note, because of built distributions and source distributions, I don't think we'll ever be able to get away from the term "distribution" entirely either.

from packaging.python.org.

Distribution package in section titles to avoid ambiguity, and just
"package" as the typical term in the body of the text would sound good to
me. That aligns pretty well with my original suggestions for the
terminology guide as well.

We can also be happy that we tried the "distributions" experiment and it
didn't work out. I "tried it, really didn't like it" is a better place to
be than just assuming we were stuck with the ambiguous dual meaning of
"package".

from packaging.python.org.

Issue #87 was the original issue regarding the ambiguity of "package".

from packaging.python.org.

If no one else has started, I could put together a PR for this.

from packaging.python.org.

The "distribution package" vs "import package" was a relatively novel phrasing that came up in the discussions on #87 (and was subsequently pulled out to #89).

I think it's definitely worth trying an approach that goes with something like:

• "distribution package" in headings
• "package" in body text, unless it's genuinely ambiguous, then "distribution package" or "import package" as appropriate
• we keep the "Python Packaging Index" change (since that aligns nicely with the expansions of PyPA and PyPUG)

If you have time to put together a PR, it would be good to see how it looked in practice.

from packaging.python.org.

That sounds fine. The only thing I'm wondering about is the heading suggestion. Are you saying, for example, that the heading for the installing tutorial should read, "Tutorial on Installing Distribution Packages"? I'd be concerned that would confuse newcomers that are just trying to learn how to "install a package" (especially since "Distribution Package" is an invented phrase). What about using the common wording in the heading, but the full phrase in the first sentence of the text (with a link to the glossary)?

from packaging.python.org.

I'm happy for the "only when ambiguous" case to apply to headings as well. I suspect the two I already changed would actually be OK with just "Packages" - it was "Distributions" that was ambiguous on the standard library side.

from packaging.python.org.

yea, I think I'd like the headings to be just "Package" as well.
@cjerdonek , I haven't started a PR. go for it.

from packaging.python.org.

I haven't started a PR. go for it.

Great, will do.

from packaging.python.org.

Okay, I made a preliminary PR here: #111

It would help if someone could look over the textual changes in the glossary. The remaining work I believe is limited to tracking down remaining appearances of the lone word "distribution."

After this, we can continue to refine our use of "package" vs. "distribution package" (or "import package") depending on context, etc.

from packaging.python.org.

First, I applaud and appreciate the efforts here.

Some comments:

Scope

I think this discussion only needs to solve what words to use to refer to each meaning of "package" within PPUG docs.

It doesn't need to invent new words -- qualified versions of "package" ("distribution package" versus "module package" [or "importable package"]) are fine; it's just a more precise version of the words people already use.

Nor does this discussion need to contemplate requiring the use of these precise words elsewhere, though it could beneficially influence other docs intended for readers new to the material, such as the docs for 3rd party packaging tools.

PPUG's mission means that "Package" should be qualified

The word "package" deserves special attention for these reasons:

1. The central topic of the Python Packaging User Guide is packages.
2. In discussions of packaging, the word "package" is highly likely to show up in both of its senses, leading to confusion. Why? ...
3. Experienced readers can often identify from context which meaning of "package" is intended, because they can use their prior knowledge to reason that the other meaning doesn't "make sense". However a crucial segment of PPUG's audience (whose practices you are hoping to elevate and unify) comes to PPUG to learn things they don't already know.

These readers do not have a prior understanding of the other words in a sentence to help them pick the meaning of "package". Instead, they need to process "package" first, unambigously, to give them a firm foothold from which to gain traction on the other words in the sentence.

A fairly obvious corollary is that a PPUG writer is in the worst position to intuit whether a usage of "package" is ambiguous. Having written the piece, one already knows what was intended, at the same time that prior knowledge leads one away from alternative (incorrect) interpretations.

Bottom line: To serve the core mission of PPUG, within PPUG docs "package" should always be qualified. The downside of doing so is minimal, the upside is reader comprehension.

from packaging.python.org.

Answers to a couple of comments

@qwcode: ' "Distribution Package" seems so cumbersome to me for the PyPUG. ' I don't dispute that. However, the main audience you are trying to reach is people who don't already know the material. For them the gain in clarity outweighs the small increment in cumbersomeness.

'that leaves "Package", but always linking to the glossary term'. I am 100% in favor of always identifying which sense is intended. But I strongly urge against implementing that as a link:

1. The links tell the reader 'we know you may have a problem understanding this sentence as it stands, and rather than fix the nomenclature, or fix the sentence, we are going to leave this incomprehensible sentence and send you on a hyperlink goose chase to try and figure it out'. Injury + insult.
2. It will be meaningless if copy/pasted or printed.

@pfmoore: As my previous post noted, in the context of PPUG Packaging docs, the word package is crucial.

The word "distribution" does not provide a compelling comparison because, within the Python packaging universe, the topic of linux distributions is not nearly as apt to cause confusions. Certainly, there could be a discussion about which Python distribution packages are contained in some linux distro, in which case distinct terms should be used to make sure the reader doesn't get confused (like I just did in this sentence).

from packaging.python.org.

Bottom line: To serve the core mission of PPUG, within PPUG docs "package" should always be qualified. The downside of doing so is minimal, the upside is reader comprehension.

Hi @gwideman, thanks for your comments. I don't think this is correct though, and I'll provide an example. (I also made this point above here.)

Take the title of the main tutorial for people to install packages, which currently reads, "Tutorial on Installing Distributions," which I'm proposing we change to "Tutorial on Installing Packages."

"Package" is the word that most people are familiar with. For example, it's the language that appears on the PyPI home page, and it's what PyPI calls packages.

In top-level section headings especially, I think it's better to use what people are familiar with because that's what they have in mind when they go looking for help. Along similar lines, unless we are advocating for a broad terminology change in the community, there is a benefit to using the language that people will be seeing elsewhere on the web (e.g. in Google results, Stackoverflow, etc). If we are constantly using terminology unique to PyPUG, it makes it seem like we are talking about a different concept or topic matter than what non-experts are used to.

from packaging.python.org.

For the record Warehouse uses Project/Release/(Files|Distributions).

from packaging.python.org.

Okay, that is interesting. Hmm, it would be nice if Warehouse, PyPI, pip, etc. could move towards using the same terminology. Then we wouldn't need to be going back and forth here. Has PyPA itself agreed on what it should be calling these things (on tool home pages and in their own docs, etc)? Or is that the topic of issue #89?

from packaging.python.org.

with @dstufft / Warehouse using "Distribution" and @ncoghlan saying "bare "Distributions" really didn't work in the context of the standard library docs", we're kinda stuck.

from packaging.python.org.

Note that can change, I don't really care what we use, though i'd rather not change the "project" moniker.

from packaging.python.org.

Certainly, there could be a discussion about which Python distribution packages are contained in
some linux distro, in which case distinct terms should be used to make sure the reader doesn't get
confused (like I just did in this sentence).

but @gwideman , this sentence can be confusing to parse as well.
Is it "Python distribution" -> "packages"
Or "Python" -> "distribution packages"

I'm just really not wanting to use a double term like "distribution package".

from packaging.python.org.

I keep coming back to staying with "package", but just explain the double use with links and/or footnotes, and even an "Advanced" section to break it all down.

from packaging.python.org.

If we don't know what packages will be called in the future, then I favor mostly using "package."

But if there's a chance that PyPA (Warehouse, pip, etc) will be aligning behind "distribution" or something else then that changes things a bit, because we wouldn't want to work against that change. To @pfmoore's point that "no matter how much we try to promote a new term, people will keep using "package" in everyday discussion," I think that was doomed to fail since PyPI itself calls them packages. With Warehouse combined with the fact that pip is under the PyPA umbrella, it seems like there is a chance for a "reset."

from packaging.python.org.

I think project/release/file works well enough for Warehouse/PyPI.
Distribution packages (sdist, bdist_*), platform specific installers and
standalone executables would all fall under the "files" heading for a given
release.

For PyPUG, I think it's worth trying the more concise spelling, and seeing
what kind of feedback we get. It may also be worth including an explicit "A
note on 'packages'" that introduces the duality, and explains that it means
both "distribution package" and "import package", and the difference is
usually implied by context (installing/publishing = distribution package,
writing Python code = import package).

This is an ambiguity that's so firmly entrenched, I think our only hope is
to equip newcomers to deal with it.

from packaging.python.org.

@qwcode wrote:

but @gwideman , this sentence can be confusing to parse as well.
Is it "Python distribution" -> "packages"
Or "Python" -> "distribution packages"

Fair point. I did actually check whether python.org uses "distribution" to refer to a python installation kit assembled and offered by a particular supplier, and didn't find it there. However, on google I see that "Python distribution" is widely used this way, as in "Anaconda Python distribution" and so on.

So, clearly I was showing an example of a writer unaware of an ambiguity. :-)

Anyhow, I continue to think that "distribution" as a modifier of "package" is unlikely to be confused with linux distribution, while instances of bare "package" (with two different meanings) often appear in the same context, and are apt to be confusing for readers who don't understand the context beforehand.

from packaging.python.org.

@cjerdonek wrote: 'Take the title of the main tutorial for people to install packages, which currently reads, "Tutorial on Installing Distributions," which I'm proposing we change to "Tutorial on Installing Packages." '

What is a user who is searching for a tutorial on how to deploy their code likely to know already?

They almost certainly know the python language concept of "package" in connection with "import", with the connotation "library".

However, not yet having read about how to wrap up and deploy code, they don't yet know that the title "Tutorial on installing packages" uses a different meaning of package. Consequently, they interpret that sentence to mean something about deploying importable packages, or in other words, libraries.

If they are looking for how to deploy a complete application written in Python, or just a simple script, then the "installing a package" seems to them like it's not the topic they want.

from packaging.python.org.

@ncoghlan, @cjerdonek I am also happy to go with qualifying "package" "only when ambiguous". It's just that I think, for the uninitiated reader, it's ambiguous most of the time in the kind of docs that PPUG covers. :-)

If there's a page that discusses only one type of package or the other, then I suspect that's fine -- establish at the beginning which kind of package is the topic, and then probably no need to qualify subsequently.

For pages that refer to both kinds of package, it's far too easy to baffle the reader, who doesn't (yet) have the wherewithal to figure them out from context.

from packaging.python.org.

On the term "distribution".

1. The software upon which distribution relies is called 'distutils', not 'packageutils. However, the distutils docs freely use "package" in place of "distribution".
2. PEP 426: ' the individual software components distributed in that phase are formally referred to as "distributions", but are more colloquially known as "packages" '

In short, despite the baked-in PEP-ordained nature of "distribution" as the official term, "package" is the term that persists, and it's what people say and write most of the time. So it's pretty certain that "package" will be the basic name going forward.

The remaining issue, for PPUG, is how to write articles for uninitiated readers such that there's minimal possibility of confusing them regarding which use of "package" means what.

So, either establish a simple rule (like "always qualify each instance"), or engage in judgement about ambiguity for every instance. Given that the writer is apt to underestimate that ambiguity, a rule has a better chance of reliable result.

Then it's a tradeoff regarding rule simplicity vs subtlety: "qualify every instance" versus "qualify the first instance in a paragraph or section, but you don't need to qualify each subsequent instance if it's clear that the subsequent instances can only refer back to the most recent qualified instance".

The simpler rule is easy to remember and more robust, while the latter might make reading more pleasant, but is vulnerable to later edits rearranging the text.

from packaging.python.org.

I think there is a practical point here as well. In writing things like emails, documentation, etc, I have tried to maintain the distribution/package distinction for some time now. And frankly, I have found that it is simply too awkward to do so consistently. It happens too often that using the word "distribution" results in an awkward turn of phrase, that leaves you rewording large chunks of your text to get round it (the worst offender here by far is "distributing a distribution"...)

To be perfectly honest, the inclination expressed here to go back to using "package" fills me with relief, as it feels as though I've been given permission to write my emails in a "natural" way again.

from packaging.python.org.

ok folks, see what I merged in #115.
wanting to close this issue....

from packaging.python.org.

Ok, this may look a bit tardy but humour these concerns:

While in the PPUG it's easy to reference the term (to the second meaning in the glossary), it's not so convenient to do it anywhere else. Think about a conversation where 2 people use the same term but they mean different things.

"packaging a package" doesn't sound right. IMHO it's as bad as saying "distributing a distribution". For all the confusion the "distribution" term created for people that didn't bother to read the docs, at least it had a clear meaning without requiring a context.

What other options have been explored? How about: "package set", "release", "collection" or just "archive"? Maybe "bundle"? Actually, no, that's used in that deprecated pip feature.

Also, I see that the common argument against "distribution" is the fact that the "package" term is being used by linux distros. Ruby doesn't seem to have this problem, and they don't use the "package" term either, why Python has it then?

On the other hand, if we start renaming things, I think we should go all the way and rename the "package" (the first meaning, the directory with submodules) to something else. Otherwise we haven't really improved clarity.

from packaging.python.org.

The problem is that we have 10 years of experience referring to both distribution and import packages as "packages". Folks are going to encounter that in the real world, so we eventually decided that having the PyPUG attempt to describe new terminology that didn't match the way people actually talked in the real world would end up confusing newcomers more than it helped them.

That said, I'd personally prefer to elevate "distribution package" and "import package" to defined terms, rather than the cryptic "package meaning 1" and "package meaning 2". I was OK with the latter approach while reviewing the PR, but that was when I had the definitions right in front of me - from the perspective of several days since reading them, I have absolutely no idea which numeric reference is which, while I still know exactly what "distribution package" and "import package" mean.

from packaging.python.org.

(Actually, I think the dual meaning may go back to the birth of distutils itself, rather than setuptools - that would make it 16 years of history for the dual meaning, rather than 10).

from packaging.python.org.

@ncoghlan +100 on your comment.

from packaging.python.org.

I'd personally prefer to elevate "distribution package" and "import package" to defined terms

another PR revision coming up....

from packaging.python.org.