[Distutils] conventions or best practice to choose package names?
pje at telecommunity.com
Thu May 31 18:00:03 CEST 2012
You've definitely put in a lot of work on this, and most of the actual
guidelines in your PEP are quite good. I think there's a core part of this
that can and should be a good Informational-track PEP.
However, I do have a few comments regarding overall organization, and some
regarding some of the specific recommendations and tone.
In order of appearance in the PEP, they are:
1. I would strongly suggest striking the aside on eggs entirely -- there's
no point to bringing it up just to dismiss it, and there never was such a
thing as an "egg name" - eggs are just another kind of distribution, so
they don't need a special term.
2. A project name isn't the name of a directory, it's the name of the thing
you release distributions of. E.g., my "Importing" project on PyPI (
http://pypi.python.org/pypi/Importing), which has the following names:
a) Project name = Importing
b) Release = 1.10
c) Distribution = Importing-1.10.zip
d) Module = peak.util.imports
Following this conceptual breakdown will make the naming recommendations
easier to follow.
3. The rationale is unnecessary and could (and *should*) be cut entirely.
Use PEP 8 as a model - it doesn't waste time explaining why coding
guidelines are a good idea. The truth is, your PEP would be massively
improved simply by deleting this entire section and not even trying to
replace it with anything.
4. The proposal section is also unnecessary, and likely to produce
resistance in any event. There is no reason why every package should use
your approach, and some developers will be opposed to your conventions. (I
disagree with some of them myself, for that matter, as I will discuss
below.) Some of the material from this section might make a good later
section on "How to apply these guidelines to your project".
5. The actual guidelines are pretty good, as I said. In particular, I like
pretty much every thing you say about package names. I disagree with some
of your assertions regarding project names, however. It's true that a
project name doesn't need to spell out what a project does (as with Celery,
Nose, etc.), but it does in fact hurt discovery and use when people use
package-based project names. It's a continuing source of frustration, for
example, that buildout recipe projects have names like z3c.recipe.scripts
and other names that I can't ever remember, and am forced to re-google or
dig up previous buildout files to find the magic names to include in my
buildouts. To me, the important thing about a project name is that it be
*memorable*, and that argues against using namespaced package names as
project names for contributions to a larger project, such as Plone
portlets, Buildout recipes, etc.
This isn't a huge point of contention for me, I just want to point out that
the good naming choices for projects are more complicated than "just use
the package name and let people search for it". I think there are some
other points you made that are a little too cut-and-dried in the same way,
but this is the only really big one.
6. Drop the language about how things are supported or not supported. This
just isn't true: Python the language supports you nesting things 6 layers
deep if you feel like it, and AFAIK there are no plans to change that, nor
should there be. Stick to talking here about what is or isn't a good idea,
not what's supported or not supported. That's just FUD.
7. PyPI should be the only place people have to check for a registered
distribution name; authors of projects that are hosted elsewhere can and
should use "setup.py register" to claim the name, or log on and do it.
Anyway, as I said, I think you've got some really good stuff here, but
it's got a lot of other stuff hiding it. Cut away the extras (and the
parts implying these guidelines are mandatory) and you've got a good
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Distutils-SIG