This document deals with:
It provides guidelines and recipes for distribution authors:
Further consideration of this PEP has been deferred at least until after PEP 426 (package metadata 2.0) and related updates have been resolved.
Reference is packaging terminology in Python documentation.
Here is a summarized list of guidelines you should follow to choose names:
If you feel unsure after reading this document, ask Python community on IRC or on a mailing list.
This helps avoid clashes between project names.
Ownership could be:
Understand the purpose of namespace before you use it.
Don’t plug into a namespace you don’t own, unless explicitly authorized.
As an example, don’t plug in “django.contrib” namespace because it is managed by Django’s core contributors.
Exceptions can be defined by project authors. See Organize community contributions below.
Also, this rule applies to non-Python projects.
As an example, don’t use “apache” as top-level namespace: “Apache” is the name of an existing project (in the case of “Apache”, it is also a trademark).
… because private projects are owned by somebody. So apply the ownership rule.
For internal/customer projects, use your company name as the namespace.
This rule applies to closed-source projects.
As an example, if you are creating a “climbing” project for the “Python Sport” company: use “pythonsport.climbing” name, even if it is closed source.
… because they are owned by individuals. So apply the ownership rule.
There is no shame in releasing a project as open source even if it has an “internal” or “individual” 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 it is easy to rename the project.
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 project belongs to the Sphinx development team. There is no need to have some “sphinx” namespace package with only one “sphinx.sphinx” project inside.
If your project is really experimental, best choice is to use an individual or organization namespace:
Distribute only one package (or only one module) per project, and use package (or module) name as project name.
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. This issue wouldn’t have occurred if these distributions used a single name.
Yes:
No:
Note
For historical reasons, PyPI contains many distributions where project and distributed package/module names differ.
Technically, Python distributions can provide multiple packages and/or modules. See setup script reference for details.
Some distributions actually do. 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 explicitly need distinct names.
As an example, the Pillow project provides an alternative to the original PIL distribution. Both projects distribute 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 project name.
PEP 8 applies to names of Python packages and modules.
If you Use a single name, PEP 8 also applies to project names. The exceptions are namespace packages, where dots are required in project name.
One important thing about a project name is that it be memorable.
As an example, celery is not a meaningful name. At first, it is not obvious that it deals with message queuing. But it is memorable, partly because it can be used to feed a RabbitMQ server.
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?”.
As an example, DateUtils is a meaningful name. It is obvious that it deals with utilities for dates.
When you are using namespaces, try to make each part meaningful.
Consider project names as unique identifiers on PyPI:
Classifiers and keywords metadata are made for categorization of distributions. Summary and description metadata are meant to describe the project.
As an example, there is a “Framework :: Twisted” classifier. Even if names are quite heterogeneous (they don’t follow a particular pattern), 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 inappropriate. 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.
The Zen of Python says “Flat is better than nested”.
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.
Yes: “pyranha”
Yes: “pythonsport.climbing”
Yes: “pythonsport.forestmap”
No: “pythonsport.maps.forest”
Don’t use 3 levels to set individual/organization ownership in a community namespace.
As an example, let’s consider:
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.gergovie”
Use packaging metadata instead.
Technically, you can create deeply nested hierarchies. However, in most cases, you shouldn’t need it.
Note
Even communities where namespaces are standard don’t use more than 3 levels.
Projects or related communities can have specific conventions, which may differ from those explained in this document.
In such a case, they should declare specific conventions in documentation.
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 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.
When no specific rule is defined, use the ${MAINPROJECT}contrib.${PROJECT} pattern to store community contributions for any product or framework, where:
As an example:
It is the simplest way to Organize community contributions.
Note
Why ${MAINPROJECT}contrib.* pattern?
This is the counterpart of the follow community conventions and standard pattern for contributions rules.
Actions:
About convention choices:
It means that existing community conventions don’t have to be changed. But, at least, they should be explicitly documented.
Example: “pyranha” is your project name and package name. Tell contributors that:
PyPI is the central place for distributions in Python community. So, it is also the place where to register project and package names.
See Registering with the Package Index for details.
The following recipes will help you follow the guidelines and conventions above.
Before you choose a project name, make sure it hasn’t already been registered in the following locations:
As an example, you could also check in various locations such as popular code hosting services, but keep in mind that PyPI is the only place you can register for names in Python community.
That’s why it is important you register names with PyPI.
Also make sure the names of distributed packages or modules haven’t already been registered:
The use a single name rule also helps you avoid clashes with package names: if a project name is available, then the package name has good chances to be available too.
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.
So, users of the legacy package:
Users who discover the legacy project see it is inactive.
If many projects follow Renaming howto recipe, then many legacy distributions will have the following characteristics:
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.
There is no obligation for existing projects to be renamed. The choice is left to project authors and mainteners for obvious reasons.
However, project authors are invited to:
The important thing, at first, is that you state about current choices:
Projects that are meant to receive contributions from community should also organize community contributions.
Every Python developer should migrate whenever possible, or promote the migrations in their respective communities.
Apply these guidelines 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, responsibility over communities.
Apply these guidelines on popular projects, then communities will adopt the conventions too.
Projects should promote migrations when they release a new (major) version, particularly if this version introduces support for Python 3.x, new standard library’s packaging or namespace packages.
As of Python 3.3 being developed:
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).
Additional background:
References and footnotes:
This document has been placed in the public domain.
Source: https://github.com/python/peps/blob/main/peps/pep-0423.rst
Last modified: 2025-05-03 18:09:21 UTC