[Distutils] Name the software! Package quality tester.
pje at telecommunity.com
Thu Mar 10 18:55:35 CET 2011
At 08:08 AM 3/10/2011 -0500, Jim Fulton wrote:
>I really should let this rest ....... really ....
I notice you seem to have already let rest defending your proposal,
as opposed to opposing mine. ;-)
That is, I don't see where you've included any counterargument for
why convincing people to *stop* using "package" for "python package"
isn't going to be a lot harder than simply *adding* the term
"project" to existing docs, via simple explanations like this one:
"If you would like to distribute your python package or module, you
need to create a project. A project consists of a directory
containing the package(s) or module(s) you want to distribute, along
with a setup.py/.cfg, specifying the project's name, current version
number, and other information. If you wish to distribute your
package via PyPI, then you must choose a unique project name and
register it. If you are only distributing one module or package,
you can name the project after it, as long as it doesn't conflict
with any other project names already registered on PyPI."
Context-specific explanations like this are easy to give, at a place
where the recipient of the explanation *wants* to learn something.
In contrast, to convince everybody in the world to replace "package"
with "module", you must send out a constant broadcast to people who
don't really care.
(your other points are addressed below)
>On Wed, Mar 9, 2011 at 11:43 AM, P.J. Eby <pje at telecommunity.com> wrote:
> > At 07:06 AM 3/9/2011 -0500, Jim Fulton wrote:
> >> They certainly aren't "projects" in any sense that most people would
> >> understand.
> > I don't follow you. Sourceforge hosts projects. Freshmeat indexes
> > projects. Mozdev.org hosts projects. The Apache Foundation hosts projects.
> > "Project", IOW, is *exactly* the word people use for these things, in the
> > larger world of software, and that's precisely why I chose it for my
> > original terminology proposal.
>But the things in PyPI are not projects. Projects have bug trackers,
>and mailing lists, and source code repositories.
And which of those things have to be hosted on the same site as the
project's index page? Freshmeat, for example, is not a project
*hosting* system, it's a project *index*. PyPI is in that sense, a
project index. Some index pages may link to all the stuff associated
with that project, some may not.
(i.e. the set of all possible project features is not equal to the
intersection of all projects' actual features: some project have
mailing lists and not bug trackers, and vice versa. This does not
make them non-projects.)
> Projects are organizations of people -- not software distributions.
I'm an organization of people; am I a project? No, the various
things I have listed on PyPI are my projects, and I distribute
releases of them.
>The things in PyPI that you call "projects" are things that get
>produced by projects. There isn't a buildout.recipe.egg
>"project". buildout.recipe.egg is just a um packaging of some software
>components. It's not a "project" in any usual sense of the word.
I don't get that. You work on it, and it is distinct from other
works. That makes it a project.
>No. End users need to know about this. They need to know what these
>names mean and that the "package name" (distutils) or "project name"
>(setuptools) doesn't imply that the distribution will provide a python
>package of the same name. Trust me on this. Users care about this.
Actually, I believe distutils calls it a "distribution name", but I
could be wrong about that. ;-)
> > For one thing, if the distutils documentation simply starts out like:
> > "If you want to distribute your work to the larger Python community, you
> > need to create a project for it. In practical terms, this means having a
> > directory with a setup.py and the code, data, or documentation you wish to
> > distribute. Your project will also need a unique name, if you want to make
> > it accessible to others via the Python Project Index (PyPI)." (replace
> > setup.py w/setup.cfg for distutils2, of course)
>It does? Where? Can you give a link? I don't see this text anywhere.
Of course not; it was a proposal for a hypothetical
introduction. That's why it says "if" up there. ;-)
> > This usage of project also maps onto common IDE usage of the term
> project --
> > a directory of stuff that you're going to edit and build.
>That use of project is equivalent to "working directory" and not
Huh? In an IDE, a project is a thing you build and distribute,
usually with source control. It's distinct from other projects, and
it has a name. It is usually not tied to a specific code unit such
as a module or package (regardless of what the code units of the
relevant programming language are called). It has additional
metadata, over and above the actual code units, and possibly includes
non-code resources such as documentation, data, images, etc.
IOW, it's *exactly* the sort of project we're talking about
here. So, the term project is consistent with both the IDE usage of
the word, *and* the mozdev/freshmeat/sourceforge et al meaning of project.
It is thus unlikely to be confusing or surprising in the least.
(Side question: were you *really* confused by the term project when
you first began working with setuptools? I don't remember you having
any issues with it at the time, but perhaps I've forgotten?)
The hard part of introducing the term *here*, on this mailing list,
is precisely the same part that is hard for your proposal: it is
usually happening at a point where people are *not* as open to
When somebody is on the list and we need to explain the
project/package distinction, it's noise to them because they're
trying to solve some other problem, and the distinction doesn't seem important.
At the point, however, where someone is reading the distutils docs
for the first time, or reading a "how to distribute your stuff"
tutorial, that is precisely the place where that distinction will be
perceived as valuable.
That is, they are asking, "what do I need to do to get my code out
there?" And the answer is, "make a project, register it, and upload
some files." This answer is sensible and satisfying, so the term
slips right in.
Arguably, you could call it a "fooblymuffin" at that same point of
introduction, and the "it's an answer to their question" argument
mostly still applies. But the pre-existing meaning of "project" from
both IDE usage and project-sites usage means that anyone who's
encountered the term in either of those uses will likely have an
immediate "aha" or "of course" reaction, thereby making the learning
and acceptance even easier.
Renaming package to module, on the other hand, has no similarly
obvious point of motivation to learn, except for people who are *not
yet python developers*... which means that it's going to take a
long, long time to get the terminology changed.
More information about the Distutils-SIG