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 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.

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.

Multiple packages/modules should be rare

Technically, Python distributions can provide multiple packages and/or modules. See setup script reference 16 for details.

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.

Distinct names should be rare

A notable exception to the Use a single name rule is when you explicitly need distinct names.

As an example, the Pillow 19 project provides an alternative to the original PIL 20 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.

Two levels is almost always enough

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”

Use only one level for ownership

Don’t use 3 levels to set individual/organization ownership in a community namespace.

As an example, let’s consider:

• you are plugging into a community namespace, such as “collective”.
• and you want to add a more restrictive “ownership” level, to avoid clashes inside the community.

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”

Don’t use namespace levels for categorization

Use packaging metadata instead.

Don’t use more than 3 levels

Technically, you can create deeply nested hierarchies. However, in most cases, you shouldn’t need it.

Follow community or related project conventions, if any

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 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.

Use standard pattern for community contributions

When no specific rule is defined, use the ${MAINPROJECT}contrib.${PROJECT} pattern to store community contributions for any product or framework, where:

• ${MAINPROJECT} is the name of the related project. “pyranha” in the example below.
• ${PROJECT} is the name of your project. “giantteeth” in the example below.

As an example:

• you are the author of “pyranha” project. You own the “pyranha” namespace.
• you didn’t defined specific naming conventions for community contributions.
• a third-party developer wants to publish a “giantteeth” project related to your “pyranha” project in a community namespace. So he should publish it as “pyranhacontrib.giantteeth”.

It is the simplest way to Organize community contributions.

Organize community contributions

This is the counterpart of the follow community conventions and standard pattern for contributions rules.

Actions:

• Choose a naming convention for community contributions.
• If it is not the default, then document it.
  • if you use the default convention, then this document should be enough. Don’t repeat 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 classifiers and keywords.

About convention choices:

• New projects should choose the default contrib pattern.
• Existing projects with community contributions should start with custom conventions. Then they can Promote migrations.

  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:

• pyranha-related distributions should use the “pyranha” keyword
• pyranha-related distributions providing templates should also use “templates” keyword.
• community contributions should be released under “pyranhacontrib” namespace (i.e. use “pyranhacontrib.*” pattern).

How to check for name availability?

Before you choose a project name, make sure it hasn’t already been registered in the following locations:

• PyPI 11
• that’s all. PyPI is the only official place.

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:

• in the Python Standard Library 28.
• inside projects at PyPI. There is currently no helper for that. Notice that the more projects follow the use a single name rule, the easier is the verification.
• you may ask the community.

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.

How to rename a project?

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.

1. First of all, do not remove legacy distributions from PyPI. Because some users may be using them.
2. Copy the legacy project, then change names (project and package/module). Pay attention to, at least:
   • packaging files,
   • folder name that contains source files,
   • documentation, including README,
   • import statements in code.
3. Assign Obsoletes-Dist metadata to new distribution in setup.cfg file. See PEP 345 about Obsolete-Dist 29 and setup.cfg specification 30.
4. Release a new version of the renamed project, then publish it.
5. Edit legacy project:
   • add dependency to new project,
   • 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:

• can continue using the legacy distributions at a deprecated version,
• can upgrade to last version of legacy distribution, which is empty…
• … and automatically download new distribution as a dependency of the legacy one.

Users who discover the legacy project see it is inactive.

How to apply naming guidelines on existing projects?

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:

• at least, state about current naming.
• then plan and promote migration.
• optionally actually rename existing project or distributed packages/modules.