This document deals with:
It provides guidelines and recipes for distribution authors:
Further consideration of this PEP has been deferred at least until afterPEP 426 (package metadata 2.0) and related updates have been resolved.
Reference ispackaging terminology in Python documentation.
packaging.core.setup() function.Here is a summarized list of guidelines you should follow to choosenames:
If you feel unsure after reading this document, askPythoncommunity 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 explicitlyauthorized.
As an example, don’t plug in “django.contrib” namespace because it ismanaged by Django’s core contributors.
Exceptions can be defined by project authors. SeeOrganize communitycontributions below.
Also, this rule applies to non-Python projects.
As an example, don’t use “apache” as top-level namespace: “Apache” isthe name of an existing project (in the case of “Apache”, it is also atrademark).
… because private projects are owned by somebody. So apply theownership rule.
For internal/customer projects, use your company name as thenamespace.
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 isclosed source.
… because they are owned by individuals. So apply theownership rule.
There is no shame in releasing a project as open source even if it hasan “internal” or “individual” name.
If the project comes to a point where the author wants to changeownership (i.e. the project no longer belongs to an individual), keepin mindit is easy to rename the project.
If your project is generic enough (i.e. it is not a contrib to anotherproduct or framework), you can avoid namespace packages. The basecondition is generally that your project is owned by a group (i.e. thedevelopment team) which is dedicated to this project.
Only use a “shared” namespace if you really intend the code to becommunity owned.
As an example,sphinx project belongs to the Sphinx developmentteam. There is no need to have some “sphinx” namespace package withonly one “sphinx.sphinx” project inside.
If your project is really experimental, best choice is to use anindividual or organization namespace:
Distribute only one package (or only one module) per project, and usepackage (or module) name as project name.
As an example,pipeline,python-pipeline anddjango-pipeline all distribute a package or module called“pipeline”. So installing two of them leads to errors. This issuewouldn’t have occurred if these distributions used a single name.
Yes:
importkheops.pyramidpipinstallkheops.pyramidNo:
Note
For historical reasons,PyPI contains many distributions whereproject and distributed package/module names differ.
Technically, Python distributions can provide multiple packages and/ormodules. Seesetup script reference for details.
Some distributions actually do.As an example,setuptools anddistribute are both declaring“pkg_resources”, “easy_install” and “site” modules in addition torespective “setuptools” and “distribute” packages.
Consider this use case as exceptional. In most cases, you don’t needthis feature. So a distribution should provide only one package ormodule at a time.
A notable exception to theUse a single name rule is when youexplicitly need distinct names.
As an example, thePillow project provides an alternative to theoriginalPIL distribution. Both projects distribute a “PIL”package.
Consider this use case as exceptional. In most cases, you don’t needthis feature. So a distributed package name should be equal to projectname.
PEP 8 applies to names of Python packages and modules.
If youUse a single name,PEP 8also applies to project names.The exceptions are namespace packages, where dots are required inproject 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 notobvious that it deals with message queuing. But it is memorable,partly because it can be used to feed aRabbitMQ server.
Ask yourself “how would I describe in one sentence what this name isfor?”, and then “could anyone have guessed that by looking at thename?”.
As an example,DateUtils is a meaningful name. It is obvious thatit 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 ofdistributions. Summary and description metadata are meant todescribe the project.
As an example, there is a “Framework :: Twisted” classifier. Evenif names are quite heterogeneous (they don’t follow a particularpattern), we get the list.
In order toOrganize community contributions, conventions aboutnames and namespaces matter, but conventions about metadata should beeven more important.
As an example, we can find Plone portlets in many places:
Even if Plone community has conventions, using the name to categorizedistributions is inappropriate. It’s impossible to get the full list ofdistributions 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 upwith projects and packages like “pythonsport.common.maps.forest”. Thistype of name is both verbose and cumbersome (e.g. if you have manyimports from the package).
Furthermore, big hierarchies tend to break down over time as theboundaries between different packages blur.
The consensus is that two levels of nesting are preferred.
For example, we haveplone.principalsource instead ofplone.source.principal or something like that. The name isshorter, the package structure is simpler, and there would be verylittle to gain from having three levels of nesting here. It would beimpractical to try to put all “core Plone” sources (a source is kindof vocabulary) into theplone.source.* namespace, in part becausesome sources are part of other packages, and in part because sourcesalready exist in other places. Had we made a new namespace, it wouldbe 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 ina community namespace.
As an example, let’s consider:
In such a case,you’d better use the most restrictive ownershiplevel 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, inmost cases, you shouldn’t need it.
Note
Even communities where namespaces are standard don’t use more than3 levels.
Projects or related communities can have specific conventions, whichmay differ from those explained in this document.
In such a case,they should declare specific conventions indocumentation.
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 thisdocument.
As an example,Plone community releases community contributions inthe “collective” namespace package. It differs from thestandardnamespace for contributions proposed here.But since it is documented, there is no ambiguity and you shouldfollow this specific convention.
When no specific rule is defined, use the${MAINPROJECT}contrib.${PROJECT} pattern to store communitycontributions for any product or framework, where:
${MAINPROJECT} is the name of the related project. “pyranha” inthe example below.${PROJECT} is the name of your project. “giantteeth” in theexample below.As an example:
It is the simplest way toOrganize community contributions.
Note
Why${MAINPROJECT}contrib.* pattern?
${MAINPROJECT}c.* is not explicit enough. As examples, “zc”belongs to “Zope Corporation” whereas “z3c” belongs to “Zope 3community”.${MAINPROJECT}community is too long.${MAINPROJECT}community conflicts with existing namespacessuch as “iccommunity” or “PyCommunity”.${MAINPROJECT}.contrib.* is inside ${MAINPROJECT} namespace,i.e. it is owned by ${MAINPROJECT} authors. It breaks theTop-level namespace relates to code ownership rule.${MAINPROJECT}.contrib.* breaks theAvoid deep nestingrule.${MAINPROJECT} doesn’t appear are not explicitenough, 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 existingsphinxcontrib-*packages. Butsphinxcontrib-* is actually about Sphinxcontrib, so this is not a real conflict… In fact, the “contrib”suffix was inspired by “sphinxcontrib”.This is the counterpart of thefollow community conventions andstandard pattern for contributions rules.
Actions:
About convention choices:
It means that existing community conventions don’t have to bechanged. 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.
SeeRegistering with the Package Index for details.
The following recipes will help you follow the guidelines andconventions above.
Before you choose a project name, make sure it hasn’t already beenregistered in the following locations:
As an example, you could also check in various locations such aspopular code hosting services, but keep in mind that PyPI is the onlyplace you canregister for names in Python community.
That’s why it is important youregister names with PyPI.
Also make sure the names of distributed packages or modules haven’talready been registered:
PyPI. There is currently no helper for that.Notice that the more projects follow theuse a single name rule,the easier is the verification.Theuse a single name rule also helps you avoid clashes withpackage names: if a project name is available, then the package namehas good chances to be available too.
Renaming a project is possible, but keep in mind that it will causesome confusions. So, pay particular attention to README anddocumentation, so that users understand what happened.
Obsoletes-Dist metadata to new distribution in setup.cfgfile. SeePEP 345 about Obsolete-Distandsetup.cfgspecification.DevelopmentStatus::7-Inactive classifier insetup script,So, users of the legacy package:
Users who discover the legacy project see it is inactive.
If many projects followRenaming howtorecipe, then many legacy distributions will have the followingcharacteristics:
DevelopmentStatus::7-Inactive classifier.Obsoletes-Dist in a newer distribution.So it will be possible to detect renamed projects and improvereadability on PyPI. So that users can focus on active distributions.But this feature is not required now. There is no urge. It won’t becovered in this document.
There is no obligation for existing projects to be renamed. Thechoice 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 currentchoices:
Projects that are meant to receive contributions from community shouldalsoorganize community contributions.
Every Python developer should migrate whenever possible, or promotethe migrations in their respective communities.
Apply these guidelines on your projects, then the community will seeit is safe.
In particular, “leaders” such as authors of popular projects areinfluential, they have power and, thus, responsibility overcommunities.
Apply these guidelines on popular projects, then communities willadopt the conventions too.
Projects should promote migrations when they release a new (major)version, particularlyif this version introduces support forPython 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 thenext year(s) to support Python 3.x, new packaging or new namespacepackages.
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 GMT