Hi,
I am looking for a convention (i.e. kind of PEP) about package names: "how to choose a good package name". I couldn't find a PEP which gives guidelines about it.
PEP 8 gives some guidelines about "syntax" of package names. I found articles like "Rules of thumb" section of http://www.martinaspeli.net/articles/the-naming-of-things-package-names-and-.... But I was looking for something more "official". And thus, I was thinking of a PEP, or something similar.
Scope:
I'm not to write this guide here (I'm not an expert about it), but, if such a PEP or documentation doesn't exist, here are some considerations to start:
Here are quotes seen in a recent thread about PEP 420 (http://mail.python.org/pipermail/import-sig/2012-May/000631.html), which make me believe a convention would be useful. Notice that, in fact, I discovered PEP 420 while searching for a PEP about "how to choose a good namespace".
Le 13/05/2012 19:25, PJ Eby a écrit :
Regarding the nesting issue and persuading Django
developers to use
namespaces, I would note that there isn't any reason for namespaces to
be deeply nested in the first place. By convention, top-level
namespace packages should be the name of a project or its sponsoring
organization, which means there is rarely a need for deep nesting.
Even cases like zope.app and peak.util are rare: usually a project or
organization will have only one such "miscellaneous" namespace with
lots of separately-distibuted components.
(After all, the main reason to have a namespace package is to have separately-distributed subpackages. So, self-contained packages don't need to have namespaces of their own, almost by definition.)
Anyway, what I've noticed is that when people want to deeply nest namespaces, it's usually because they're trying to share a namespace across organizations, like making a shared 'net.' namespace. The idea of namespaces isn't for that kind of categorization, though, it's for ownership. If two developers are fighting over where to put something in a category hierarchy, it's a sign that they need to be working in different namespaces, with each developer staking a claim to a top-level package -- like OSAF's osaf., Zope Corporation's zc. (vs. the community project's zope.), and so on.
When developers use namespaces for project/ownership distinction, the resulting package hierarchies can be pretty much as flat as you like.
If I had to explain it to another Python developer, I wish I could give him an hyperlink and say "read and follow the convention".
Le 13/05/2012 20:56, "Martin v. Löwis" a écrit :
In Java, people apparently want that because they get these deeply nested directory hiearchies (org/apache/commons/betwixt/expression). It's apparently possible to condense this into org.apache.commons.betwixt/expression (which isn't a shorter string, but fewer cd commands / explorer clicks / .svn folders).
I predict that people will start using PEP 420 in the reversed-domain fashion also, so we eventually might end up wanting something like this for Python.
Could we anticipate namespace usage? At least for some "simple" things that already are de facto standards. As an example, I guess we could state about "reasonable maximum namespace depth", because on Pypi there is not many packages with more than 3 levels.
Regards, Benoit
On Sun, May 13, 2012 at 5:44 PM, Benoît Bryon benoit@marmelune.net wrote:
...
Le 13/05/2012 19:25, PJ Eby a écrit : >
Regarding the nesting issue and persuading Django developers to use namespaces, I would note that there isn't any reason for namespaces to be deeply nested in the first place. By convention, top-level namespace packages should be the name of a project or its sponsoring organization, which means there is rarely a need for deep nesting. Even cases like zope.app and peak.util are rare: usually a project or organization will have only one such "miscellaneous" namespace with lots of separately-distibuted components.
(After all, the main reason to have a namespace package is to have separately-distributed subpackages. So, self-contained packages don't need to have namespaces of their own, almost by definition.)
Anyway, what I've noticed is that when people want to deeply nest namespaces, it's usually because they're trying to share a namespace across organizations, like making a shared 'net.' namespace. The idea of namespaces isn't for that kind of categorization, though, it's forownership. If two developers are fighting over where to put something in a category hierarchy, it's a sign that they need to be working in different namespaces, with each developer staking a claim to a top-level package -- like OSAF's osaf., Zope Corporation's zc. (vs. the community project's zope.), and so on.
When developers use namespaces for project/ownership distinction, the resulting package hierarchies can be pretty much as flat as you like.
Well said. IMO, only one level of nesting is necessary. When I've used nested namespaces in the past, it was out of a compulsion to over-organize. :)
But:
Le 13/05/2012 20:56, "Martin v. Löwis" a écrit : >
In Java, people apparently want that because they get these deeply nested directory hiearchies (org/apache/commons/betwixt/expression). It's apparently possible to condense this into org.apache.commons.betwixt/expression (which isn't a shorter string, but fewer cd commands / explorer clicks / .svn folders).
I predict that people will start using PEP 420 in the reversed-domain fashion also, so we eventually might end up wanting something like this for Python.
If Python were more popular, I think we'd be more like Java in this regard.
When I create a package like zc.thread
it allows me to use a
package named thread
without being presumptuous and trying to
claim a top-level name like "thread". But "zc" is a little
presumptuous too. Might there someday be another organization who's
initials are "zc"?
Lately, I've gotten the impression that people are rejecting the use of namespace packages altogether. There's an incorrect notion that namespace packages are an invention of setuptools. I think this is unfortunate.
+1 for an official document (or addition to an existinhg document) providing a rational for namespace packages and their naming.
Jim
-- Jim Fulton http://www.linkedin.com/in/jimfulton Jerky is better than bacon! http://www.dublinstore.com/
Lately, I've gotten the impression that people are rejecting the use of namespace packages altogether. There's an incorrect notion that namespace packages are an invention of setuptools. I think this is unfortunate.
Indeed, it's unfortunate. It took me some time to discover that (presumably) the original idea was first formulated in
https://mail.zope.org/pipermail/zope3-dev/2002-December/004251.html
I'd be curious to know whether there is an even earlier (public) discussion of namespace packages.
Regards, Martin
Hello,
Le 14/05/2012 13:12, Jim Fulton a écrit :
+1 for an official document (or addition to an existinhg document) providing a rational for namespace packages and their naming.
I opened a ticket on CPython issue tracker: http://bugs.python.org/issue14899
Then started to work in a fork: https://bitbucket.org/benoitbryon/cpython/src/doc-package-names/Doc/packagin...
.. but it looks like a PEP. So, I followed PEP 1 and posted the proposal to python-list@python.org... where I've been told to post it to distutils-sig :) So, I'm back here with a proposal...
The document below is the same as current version of https://bitbucket.org/benoitbryon/cpython/src/doc-package-names/Doc/packagin....
Thanks to Martin Aspeli for his article. Thanks to early reviewers: Alexis Métaireau, Éric Bréhault, Jean-Philippe Camguilhem and Mathieu Leplâtre.
Benoit
###### #
Names in packaging: conventions and recipes
###### #
This document deals with:
It provides conventions and recipes for distribution authors.
Main use case is:
as a developer, I want to create a project in order to distribute a package. So I have to choose names. Which names are "good"?
The Zen of Python
_ says:
In the face of ambiguity, refuse the temptation to guess. There should be one-- and preferably only one --obvious way to do it.
So I need clear and official (i.e. obvious) guidelines or conventions that I can follow.
Here are conventions, guidelines and recipes.
Guidelines for existing projects are also given.
Terminology
First of all, let's make sure there is no confusion...
Distribution name Distribution name is used by packaging utilities:
setup script</packaging/setupscript>
, it is the value
passed as
name
to packaging.core.setup()
PyPI
_ if the package is registered on itpip
requirements filesit can be used in buildout
configuration files.
Distribution term is introduced in :doc:packaging
docs</packaging/index>
.
Egg name
It is the same concept as distribution name. Technically, the egg is not the
distribution. But they use the same name: it is declared as
packaging.core.setup()
name argument.
"Egg" term is the legacy counterpart to "distribution". It was used by distutils and setuptools. It becomes deprecated with the new packaging module.
This document focuses on distributions, not eggs.
Package and module names
Package and module names are used in Python code. It is the string used in
:ref:import statements<import>
.
Remember that, from a file system perspective, packages are directories and modules are files.
:ref:Python packaging allows distributions to distribute several packages
and/or modules<setupcfg-section-files>
.
Project name
Usually the name of the repository or folder in which distribution authors put
their code. It generally is the directory name of the "distribution root",
as defined in :ref:packaging-term
.
Namespace packages
It is common practice to use namespaces in package names. PEP 420
_ brings
this concept to core Python. When PEP 420 will be accepted, Python officially
supports namespace packages.
As an example, consider django-debug-toolbar
_:
django-debug-toolbar
is the distribution name. It is declared
in
setup.py file
<https://github.com/django-debug-toolbar/django-debug-toolbar/blob/599d76e41c5728c0e342d55250690b2694bd2aad/setup.py#L4>
_.
debug_toolbar
is the package name. It is what would appear in
Django's
INSTALLED_APPS setting or be used as import debug_toolbar
.
Technically, all those names can be different.
Rationale
PEP 8
_ deals with code style guide, including names of Python packages
and
modules. It covers syntax of package/modules names.
PEP 345
_ deals with packaging metadata, and defines distribution
name.
PEP 420
_ deals with namespace packages. It brings support of
namespace
packages to Python core. Before, namespaces packages were implemented by
external libraries.
PEP 3108
_ deals with transition between Python 2.x and Python 3.x
applied
to standard library: some modules to be deleted, some to be renamed.
Martin Aspeli's article about names
_. Some parts of this proposal are
quotes from this article.
The Hitchhiker's Guide to Packaging
_, which has an empty placeholder
for "naming specification".
and, of course, in development official packaging documentation
_.
Before Python version 3.3, there is no official guidelines to name projects,
distributions or packages/modules.
Current PEPs (see Relationship with other PEPs
_) are very open on this
topic.
Distribution authors have to follow their own intuition.
Several standards emerged from communities. As examples:
Plone
_ community uses "plone." namespace for official Plone
products, and
"collective." for community products. This is a convention explicitely
promoted by Plone community.
Martin Aspeli's article about names
_ is about conventions and usages in
Plone community.
.. note:: Is there an official document about these conventions? A PLIP?
most Django
_ applications from community use "django-*" pattern as
distribution name. This is a de facto standard.
many Pyramid
_ applications from community use "pyramid_*" pattern as
distribution name.
Thus, as PyPI
_ testifies, distribution names and package/module names are
really heterogeneous.
Here are points this document tries to resolve.
When distribution authors come to choose a name, they can't find an unique official guideline. In such a situation, "Now is better than never" wins over "Refuse temptation to guess". So distribution authors follow one of the conventions they discovered (usually the one from their community), or follow their own intuition.
As explained in terminology
_ above, project, distribution and package
names
can be assigned distinct values. That is a big source of confusion, especially
for Python developers who are not used to packaging.
As a direct consequence of ambiguity
_ and confusion
_, new
Python developers
spend too much time to understand Python projects/distributions/packages names:
they can't find obvious (i.e. official) naming conventions (or at least
guidelines) even if they search for it. They have to ask community to resolve
the ambiguity
_.
it's hard to resolve the confusion
_ between names. It's even harder
because
community itself is a bit confused. Their best chance is to find one of the
Other sources of inspiration
_ listed above or ask a well informed
person.
developers from some other languages suppose Python have official naming conventions for distributions and packages. So they search for it, and feel worried when they figure out that it doesn't exist.
Experienced Python users are less affected: they built their opinion in the past and keep on following their habits.
The global Python community is partitionned into opposed sub-communities:
most Python developers are linked to at least one community (i.e. Zope, Plone, Pyramid, Django...).
communities usually resolved naming conventions with official documents or with de facto usage.
developers usually follow their community's standards.
developers usually believe their community made the best choice. They usually adhere to community arguments.
choices and reasons differ from one community to another.
when Python communities meet, package names are a never-ending topic of discussion.
people discuss about package names when they should work together on more valuable stories.
they can't settle the issue, because:
arguments have historical reasons. In history, these reasons were enough.
accepting someone else's arguments means changing habits, and maybe re-packaging existing projects, i.e. efforts and time.
there is no guidelines from an higher authorithy (i.e. python.org). There is no comparison standard. Both choices are legitimate.
An additional note about developers who belong to several communities:
As The Zen of Python
_ says: "There should be one-- and preferably only
one
--obvious way to do it."
So the proposal is:
It's impossible to require a change for every existing project, for obvious reasons.
But it is possible to first document existing naming conventions, then promote a change.
This document proposes two things:
a status on current existing naming conventions, inside each project or
community. So that custom naming conventions are at least self-documented.
See Organize community contributions
_ for details.
a Transition plan
_ for those who are ready to migrate.
.. _packagenames-opportunity
:
As of Python 3.3 being developed:
many projects are not Python 3.x compatible. It includes "big" products or frameworks. It means that many projects will have to do a migration to support Python 3.x.
packaging (aka distutils2) is on the starting blocks. When it is released, projects will be invited to migrate and use new packaging.
PEP 420
_ brings official support of namespace packages to Python.
It means that most active projects should be about to migrate in the next year(s) to support Python 3.x, new packaging or new namespace packages.
Such an opportunity is unique and won't come again soon! So let's introduce and promote naming conventions as soon as possible (i.e. now).
Transition plan
In order of priority:
If the project belongs to a community (i.e. product/framework), and the community have official conventions, then follow community conventions.
.. note::
:ref:`Communities SHOULD organize contributions
<packagenames-organizecommunities>`.
As an example new community project related to Plone should be distributed as "collective.*", because it is an explicit standard of the Plone community.
New projects SHOULD follow Conventions
_ described in this
document.
There is no obligation for existing distributions to be renamed. The choice is left to distribution authors and mainteners for obvious reasons.
However, distribution authors are invited to promote migrations
_.
In order to rename an existing distribution, follow Renaming howto
_
guidelines below.
Every Python developer should migrate whenever possible, or promote the migrations in their respective communities.
Apply this convention on your projects, then the community will see it is safe.
In particular, "leaders" such as authors of popular projects are influential, they have power and, thus, responsability over communities.
Apply this conventions on popular projects, then communities will adopt the conventions too.
Popular projects SHOULD promote migrations when they release a new (major) version, particularly :ref:`if this version introduces support for Python 3.x, new standard library's packaging or namespace packages
<packagenames-opportunity>`.
.. note::
On the contrary, if popular projects refuse the conventions, communities
may not adopt the conventions.
If many projects follow Renaming howto
_, many legacy distributions will
have
the following characteristics:
Development Status :: 7 - Inactive
classifier.Obsoletes-Dist
in a newer distribution.So it will be possible to detect renamed distributions and improve readability on PyPI. So that users can focus on active distributions. But this feature is not required now. There is no urge. It won't be covered in this document.
Conventions
Rules that you SHOULD follow.
If you feel unsure after reading the following conventions, ask Python
community
_ on IRC or on a mailing list.
Distribute only one package (or only one module) in a distribution, and use package (or module) name as project name and distribution name.
It also limits implicit clashes between package/module names. By using a single name, when you register a name to PyPI, you also perform a basic package/module name availability verification.
As an example, pipeline
_, python-pipeline
_ and
django-pipeline
_ all
distribute a package or module called "pipeline". So installing two of them
leads to errors.
Yes:
Package name: "kheops.pyramid",
i.e. import kheops.pyramid
distribution name: "kheops.pyramid",
i.e. pip install kheops.pyramid
Project name: "kheops.pyramid",
i.e. git clone git@github.com/pharaohs/kheops.pyramid.git
No:
.. note::
For historical reasons, on `PyPI`_, you can find many distributions using
different values for project, distribution and package/module name.
Technically, Python distributions can provide multiple packages and/or modules.
See :ref:setup script reference<packaging-setup-script>
for
details.
Some distributions actually does.
As an example, setuptools
_ and distribute
_ are both declaring
"pkg_resources", "easy_install" and "site" modules in addition to respective
"setuptools" and "distribute" packages.
Consider this use case as exceptional. In most cases, you don't need this feature. So a distribution should provide only one package or module at a time.
A notable exception to the "Use a single name" rule is when you explicitely need distinct names.
As an example, the Pillow
_ distribution is an alternative to the original
PIL
_ distribution. They both provide a "PIL" package.
Consider this use case as exceptional. In most cases, you don't need this feature. So a distributed package name should be equal to distribution name.
PEP 8
_ applies to Python package and module names.
If you Use a single name
_, PEP 8
_ also applies to project and
distribution
names. The exceptions are namespace packages, where dots are required in the
name.
Ask yourself "how would I describe in one sentence what this name is for?", and then "could anyone have guessed that by looking at the name?".
When you are using namespaces, make sure each part is meaningful.
.. _packagenames-ownership
:
This helps avoid clashes between distribution names.
Ownership could be:
an individual.
Example: gp.fileupload
_ is owned and maintained by Gael Pasgrimaud.
an organization. Examples:
zest.releaser
_ is owned and maintained by Zest Software.Django
_ is owned and maintained by the Django Software Fundation.a group or community.
Example: sphinx
_ is maintained by developers of the Sphinx project, not
only by its author, Georg Brandl.
a group or community related to another package.
Example: collective.recaptcha
_ is owned by its author: David Glick,
Groundwire. But the "collective" namespace is owned by Plone community.
Understand the purpose of namespace before you use it.
DO NOT plug into a namespace you don't own, unless explicitely authorized.
If in doubt, ask
_.
As an example, DO NOT use "django.contrib" namespace: it is managed by Django's core contributors.
Exceptions CAN be defined by distribution authors. See Organize community
contributions
_ below.
... because private distributions are owned by somebody. So apply the
:ref:ownership rule<packagenames-ownership>
.
For internal/customer projects, use your company name as the namespace.
This rule applies to closed-source distributions.
As an example, if you are creating a "climbing" distribution for the "Python Sport" company: use "pythonsport.climbing" name, even if it is closed source.
... because they are owned by individuals. So apply the :ref:`ownership rule
<packagenames-ownership>`.
There is no shame in releasing a distribution as open source even if it has an "internal" name.
If the project comes to a point where the author wants to change ownership
(i.e. the project no longer belongs to an individual), keep in mind :ref:it is
easy to rename the project<packagenames-rename>
.
If your project is generic enough (i.e. it is not a contrib to another product or framework), you CAN avoid namespaces. The base condition is generally that your project is owned by a group (i.e. the development team) which is dedicated to this project.
Only use a "shared" namespace if you really intend the code to be community owned.
As an example, sphinx
_ project belongs to the Sphinx development
team.
If your project is not mature or hasn't been proven useful to a community, best choice is to use an individual or organization namespace.
It allows distribution authors to release projects early.
And it doesn't block future changes. When a project becomes mature, and if it
appears there is no reason to keep individual ownership, :ref:it remains
possible to rename the project<packagenames-rename>
.
The Zen of Python
_ says:
Flat is better than nested.
Don't define everything in deeply nested hierarchies: you will end up with distributions and packages like "pythonsport.common.maps.forest". This type of name is both verbose and cumbersome (e.g. if you have many imports from the package). Furthermore, big hierarchies tend to break down over time as the boundaries between different packages blur.
The consensus is that two levels of nesting are preferred.
Yes: "pyranha"
Yes: "pythonsport.climbing"
Yes: "pythonsport.forestmap"
No: "pythonsport.maps.forest"
.. _packagenames-othermetadata
:
Consider distribution names (with or without namespaces) as unique identifiers on PyPI. It is important that these identifiers remain human-readable. It is even better when these identifiers are meaningful. But their primary purpose is not to classify or describe distributions.
As examples, if you only look at the name:
The examples above are not problematic.
Classifiers
_ and keywords metadata are made for categorization of
distributions.
As an example, there is a "Framework :: TurboGears" classifier. Even if names are quite heterogeneous (they don't follow a pattern like collective.* for Plone community projects), we get the list.
In order to Organize community contributions
_, conventions about names
and
namespaces matter, but conventions about metadata should be even more
important.
As an example, we can find Plone portlets in many places:
Even if Plone community has conventions, using the name to categorize distributions is inapropriate. It's impossible to get the full list of distributions that provide portlets for Plone by filtering on names. But it would be possible if all these distributions used "Framework :: Plone" classifier and "portlet" keyword.
For example, we have plone.principalsource
instead of
plone.source.principal
or something like that. The name is shorter, the
package structure is simpler, and there would be very little to gain from
having three levels of nesting here. It would be impractical to try to put all
"core Plone" sources (a source is kind of vocabulary) into the
plone.source.*
namespace, in part because some sources are part of other
packages, and in part because sources already exist in other places. Had we
made a new namespace, it would be inconsistently used from the start.
3 levels are also tempting when:
In such a case, you'd better use the most restrictive ownership level as first level.
As an example, where "collective" is a major community namespace that "gergovie" belongs to, and "vercingetorix" it the name of "gergovie" author:
No: "collective.vercingetorix.gergovie"
Yes: "vercingetorix.collectivegergovie"
Even if not recommended, 3 levels are supported. This is mainly for historical
reasons: 3 levels can be accepted where top level namespace owner explicitely
allows it with a specific convention. See Organize community contributions
_
for details.
.. note::
Even communities where namespaces are standard don't use more than 3 levels.
.. _packagenames-organizecommunities
:
Actions:
Choose a naming convention for community contributions.
If it is not :ref:the default<packagenames-contribnamespace>
,
document it.
if you use the :ref:default
convention<packagenames-contribnamespace>
,
this document should be enough. Don't reapeat it. You MAY reference it.
else, tell users about custom conventions in project's "contribute" or "create modules" documentation.
Also recommend the use of additional metadata, such as :ref:classifiers and
keywords<packagenames-othermetadata>
.
About convention choices:
New projects SHOULD choose the default scheme.
Existing projects with community contributions CAN start with custom
conventions. Then they SHOULD Promote migrations
_.
It means that existing community conventions doesn't need to be changed. But they need to be explicitely documented: first state about current naming conventions, then about future.
Example: "pyranha" is your project name, distribution name and package name. Tell contributors that:
pyranha-related distributions should use the "pyranha" keyword
pyranha distributions providing templates should also use "templates" keyword.
community contributions should be released under "pyranhacontrib" namespace (i.e. use "pyranhacontrib.*" pattern):
.. _packagenames-contribnamespace
:
The idea is to use a standard pattern to store community contributions for any product or framework.
It is the simplest way to Organize community contributions
_: the obvious
way
to go is "${DIST}contrib", no ambiguity.
As an example:
.. note::
Why ``${DIST}contrib.*`` pattern?
* ``${DIST}c.*`` is not explicit enough. As examples, "zc" belongs to
"Zope Corporation" whereas "z3c" belongs to "Zope 3 community".
* ``${DIST}community`` is too long.
* ``${DIST}community`` conflicts with existing namespaces such as
"iccommunity" or "PyCommunity".
* ``${DIST}.contrib`` is inside ${DIST} namespace, i.e. it is owned by
${DIST} authors. It breaks the `Top level namespace relates to code
ownership`_.
* ``${DIST}.contrib.*`` breaks the `Avoid deep nesting`_ rule.
* names where ``${DIST}`` doesn't appear are not explicit enough, i.e.
nobody can guess they are related to ``${DIST}``.
* ``{$DIST}contrib.*`` may conflict with existing ``sphinxcontrib-*``
packages. But ``sphinxcontrib-*`` is actually about Sphinx contrib, so
this is not a real conflict... In fact, the "contrib" suffix was inspired
by "sphinxcontrib".
Recipes
Before you choose a distribution name, make sure it hasn't already been registered in the following locations:
PyPI
_Popular code repositories such as:
Github
_Bitbucket
_Gitorious
_djangopackages.com
_
.. note:: A web service would be welcome for this!
Also make sure the package name hasn't already been registered:
Python Standard Library
_,.. _packagenames-rename
:
Renaming a project is possible, but keep in mind that it will cause some confusions. So, pay particular attention to README and documentation, so that users understand what happened.
# . First of all, do not remove legacy distribution from PyPI. Because some
users may be using it.
# . Copy the legacy project, then change names (project, distribution and
package/module). Pay attention to, at least:
* packaging files,
* folder name that contains source files,
* documentation, including README,
* import statements in code.
# . Assign Obsoletes-Dist
metadata to new distribution in setup.cfg
file.
See `PEP 345 about Obsolete-Dist`_ and :ref:`setup.cfg specification
<setupcfg-spec>`.
# . Release the renamed distribution as a new version, then publish it.
# . Edit legacy distribution:
* add dependency to new distribution,
* drop everything except packaging stuff,
* add the ``Development Status :: 7 - Inactive`` classifier in setup script,
* publish a new release.
So, users of the legacy package:
Users who discover the legacy distribution see it is inactive.
References
.. target-notes::
.. _Martin Aspeli's article about names
:
http://www.martinaspeli.net/articles/the-naming-of-things-package-names-and-...
.. _PEP 1
: http://www.python.org/dev/peps/pep-0001/
.. _The Zen of Python
: http://www.python.org/dev/peps/pep-0020/
.. _PEP 8
: http://www.python.org/dev/peps/pep-0008/#package-and-module-names
.. _PEP 345
: http://www.python.org/dev/peps/pep-0345/
.. _PEP 420
: http://www.python.org/dev/peps/pep-0420/
.. _PEP 3108
: http://www.python.org/dev/peps/pep-3108
.. _The Hitchhiker's Guide to Packaging
:
http://guide.python-distribute.org/specification.html#naming-specification
.. _in development official packaging documentation
:
http://docs.python.org/dev/packaging/
.. _plone
: http://plone.org/community/develop
.. _django
: http://djangoproject.com/
.. _pyramid
: http://pylonsproject.org
.. _pypi
: http://pypi.python.org
.. _django-debug-toolbar
:
https://github.com/django-debug-toolbar/django-debug-toolbar
.. _gp.fileupload
: http://pypi.python.org/pypi/gp.fileupload/
.. _zest.releaser
: http://pypi.python.org/pypi/zest.releaser/
.. _sphinx
: http://sphinx.pocoo.org
.. _Classifiers
: http://pypi.python.org/pypi?:action=list_classifiers
.. _collective.recaptcha
: http://pypi.python.org/pypi/collective.recaptcha/
.. _Python community
: http://www.python.org/community/
.. _pipeline
: http://pypi.python.org/pypi/pipeline/
.. _python-pipeline
: http://pypi.python.org/pypi/python-pipeline/
.. _django-pipeline
: http://pypi.python.org/pypi/django-pipeline/
.. _setuptools
: http://pypi.python.org/pypi/setuptools
.. _distribute
: http://packages.python.org/distribute/
.. _Pillow
: http://pypi.python.org/pypi/Pillow/
.. _PIL
: http://pypi.python.org/pypi/PIL/
.. _Python Standard Library
: http://docs.python.org/library/index.html
.. _github
: https://github.com
.. _bitbucket
: https://bitbucket.org
.. _gitorious
: https://gitorious.org/
.. _djangopackages.com
: http://djangopackages.com
.. _PEP 345 about Obsolete-Dist
:
http://www.python.org/dev/peps/pep-0345/#obsoletes-dist-multiple-use
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:
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.
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.
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.
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".
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.
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.
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 Informational-track PEP.
Hi,
Updated https://bitbucket.org/benoitbryon/cpython/src/doc-package-names/Doc/packagin...
Le 31/05/2012 18:00, PJ Eby a écrit :
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.
If it actually becomes a draft PEP, I guess we should:
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:
Removed the text about eggs.
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.
Changed "Terminology section".
However, I am still confusing "project name" and "distribution name". From your comment, I understand that name argument of packaging.core.setup() is the name of the project, which is used to get names of the distributions like "%(project_name)s-%(version)s.tar.gz". But PEP 345 says it is the name of the distributions : http://www.python.org/dev/peps/pep-0345/#name
Also, I propose to shorten or move the "terminology" section in another document (another pep or in packaging documentation):
Changed the "Rationale" section:
The "proposal" part of "Rationale" section has been removed.
There is no reason why every package should use your approach,and some developers will be opposed to your conventions.
"Rationale" section used to point out that current (missing) naming rules lead to problems, such as duplicate packages/modules or inconsistent project/package names. Shouldn't we consider them as issues?
But, whatever the value of those arguments, I understand some developers will be opposed to proposed conventions.
That's why I tried to make the document tell:
Since the document is a bit directive, the ideas above appear in reversed order: first you should apply the convention, but at last you do what you want to. Is it clear in the document?
Let's consider the "django-pipeline" VS "pipeline" VS "python-pipeline" example:
Notice that Django community could state that "there is no valuable issue, i.e. wontfix". But this would mean that this choice is documented in an issue, discussion or in the documentation... so it would fit the guidelines as an explicit community-specific convention.
(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".
The "proposal" section has been removed as part of the "Rationale" one. Were you talking about the "Transition plan" instead?
I moved the "transition plan" section at the end of the document, i.e. conventions appear before. In fact, I changed the "transition plan" into a set of recipes for existing projects.
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.
I updated the conventions:
I agree that choosing a "good" name is not easy. I suppose that the best we can do is to provide guidelines such as "ownership", "memorable" or "meaningful"... so that users can avoid some common pitfalls.
Then, it's a matter of priorities. I would say that:
first, we should avoid duplicates (project and packages). That's why "top-level namespace for ownership" and "use a single name" seem so important to me.
then, it's better if the project name is memorable and meaningful and easy to discover... but it's a less important issue than duplicates, mainly because other metadata such as description, keywords and classifiers can help.
Removed "support" vocabulary. Changed "conventions" to "guidelines". Used only lowercase "may", "should" and "can".
Added "Register names to PyPI" guideline. Changed the "check for name availability" recipe: PyPI is the only place.
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 Informational-track PEP.
Does it sounds better now?
Regards, Benoit
Also, I propose to shorten or move the "terminology" section in another document (another pep or in packaging documentation):
+1
There is no reason why every package should use your approach,and some developers will be opposed to your conventions.
"Rationale" section used to point out that current (missing) naming rules lead to problems, such as duplicate packages/modules or inconsistent project/package names. Shouldn't we consider them as issues?
But, whatever the value of those arguments, I understand some developers will be opposed to proposed conventions. That's conventions, not rules. PEP8 for instance, says that the rules are made to be changed in case there really is a need to, for your project. Having conventions is not about making everyone agree, but about having everyone using the same methods to avoid confusion IMO. Maybe should we state this clearly.
Alexis
Hi,
Le 06/06/2012 10:52, Benoît Bryon a écrit :
Le 31/05/2012 18:00, PJ Eby a écrit :
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.
If it actually becomes a draft PEP, I guess we should:
Updated https://bitbucket.org/benoitbryon/cpython/src/doc-package-names/Doc/packagin... Prepared migration to a PEP. I am to submit the document for review at peps@python.org. Feedback is welcome!
Le 06/06/2012 10:52, Benoît Bryon a écrit :
Also, I propose to shorten or move the "terminology" section in another document (another pep or in packaging documentation):
Moved terminology section to packaging/introduction.rst. See https://bitbucket.org/benoitbryon/cpython/changeset/5eca478e6804#chg-Doc/pac...
Benoit
Hello,
The proposal has been posted to peps@python.org : http://hg.python.org/peps/file/52767ab7e140/pep-0423.txt
I am about to post it to python-dev@python.org for discussion and review.
In order to complete the move, I plan to replace the document by references to PEP 423 in packaging section of cpython documentation. See also http://bugs.python.org/issue14899
Benoit
Le 19/06/2012 23:49, Benoît Bryon a écrit :
Hi,
Le 06/06/2012 10:52, Benoît Bryon a écrit :
Le 31/05/2012 18:00, PJ Eby a écrit :
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.
If it actually becomes a draft PEP, I guess we should:
Updated https://bitbucket.org/benoitbryon/cpython/src/doc-package-names/Doc/packagin... Prepared migration to a PEP. I am to submit the document for review at peps@python.org. Feedback is welcome!
Le 06/06/2012 10:52, Benoît Bryon a écrit :
Also, I propose to shorten or move the "terminology" section in another document (another pep or in packaging documentation):
Moved terminology section to packaging/introduction.rst. See https://bitbucket.org/benoitbryon/cpython/changeset/5eca478e6804#chg-Doc/pac...
Benoit
Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
[Benoît Bryon, 2012-06-27]
I think PEP 386 (about versions) should be mentioned in "Relationship with other PEPs" section.
About "Use a single name" section: sometimes one needs to add "python-"
or "py" prefix to project name (f.e. if the name is already used in
other programming languages and you cannot register it in your favourite
forge hosting service)... but please don't add the prefix also in namespace.
All these PyQts, pyudevs, pygames and pyopencls sound stupid to me (isn't
it obvious that when I do import foo
in Python, "foo" is a Python
library?)
About ".contrib.": flask uses flask.ext.foo (namespace) and Flask-Foo (project name) schema for Flask extensions - maybe it's worth mentioning
Piotr Ożarowski Debian GNU/Linux Developer www.ozarowski.pl www.griffith.cc www.debian.org GPG Fingerprint: 1D2F A898 58DA AF62 1786 2DF7 AEF6 F1A2 A745 7645
Le 28/06/2012 14:15, Piotr Ozarowski a écrit :
[Benoît Bryon, 2012-06-27]
http://hg.python.org/peps/file/52767ab7e140/pep-0423.txt I think PEP 386 (about versions) should be mentioned in "Relationship with other PEPs" section.
Why? Right now, I can't see the relationship between projects/packages/modules names and versions.
About "Use a single name" section: sometimes one
needs to add "python-"
or "py" prefix to project name (f.e. if the name is already used in
other programming languages and you cannot register it in your favourite
forge hosting service)... but please don't add the prefix also in namespace.
All these PyQts, pyudevs, pygames and pyopencls sound stupid to me (isn't
it obvious that when I do import foo
in Python, "foo" is a Python
library?)
Do you mean:
Currently, if the project name is "pyqt", then the PEP proposal recommends "pip install pyqt" and "import pyqt", to make the name consistent. If one is not a good choice, change both. It is convention over configuration.
IMHO, a "py" prefix for package name would not be a problem in this case. You are not importing Qt itself, but Python bindings for Qt.
I mean, yes, it is obvious that when I do import foo
in
Python, then "foo" is a Python library. But would the
reverse assertion be that if I see "import qt" in Python
code, then it is obvious that Qt itself is a Python library?
The name could have been "qtbindings", would have it been a problem then? The "py" prefix has the advantage to be clear: that's Python bindings for Qt. And it's a really short prefix.
About ".contrib.": flask uses flask.ext.foo (namespace) and Flask-Foo (project name) schema for Flask extensions - maybe it's worth mentioning in this PEP as well. Maybe it will be used in discussions or in examples, but I suppose the PEP is not the place to list all project-specific conventions. Currently the draft PEP tells: "search for specific conventions in main project (Flask) documentation".
Benoit
[Benoît Bryon, 2012-06-29]
Le 28/06/2012 14:15, Piotr Ozarowski a écrit :
[Benoît Bryon, 2012-06-27]
http://hg.python.org/peps/file/52767ab7e140/pep-0423.txt I think PEP 386 (about versions) should be mentioned in "Relationship with other PEPs" section.
Why? Right now, I can't see the relationship between projects/packages/modules names and versions.
The PEP name is "Naming conventions and recipes related to packaging" and version numbers are related to packaging (and naming) for sure.
How about PEP 396 (Module Version Numbers)?
About "Use a
single name" section: sometimes one needs to add "python-"
or "py" prefix to project name (f.e. if the name is already used in
other programming languages and you cannot register it in your favourite
forge hosting service)... but please don't add the prefix also in namespace.
All these PyQts, pyudevs, pygames and pyopencls sound stupid to me (isn't
it obvious that when I do import foo
in Python, "foo" is a Python
library?)
Do you mean:
right
Currently, if the project name is "pyqt", then the PEP proposal recommends "pip install pyqt" and "import pyqt", to make the name consistent. If one is not a good choice, change both. It is convention over configuration.
that's my point, PyQt guys cannot use Qt as project name, but "qt" it a better name for this namespace, IMO
IMHO, a "py" prefix for package name would not be a problem in this case. You are not importing Qt itself, but Python bindings for Qt.
it's not "a problem", I just think PEP should not recommend such prefixes
I mean, yes, it is obvious that when I do
import foo
in
Python, then "foo" is a Python library. But would the
reverse assertion be that if I see "import qt" in Python
code, then it is obvious that Qt itself is a Python library?
There's a "readline" package in Python's stdlib, does it imply readline is something Python related or specific?
The name could have been "qtbindings", would have it been a problem then? The "py" prefix has the advantage to be clear: that's Python bindings for Qt. And it's a really short prefix.
qtbindings, qtlib or other similar prefixes/suffixes should not be recommended, IMHO
About ".contrib.": flask uses flask.ext.foo (namespace) and Flask-Foo (project name) schema for Flask extensions - maybe it's worth mentioning in this PEP as well. Maybe it will be used in discussions or in examples, but I suppose the PEP is not the place to list all project-specific conventions. Currently the draft PEP tells: "search for specific conventions in main project (Flask) documentation".
I just thought "foo.ext.bar" is a nice convention worth mentioning
Piotr Ożarowski Debian GNU/Linux Developer www.ozarowski.pl www.griffith.cc www.debian.org GPG Fingerprint: 1D2F A898 58DA AF62 1786 2DF7 AEF6 F1A2 A745 7645
Le 29/06/2012 12:50, Piotr Ozarowski a écrit :
[Benoît Bryon, 2012-06-29]
Le 28/06/2012 14:15, Piotr Ozarowski a écrit :
[Benoît Bryon, 2012-06-27]
http://hg.python.org/peps/file/52767ab7e140/pep-0423.txt I think PEP 386 (about versions) should be mentioned in "Relationship with other PEPs" section. Why? Right now, I can't see the relationship between projects/packages/modules names and versions. The PEP name is "Naming conventions and recipes related to packaging" and version numbers are related to packaging (and naming) for sure. Ok. Maybe the title of the PEP is not clear. It is related to naming conventions only, and only in packaging (i.e. projects, and distributed packages or modules, not variables, function or class names).
Would "naming conventions related to packaging" be better?
How about PEP 396 (Module Version Numbers)? How are version numbers related to naming?
About
"Use a single name" section: sometimes one needs to add "python-"
or "py" prefix to project name (f.e. if the name is already used in
other programming languages and you cannot register it in your favourite
forge hosting service)... but please don't add the prefix also in namespace.
All these PyQts, pyudevs, pygames and pyopencls sound stupid to me (isn't
it obvious that when I do import foo
in Python, "foo" is a Python
library?)
Do you mean:
Currently, if the project name is "pyqt", then the PEP proposal recommends "pip install pyqt" and "import pyqt", to make the name consistent. If one is not a good choice, change both. It is convention over configuration. that's my point, PyQt guys cannot use Qt as project name, but "qt" it a better name for this namespace, IMO
IMHO, a "py" prefix for package name would not be a problem in this case. You are not importing Qt itself, but Python bindings for Qt. it's not "a problem", I just think PEP should not recommend such prefixes
By now, I feel that the "py" prefix use case is not special enough to reconsider or break the "use a single name" rule. I would accept to "import pyqt" instead of "import qt". But that's my own viewpoint. I understand you don't subscribe to it.
May someone else enter the discussion and give his opinion about this point?
I mean, yes,
it is obvious that when I do import foo
in
Python, then "foo" is a Python library. But would the
reverse assertion be that if I see "import qt" in Python
code, then it is obvious that Qt itself is a Python library?
There's a "readline" package in Python's stdlib, does it imply readline
is something Python related or specific?
You are right. My bad :)
The name could have been "qtbindings", would have it been a problem then? The "py" prefix has the advantage to be clear: that's Python bindings for Qt. And it's a really short prefix. qtbindings, qtlib or other similar prefixes/suffixes should not be recommended, IMHO
About ".contrib.": flask uses flask.ext.foo (namespace) and Flask-Foo (project name) schema for Flask extensions - maybe it's worth mentioning in this PEP as well. Maybe it will be used in discussions or in examples, but I suppose the PEP is not the place to list all project-specific conventions. Currently the draft PEP tells: "search for specific conventions in main project (Flask) documentation". I just thought "foo.ext.bar" is a nice convention worth mentioning (next to, not instead of "contrib" which is more general than "ext")
I agree that "foo.ext.bar" seems nice... but it uses 3 namespace levels. It breaks the "avoid deep nesting" rule, which recommends not more than two levels. So the PEP can't recommend this pattern, or we will also have to reconsider the "avoid deep nesting" rule.
Notice that, from current feedback about the PEP, I understand that the "avoid deep nesting" rule sounds more valuable than the "standard pattern for contributions".
About naming pattern for contribs, the draft PEP proposes:
if there is a need to separate "extensions" from "contributions" (supposing the difference is clearly documented), the project can tell his users to:
That said, in that particular case, I would publish everything related to foo (except foo itself) in the same namespace (i.e. only foocontrib.*) and use metadata to categorize projects. As an example, with something like keywords="foo extension". So that:
there is only one namespace package
everything that is "related to foo" is under foocontrib.*
if the "contribution" VS "extension" terminology change, there is no need to move projects from one namespace to another.
a project can be both an extension and a contribution.
it's possible to filter the list of packages at PyPI to get the list of extensions: name starts with "foocontrib." and has keyword "extension".
Benoit
May package names contain hyphen (-)?
On 29 June 2012 15:34, Daniel Holth dholth@gmail.com wrote:
May package names contain hyphen (-)?
Package or distribution? Package, no because it has to be a valid Python identifier. Distribution, I'm not sure - there are funny rules to allow for things like parsing dist-info directory names, or egg filenames, unambiguously. One of the packaging PEPs would probably answer this one.
Paul.
Le 29/06/2012 18:01, Paul Moore a écrit :
On 29 June 2012 15:34, Daniel Holthdholth@gmail.com wrote:
May package names contain hyphen (-)? Package or distribution? Package, no because it has to be a valid Python identifier. Distribution, I'm not sure - there are funny rules to allow for things like parsing dist-info directory names, or egg filenames, unambiguously. One of the packaging PEPs would probably answer this one.
Paul.
In package/module names, as Paul said, you can't use hyphens.
About project names, currently, the draft PEP recommends using the same value for distributed module/package name and for project name. The consequence is: PEP 8 applies to project names too, which means "no hyphens" in project names (and many other rules). The exception is the dot symbol, required to create namespace packages.
Benoit
[Benoît Bryon, 2012-06-29]
Le 29/06/2012 12:50, Piotr Ozarowski a écrit :
[Benoît Bryon, 2012-06-29]
Le 28/06/2012 14:15, Piotr Ozarowski a écrit :
[Benoît Bryon, 2012-06-27]
http://hg.python.org/peps/file/52767ab7e140/pep-0423.txt I think PEP 386 (about versions) should be mentioned in "Relationship with other PEPs" section. Why? Right now, I can't see the relationship between projects/packages/modules names and versions. The PEP name is "Naming conventions and recipes related to packaging" and version numbers are related to packaging (and naming) for sure. Ok. Maybe the title of the PEP is not clear. It is related to naming conventions only, and only in packaging (i.e. projects, and distributed packages or modules, not variables, function or class names).
Would "naming conventions related to packaging" be better?
How about PEP 396 (Module Version Numbers)? How are version numbers related to naming?
OK, I admit I shamelessly wanted to promote these two PEPs in as many places as possible ;-) "The great thing about standards is that there are so many to choose from." and there are way too many Python versioning conventions (and places where these versions are stored)
I just thought "foo.ext.bar" is a nice convention worth mentioning (next to, not instead of "contrib" which is more general than "ext")
I agree that "foo.ext.bar" seems nice... but it uses 3 namespace levels. It breaks the "avoid deep nesting"
nevermind then, it was just a suggestion. I feel strongly against the py/python/lib/bindings/etc. prefix/suffix issue, though (but will not
Piotr Ożarowski Debian GNU/Linux Developer www.ozarowski.pl www.griffith.cc www.debian.org GPG Fingerprint: 1D2F A898 58DA AF62 1786 2DF7 AEF6 F1A2 A745 7645
On 29 June 2012 14:05, Benoît Bryon benoit@marmelune.net wrote:
I agree that "foo.ext.bar" seems nice... but it uses 3 namespace levels. It breaks the "avoid deep nesting" rule, which recommends not more than two levels. So the PEP can't recommend this pattern, or we will also have to reconsider the "avoid deep nesting" rule.
??? I thought the PEP was about distribution naming (i.e., things published on PyPI. If the package "foo" is published under that name on PyPI, I see no reason it can't (good taste permitting) use multi-level names like foo.bar.baz internally. That's a completely different question than whether a distribution named foo.bar.baz should be available for download from PyPI (presumably alongside foo.bar.bip and foo.bop.boop...)
Maybe I'm misunderstanding the conversation here. We need to be extremely precise about the differences between distributions (things published to somewhere like PyPI, which can be installed independently, and have a version number, etc) and packages (which are things you import in Python). I've been just as vague as everyone else in this thread, so I'm not trying to blame anyone. But things are definitely getting muddled.
Paul.
Le 29/06/2012 17:59, Paul Moore a écrit :
On 29 June 2012 14:05, Benoît Bryonbenoit@marmelune.net wrote:
I agree that "foo.ext.bar" seems nice... but it uses 3 namespace levels. It breaks the "avoid deep nesting" rule, which recommends not more than two levels. So the PEP can't recommend this pattern, or we will also have to reconsider the "avoid deep nesting" rule. ??? I thought the PEP was about distribution naming (i.e., things published on PyPI.
It is about naming, limited to packaging, but not limited to things published on PyPI.
If the package "foo" is published under that name on PyPI, I see no reason it can't (good taste permitting) use multi-level names like foo.bar.baz internally. That's a completely different question than whether a distribution named foo.bar.baz should be available for download from PyPI (presumably alongside foo.bar.bip and foo.bop.boop...)
I understood the foo.ext.bar example as:
If foo is a project without namespace packages, then, yes, the PEP proposal doesn't cover its internal code organization.
Maybe I'm misunderstanding the conversation here. We need to be extremely precise about the differences between distributions (things published to somewhere like PyPI, which can be installed independently, and have a version number, etc) and packages (which are things you import in Python). I've been just as vague as everyone else in this thread, so I'm not trying to blame anyone. But things are definitely getting muddled.
The terminology reference used in the PEP proposal is https://bitbucket.org/benoitbryon/cpython/src/doc-package-names/Doc/packagin... (which is http://docs.python.org/dev/packaging/introduction.html + some changes related to the PEP proposal).
The PEP proposal deals with :
Benoit