PEP 8[2] deals with code style guide, including names of Python
packages and modules. It covers syntax of package/modules names.

PEP 345[3] deals with packaging metadata, and defines name argument
of the packaging.core.setup() function.

PEP 420[4] deals with namespace packages. It brings support of
namespace packages to Python core. Before, namespaces packages were
implemented by external libraries.

PEP 3108[5] deals with transition between Python 2.x and Python 3.x
applied to standard library: some modules to be deleted, some to be
renamed. It points out that naming conventions matter and is an
example of transition plan.

If your project is generic enough (i.e. it is not a contrib to another
product or framework), you can avoid namespace packages. 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[10] project belongs to the Sphinx development
team. There is no need to have some "sphinx" namespace package with
only one "sphinx.sphinx" project inside.

Distribute only one package (or only one module) per project, and use
package (or module) name as project name.

It avoids possible confusion between project name and distributed
package or module name.

It makes the name consistent.

It is explicit: when one sees project name, he guesses
package/module name, and vice versa.

It also limits implicit clashes between package/module names.
By using a single name, when you register a project name to PyPI[11],
you also perform a basic package/module name availability
verification.

Some distributions actually do.
As an example, setuptools[17] and distribute[18] 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.

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.

Don't define everything in deeply nested hierarchies: you will end up
with projects 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.

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.

So, if your project belongs to another project or to a community,
first look for specific conventions in main project's documentation.

If there is no specific conventions, follow the ones declared in this
document.

As an example, Plone community[26] releases community contributions in
the "collective" namespace package. It differs from the standard
namespace for contributions proposed here.
But since it is documented, there is no ambiguity and you should
follow this specific convention.

names where ${MAINPROJECT} doesn't appear are not explicit
enough, i.e. nobody can guess they are related to
${MAINPROJECT}. As an example, it is not obvious that
"collective.*" belongs to Plone community.

{$DIST}contrib.* looks like 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".

If many projects follow Renaming howto
recipe, then many legacy distributions will have the following
characteristics:

Development Status :: 7 - Inactive classifier.

latest version is empty, except packaging stuff.

lastest version "redirects" to another distribution. E.g. it has a
single dependency on the renamed project.

referenced as Obsoletes-Dist in a newer distribution.

So it will be possible to detect renamed projects 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.