PEP 423 – Naming conventions and recipes related to packaging | peps.python.org
PEP 423 – Naming conventions and recipes related to packaging PEP 423 – Naming conventions and recipes related to packaging Author : Benoit Bryon <benoit at marmelune.net> Discussions-To : Distutils-SIG list Status : Deferred Type : Informational Topic : Packaging Created : 24-May-2012 Post-History : Table of Contents Abstract PEP Deferral Terminology Relationship with other PEPs Overview If in doubt, ask Top-level namespace relates to code ownership Respect ownership Private (including closed-source) projects use a namespace Individual projects use a namespace Community-owned projects can avoid namespace packages In doubt, use an individual/organization namespace Use a single name Multiple packages/modules should be rare Distinct names should be rare Follow PEP 8 for syntax of package and module names Pick memorable names Pick meaningful names Use packaging metadata Avoid deep nesting Two levels is almost always enough Use only one level for ownership Don’t use namespace levels for categorization Don’t use more than 3 levels Conventions for communities or related projects Follow community or related project conventions, if any Use standard pattern for community contributions Organize community contributions Register names with PyPI Recipes How to check for name availability?
How to rename a project? Improved handling of renamed projects on PyPI How to apply naming guidelines on existing projects? State about current naming Promote migrations Opportunity References Copyright Abstract This document deals with: names of Python projects, names of Python packages or modules being distributed, namespace packages. It provides guidelines and recipes for distribution authors: new projects should follow the guidelines below. existing projects should be aware of these guidelines and can follow specific recipes for existing projects .
PEP Deferral Further consideration of this PEP has been deferred at least until after PEP 426 (package metadata 2.0) and related updates have been resolved. Terminology Reference is packaging terminology in Python documentation . Relationship with other PEPs 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 name argument of the packaging.core.setup() function.
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. It points out that naming conventions matter and is an example of transition plan. Overview Here is a summarized list of guidelines you should follow to choose names: understand and respect namespace ownership . if your project is related to another project or community: search for conventions in main project’s documentation, because projects should organize community contributions . follow specific project or related community conventions , if any. if there is no convention, follow a standard naming pattern . make sure your project name is unique, i.e. avoid duplicates: use top-level namespace for ownership , check for name availability , register names with PyPI . make sure distributed packages and modules names are unique, unless you explicitly want to distribute alternatives to existing packages or modules.
Using the same value for package/module name and project name is the recommended way to achieve this. distribute only one package or module at a time , unless you know what you are doing. It makes it possible to apply the “ use a single name ” rule, and thus make names consistent. make it easy to discover and remember your project: use as much memorable names as possible , use as much meaningful names as possible , use other packaging metadata . avoid deep nesting .
Flat things are easier to use and remember than nested ones: one or two namespace levels are recommended, because they are almost always enough. even if not recommended, three levels are, de facto, a common case. in most cases, you should not need more than three levels. follow PEP 8 for syntax of package and module names. if you followed specific conventions, or if your project is intended to receive contributions from the community, organize community contributions . if still in doubt, ask .
If in doubt, ask If you feel unsure after reading this document, ask Python community on IRC or on a mailing list. Top-level namespace relates to code ownership This helps avoid clashes between project 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 Foundation. 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. Respect ownership Understand the purpose of namespace before you use it. Don’t plug into a namespace you don’t own, unless explicitly authorized.
If in doubt, ask . 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).
Private (including closed-source) projects use a namespace … 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. Individual projects use a namespace … 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 . Community-owned projects can avoid namespace packages 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. In doubt, use an individual/organization namespace If your project is really experimental, best choice is to use an individual or organization namespace: it allows projects to be released early. it won’t block a name if the project is abandoned. it doesn’t block future changes.
When a project becomes mature and there is no reason to keep individual ownership, it remains possible to rename the project . Use a single name 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
The rest of this page is on the live site.