[Distutils] Name the software! Package quality tester.

P.J. Eby 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
>relevant, IMO.

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 
learning something.

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 mailing list