Hello,

Le 14/05/2012 13:12, Jim Fulton a écrit :

+1 for an official document (or addition to an existinhg document) providing a rational for namespace packages and their naming.

I opened a ticket on CPython issue tracker: http://bugs.python.org/issue14899

Then started to work in a fork: https://bitbucket.org/benoitbryon/cpython/src/doc-package-names/Doc/packagin...

.. but it looks like a PEP. So, I followed PEP 1 and posted the proposal to python-list@python.org... where I've been told to post it to distutils-sig :) So, I'm back here with a proposal...

The document below is the same as current version of https://bitbucket.org/benoitbryon/cpython/src/doc-package-names/Doc/packagin....

Thanks to Martin Aspeli for his article. Thanks to early reviewers: Alexis Métaireau, Éric Bréhault, Jean-Philippe Camguilhem and Mathieu Leplâtre.

Benoit

########################################### Names in packaging: conventions and recipes ###########################################

This document deals with:

* names of Python projects, * names of distributions in projects, * names of Python packages or modules being distributed, * namespace packages.

It provides conventions and recipes for distribution authors.

Main use case is:

* as a developer, I want to create a project in order to distribute a package. So I have to choose names. Which names are "good"?

* `The Zen of Python`_ says:

In the face of ambiguity, refuse the temptation to guess. There should be one-- and preferably only one --obvious way to do it.

* So I need clear and official (i.e. obvious) guidelines or conventions that I can follow.

* Here are conventions, guidelines and recipes.

Guidelines for existing projects are also given.

*********** Terminology ***********

First of all, let's make sure there is no confusion...

Distribution name Distribution name is used by packaging utilities:

* in :doc:`setup script</packaging/setupscript>`, it is the value passed as ``name`` to ``packaging.core.setup()`` * it appears on `PyPI`_ if the package is registered on it * it can be used in `pip` requirements files * it can be used in `buildout` configuration files.

Distribution term is introduced in :doc:`packaging docs</packaging/index>`.

Egg name It is the same concept as distribution name. Technically, the egg is not the distribution. But they use the same name: it is declared as ``packaging.core.setup()`` name argument.

"Egg" term is the legacy counterpart to "distribution". It was used by distutils and setuptools. It becomes deprecated with the new packaging module.

This document focuses on distributions, not eggs.

Package and module names Package and module names are used in Python code. It is the string used in :ref:`import statements<import>`.

Remember that, from a file system perspective, packages are directories and modules are files.

:ref:`Python packaging allows distributions to distribute several packages and/or modules<setupcfg-section-files>`.

Project name Usually the name of the repository or folder in which distribution authors put their code. It generally is the directory name of the "distribution root", as defined in :ref:`packaging-term`.

Namespace packages It is common practice to use namespaces in package names. `PEP 420`_ brings this concept to core Python. When PEP 420 will be accepted, Python officially supports namespace packages.

As an example, consider `django-debug-toolbar`_:

* ``django-debug-toolbar`` is the distribution name. `It is declared in setup.py file https://github.com/django-debug-toolbar/django-debug-toolbar/blob/599d76e41c5728c0e342d55250690b2694bd2aad/setup.py#L4`_.

* ``debug_toolbar`` is the package name. It is what would appear in Django's INSTALLED_APPS setting or be used as ``import debug_toolbar``.

Technically, all those names can be different.

********* Rationale *********

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

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

Other sources of inspiration ============================

* `Martin Aspeli's article about names`_. Some parts of this proposal are quotes from this article.

* `The Hitchhiker's Guide to Packaging`_, which has an empty placeholder for "naming specification".

* and, of course, `in development official packaging documentation`_.

Facts =====

Before Python version 3.3, there is no official guidelines to name projects, distributions or packages/modules. Current PEPs (see `Relationship with other PEPs`_) are very open on this topic.

Distribution authors have to follow their own intuition.

Several standards emerged from communities. As examples:

* `Plone`_ community uses "plone.*" namespace for official Plone products, and "collective.*" for community products. This is a convention explicitely promoted by Plone community. `Martin Aspeli's article about names`_ is about conventions and usages in Plone community.

.. note:: Is there an official document about these conventions? A PLIP?

* most `Django`_ applications from community use "django-*" pattern as distribution name. This is a de facto standard.

* many `Pyramid`_ applications from community use "pyramid_*" pattern as distribution name.

Thus, as `PyPI`_ testifies, distribution names and package/module names are really heterogeneous.

Impacts =======

Here are points this document tries to resolve.

Ambiguity ---------

When distribution authors come to choose a name, they can't find an unique official guideline. In such a situation, "Now is better than never" wins over "Refuse temptation to guess". So distribution authors follow one of the conventions they discovered (usually the one from their community), or follow their own intuition.

Confusion ---------

As explained in `terminology`_ above, project, distribution and package names can be assigned distinct values. That is a big source of confusion, especially for Python developers who are not used to packaging.

Time loss ---------

As a direct consequence of `ambiguity`_ and `confusion`_, new Python developers spend too much time to understand Python projects/distributions/packages names:

* they can't find obvious (i.e. official) naming conventions (or at least guidelines) even if they search for it. They have to ask community to resolve the `ambiguity`_.

* it's hard to resolve the `confusion`_ between names. It's even harder because community itself is a bit confused. Their best chance is to find one of the `Other sources of inspiration`_ listed above or ask a well informed person.

* developers from some other languages suppose Python have official naming conventions for distributions and packages. So they search for it, and feel worried when they figure out that it doesn't exist.

Experienced Python users are less affected: they built their opinion in the past and keep on following their habits.

Community partitionning -----------------------

The global Python community is partitionned into opposed sub-communities:

* most Python developers are linked to at least one community (i.e. Zope, Plone, Pyramid, Django...).

* communities usually resolved naming conventions with official documents or with de facto usage.

* developers usually follow their community's standards.

* developers usually believe their community made the best choice. They usually adhere to community arguments.

* choices and reasons differ from one community to another.

* when Python communities meet, package names are a never-ending topic of discussion.

* people discuss about package names when they should work together on more valuable stories.

* they can't settle the issue, because:

* arguments have historical reasons. In history, these reasons were enough.

* accepting someone else's arguments means changing habits, and maybe re-packaging existing projects, i.e. efforts and time.

* there is no guidelines from an higher authorithy (i.e. python.org). There is no comparison standard. Both choices are legitimate.

An additional note about developers who belong to several communities:

* they usually adhere to the naming conventions from one community, * it's hard to adopt another convention when contributing in another community.

Proposal ========

As `The Zen of Python`_ says: "There should be one-- and preferably only one --obvious way to do it."

So the proposal is:

* adopt strict conventions where Python community finds a consensus, * provide guidelines or recipes for what cannot be covered by conventions.

What about existing projects? =============================

It's impossible to **require** a change for every existing project, for obvious reasons.

But it is possible to first **document** existing naming conventions, then **promote** a change.

This document proposes two things:

* a status on current existing naming conventions, inside each project or community. So that custom naming conventions are at least self-documented. See `Organize community contributions`_ for details.

* a `Transition plan`_ for those who are ready to migrate.

.. _`packagenames-opportunity`:

Opportunity ===========

As of Python 3.3 being developed:

* many projects are not Python 3.x compatible. It includes "big" products or frameworks. It means that many projects will have to do a migration to support Python 3.x.

* packaging (aka distutils2) is on the starting blocks. When it is released, projects will be invited to migrate and use new packaging.

* `PEP 420`_ brings official support of namespace packages to Python.

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

*************** Transition plan ***************

New distributions =================

In order of priority:

1. If the project belongs to a community (i.e. product/framework), **and** the community have official conventions, then follow community conventions.

.. note::

:ref:`Communities SHOULD organize contributions <packagenames-organizecommunities>`.

As an example new community project related to Plone should be distributed as "collective.*", because it is an explicit standard of the Plone community.

2. New projects SHOULD follow `Conventions`_ described in this document.

Existing projects =================

**There is no obligation for existing distributions to be renamed**. The choice is left to distribution authors and mainteners for obvious reasons.

However, distribution authors are invited to `promote migrations`_.

In order to rename an existing distribution, follow `Renaming howto`_ guidelines below.

Promote migrations ==================

Every Python developer should migrate whenever possible, or promote the migrations in their respective communities.

Apply this convention 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, responsability over communities.

Apply this conventions on popular projects, then communities will adopt the conventions too.

**Popular projects SHOULD promote migrations when they release a new (major) version**, particularly :ref:`if this version introduces support for Python 3.x, new standard library's packaging or namespace packages <packagenames-opportunity>`.

.. note::

On the contrary, if popular projects refuse the conventions, communities may not adopt the conventions.

Improved handling of renamed distributions on PyPI ==================================================

If many projects follow `Renaming howto`_, 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 distribution. * referenced as ``Obsoletes-Dist`` in a newer distribution.

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

*********** Conventions ***********

Rules that you SHOULD follow.

If in doubt, ask ================

If you feel unsure after reading the following conventions, ask `Python community`_ on IRC or on a mailing list.

Use a single name =================

Distribute only one package (or only one module) in a distribution, and use package (or module) name as project name and distribution name.

* It avoids possible confusion between all those names. * It makes the name consistent. * It is explicit: when one sees distribution name, he guesses package name, and vice versa. * It also limits implicit clashes between package/module names. By using a single name, when you register a name to PyPI, you also perform a basic package/module name availability verification.

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.

Yes:

* Package name: "kheops.pyramid", i.e. ``import kheops.pyramid``

* distribution name: "kheops.pyramid", i.e. ``pip install kheops.pyramid``

* Project name: "kheops.pyramid", i.e. ``git clone git@github.com/pharaohs/kheops.pyramid.git``

No:

* Package name: "kheops" * Distribution name: "kheops-pyramid" * Project name: "KheopsPyramid"

.. note::

For historical reasons, on `PyPI`_, you can find many distributions using different values for project, distribution and package/module name.

Multiple packages/modules should be rare ----------------------------------------

Technically, Python distributions can provide multiple packages and/or modules. See :ref:`setup script reference<packaging-setup-script>` for details.

Some distributions actually does. 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.

Explicit distinct names should be rare --------------------------------------

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

As an example, the `Pillow`_ distribution is an alternative to the original `PIL`_ distribution. They both provide 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 distribution name.

Follow PEP 8 for package names syntax =====================================

`PEP 8`_ applies to Python package and module names.

If you `Use a single name`_, `PEP 8`_ also applies to project and distribution names. The exceptions are namespace packages, where dots are required in the name.

Pick meaningful names =====================

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

When you are using namespaces, make sure each part is meaningful.

.. _`packagenames-ownership`:

Top level namespace relates to code ownership =============================================

This helps avoid clashes between distribution 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 Fundation.

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

**DO NOT** plug into a namespace you don't own, unless explicitely authorized.

`If in doubt, ask`_.

As an example, **DO NOT** use "django.contrib" namespace: it is managed by Django's core contributors.

Exceptions CAN be defined by distribution authors. See `Organize community contributions`_ below.

Private (including closed-source) distributions use a namespace ---------------------------------------------------------------

... because private distributions are owned by somebody. So apply the :ref:`ownership rule<packagenames-ownership>`.

For internal/customer projects, use your company name as the namespace.

This rule applies to closed-source distributions.

As an example, if you are creating a "climbing" distribution 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 :ref:`ownership rule <packagenames-ownership>`.

There is no shame in releasing a distribution as open source even if it has an "internal" 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 :ref:`it is easy to rename the project<packagenames-rename>`.

Independant community Python projects CAN avoid namespaces ----------------------------------------------------------

If your project is generic enough (i.e. it is not a contrib to another product or framework), you CAN avoid namespaces. 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.

In doubt, use an individual/organization namespace --------------------------------------------------

If your project is not mature or hasn't been proven useful to a community, best choice is to use an individual or organization namespace.

It allows distribution authors to release projects early.

And it doesn't block future changes. When a project becomes mature, and if it appears there is no reason to keep individual ownership, :ref:`it remains possible to rename the project<packagenames-rename>`.

Avoid deep nesting ==================

`The Zen of Python`_ says:

Flat is better than nested.

Two levels is almost always enough ----------------------------------

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

Yes: "pyranha"

Yes: "pythonsport.climbing"

Yes: "pythonsport.forestmap"

No: "pythonsport.maps.forest"

.. _`packagenames-othermetadata`:

Limited namespace levels, unlimited metadata --------------------------------------------

Consider distribution names (with or without namespaces) as unique identifiers on PyPI. It is important that these identifiers remain human-readable. It is even better when these identifiers are meaningful. But their primary purpose is not to classify or describe distributions.

As examples, if you only look at the name:

* you can't guess "nose" is about testing, * or "celery" about distributed task queueing, * or that "lettuce" is about tests, and has nothing in common with "celery".

The examples above are not problematic.

**`Classifiers`_ and keywords metadata are made for categorization of distributions.**

As an example, there is a "Framework :: TurboGears" classifier. Even if names are quite heterogeneous (they don't follow a pattern like collective.* for Plone community projects), 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:

* plone.portlet.* * collective.portlet.* * collective.portlets.* * collective.*.portlets * some vendor-related distributions such as "quintagroup.portlet.cumulus" * and even distributions where "portlet" pattern doesn't appear...

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.

Do you really need 3 levels? ----------------------------

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.

3 levels are also tempting when:

* you are pluging 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.collectivegergovie"

3 levels are supported for historical reasons ---------------------------------------------

Even if not recommended, 3 levels are supported. This is mainly for historical reasons: 3 levels can be accepted where top level namespace owner explicitely allows it with a specific convention. See `Organize community contributions`_ for details.

Don't use more than 3 levels ----------------------------

* 1 or 2 levels are recommended. * 3 levels are discouraged, but supported for historical reasons. * you shouldn't need more than 3 levels.

.. note::

Even communities where namespaces are standard don't use more than 3 levels.

.. _`packagenames-organizecommunities`:

Organize community contributions ================================

Actions:

* Choose a naming convention for community contributions.

* If it is not :ref:`the default<packagenames-contribnamespace>`, document it.

* if you use the :ref:`default convention<packagenames-contribnamespace>`, this document should be enough. Don't reapeat 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 :ref:`classifiers and keywords<packagenames-othermetadata>`.

About convention choices:

* New projects SHOULD choose the default scheme.

* Existing projects with community contributions CAN start with custom conventions. Then they SHOULD `Promote migrations`_.

It means that existing community conventions doesn't need to be changed. But they need to be explicitely documented: first state about current naming conventions, then about future.

Example: "pyranha" is your project name, distribution name and package name. Tell contributors that:

* pyranha-related distributions should use the "pyranha" keyword

* pyranha distributions providing templates should also use "templates" keyword.

* community contributions should be released under "pyranhacontrib" namespace (i.e. use "pyranhacontrib.*" pattern):

.. _`packagenames-contribnamespace`:

Community contributions SHOULD use "${DIST}contrib.*" pattern ================================================================

The idea is to use a standard pattern to store community contributions for any product or framework.

It is the simplest way to `Organize community contributions`_: the obvious way to go is "${DIST}contrib", no ambiguity.

As an example:

* you are the author of "pyranha" project. You own the "pyranha" namespace. * a third-party developer wants to publish a "giantteeth" project related to your "pyranha" project. He can publish it as "pyranhacontrib.giantteeth".

.. note::

Why ``${DIST}contrib.*`` pattern?

* ``${DIST}c.*`` is not explicit enough. As examples, "zc" belongs to "Zope Corporation" whereas "z3c" belongs to "Zope 3 community".

* ``${DIST}community`` is too long.

* ``${DIST}community`` conflicts with existing namespaces such as "iccommunity" or "PyCommunity".

* ``${DIST}.contrib`` is inside ${DIST} namespace, i.e. it is owned by ${DIST} authors. It breaks the `Top level namespace relates to code ownership`_.

* ``${DIST}.contrib.*`` breaks the `Avoid deep nesting`_ rule.

* names where ``${DIST}`` doesn't appear are not explicit enough, i.e. nobody can guess they are related to ``${DIST}``.

* ``{$DIST}contrib.*`` may conflict with 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".

******* Recipes *******

How to avoid duplicate names ============================

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

* `PyPI`_ * Popular code repositories such as:

* `Github`_ * `Bitbucket`_ * `Gitorious`_

* `djangopackages.com`_

.. note:: A web service would be welcome for this!

Also make sure the package name hasn't already been registered:

* in the `Python Standard Library`_, * in the locations where you checked for distribution name availability.

.. _`packagenames-rename`:

Renaming howto ==============

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.

#. First of all, **do not remove legacy distribution from PyPI**. Because some users may be using it.

#. Copy the legacy project, then change names (project, distribution and package/module). Pay attention to, at least:

* packaging files, * folder name that contains source files, * documentation, including README, * import statements in code.

#. Assign ``Obsoletes-Dist`` metadata to new distribution in setup.cfg file. See `PEP 345 about Obsolete-Dist`_ and :ref:`setup.cfg specification <setupcfg-spec>`.

#. Release the renamed distribution as a new version, then publish it.

#. Edit legacy distribution:

* add dependency to new distribution, * 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 distribution 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 distribution see it is inactive.

********** References **********

.. target-notes::

.. _`Martin Aspeli's article about names`: http://www.martinaspeli.net/articles/the-naming-of-things-package-names-and-... .. _`PEP 1`: http://www.python.org/dev/peps/pep-0001/ .. _`The Zen of Python`: http://www.python.org/dev/peps/pep-0020/ .. _`PEP 8`: http://www.python.org/dev/peps/pep-0008/#package-and-module-names .. _`PEP 345`: http://www.python.org/dev/peps/pep-0345/ .. _`PEP 420`: http://www.python.org/dev/peps/pep-0420/ .. _`PEP 3108`: http://www.python.org/dev/peps/pep-3108 .. _`The Hitchhiker's Guide to Packaging`: http://guide.python-distribute.org/specification.html#naming-specification .. _`in development official packaging documentation`: http://docs.python.org/dev/packaging/ .. _`plone`: http://plone.org/community/develop .. _`django`: http://djangoproject.com/ .. _`pyramid`: http://pylonsproject.org .. _`pypi`: http://pypi.python.org .. _`django-debug-toolbar`: https://github.com/django-debug-toolbar/django-debug-toolbar .. _`gp.fileupload`: http://pypi.python.org/pypi/gp.fileupload/ .. _`zest.releaser`: http://pypi.python.org/pypi/zest.releaser/ .. _`sphinx`: http://sphinx.pocoo.org .. _`Classifiers`: http://pypi.python.org/pypi?:action=list_classifiers .. _`collective.recaptcha`: http://pypi.python.org/pypi/collective.recaptcha/ .. _`Python community`: http://www.python.org/community/ .. _`pipeline`: http://pypi.python.org/pypi/pipeline/ .. _`python-pipeline`: http://pypi.python.org/pypi/python-pipeline/ .. _`django-pipeline`: http://pypi.python.org/pypi/django-pipeline/ .. _`setuptools`: http://pypi.python.org/pypi/setuptools .. _`distribute`: http://packages.python.org/distribute/ .. _`Pillow`: http://pypi.python.org/pypi/Pillow/ .. _`PIL`: http://pypi.python.org/pypi/PIL/ .. _`Python Standard Library`: http://docs.python.org/library/index.html .. _`github`: https://github.com .. _`bitbucket`: https://bitbucket.org .. _`gitorious`: https://gitorious.org/ .. _`djangopackages.com`: http://djangopackages.com .. _`PEP 345 about Obsolete-Dist`: http://www.python.org/dev/peps/pep-0345/#obsoletes-dist-multiple-use

Hi,

Updated https://bitbucket.org/benoitbryon/cpython/src/doc-package-names/Doc/packagin...

Le 31/05/2012 18:00, PJ Eby a écrit :

You've definitely put in a lot of work on this, and most of the actual guidelines in your PEP are quite good. I think there's a core part of this that can and should be a good Informational-track PEP.

If it actually becomes a draft PEP, I guess we should:

* move the document in PEPs' repository * add notes in Python packaging documentation to reference the PEP.

However, I do have a few comments regarding overall organization, and some regarding some of the specific recommendations and tone.

In order of appearance in the PEP, they are:

1. I would strongly suggest striking the aside on eggs entirely --

there's no point to bringing it up just to dismiss it, and there never was such a thing as an "egg name" - eggs are just another kind of distribution, so they don't need a special term.

Removed the text about eggs.

2. A project name isn't the name of a directory, it's the name of the

thing you release distributions of. E.g., my "Importing" project on PyPI (http://pypi.python.org/pypi/Importing), which has the following names:

a) Project name = Importing b) Release = 1.10 c) Distribution = Importing-1.10.zip d) Module = peak.util.imports

Following this conceptual breakdown will make the naming recommendations easier to follow.

Changed "Terminology section".

However, I am still confusing "project name" and "distribution name". From your comment, I understand that name argument of packaging.core.setup() is the name of the project, which is used to get names of the distributions like "%(project_name)s-%(version)s.tar.gz". But PEP 345 says it is the name of the distributions : http://www.python.org/dev/peps/pep-0345/#name

Also, I propose to shorten or move the "terminology" section in another document (another pep or in packaging documentation):

* it would simplify the document * we'd better share the terminology between several documents.

3. The rationale is unnecessary and could (and *should*) be cut

entirely. Use PEP 8 as a model - it doesn't waste time explaining why coding guidelines are a good idea. The truth is, your PEP would be massively improved simply by deleting this entire section and not even trying to replace it with anything.

Changed the "Rationale" section:

* kept "relationship with other PEPs" and "other sources of inspiration". * moved "opportunity" section from "Rationale" to "Transition plan" section. I kept it because opportunity should be a valuable reason to adopt the conventions. And unlike other statements of "Rationale", opportunity cannot be explained within the conventions. Would you remove it too? * removed other text in the "Rationale" section.

4. The proposal section is also unnecessary, and likely to produce

resistance in any event.

The "proposal" part of "Rationale" section has been removed.

There is no reason why every package should use your approach,and some developers will be opposed to your conventions.

"Rationale" section used to point out that current (missing) naming rules lead to problems, such as duplicate packages/modules or inconsistent project/package names. Shouldn't we consider them as issues?

But, whatever the value of those arguments, I understand some developers will be opposed to proposed conventions.

That's why I tried to make the document tell:

* at last, in the namespace you own, you do what you want. * at least (and at first), you should state on the conventions you are currently using. * then, understand the issues that names can introduce. * optionally follow the proposed conventions, which may lead to renaming project or packages/modules.

Since the document is a bit directive, the ideas above appear in reversed order: first you should apply the convention, but at last you do what you want to. Is it clear in the document?

Let's consider the "django-pipeline" VS "pipeline" VS "python-pipeline" example:

* there is no obligation at all to rename these projects or packages. * but one should admit there is an issue with names. Here the issue is a duplicate package name. See https://github.com/cyberdelia/django-pipeline/issues/101 * first of all, authors should be aware of the issue. * then, if authors want to, they can apply conventions, which could be a rename of the distributed package only. * if django-pipeline changes its package or project name, it breaks the "most used" scheme (de facto standard) of the Django community. So it would be another homemade naming scheme... * unless the Django community takes the naming issues into account, states about packaging, and optionally promotes migrations.

Notice that Django community could state that "there is no valuable issue, i.e. wontfix". But this would mean that this choice is documented in an issue, discussion or in the documentation... so it would fit the guidelines as an explicit community-specific convention.

(I disagree with some of them myself, for that matter, as I will discuss below.) Some of the material from this section might make a good later section on "How to apply these guidelines to your project".

The "proposal" section has been removed as part of the "Rationale" one. Were you talking about the "Transition plan" instead?

I moved the "transition plan" section at the end of the document, i.e. conventions appear before. In fact, I changed the "transition plan" into a set of recipes for existing projects.

5. The actual guidelines are pretty good, as I said. In particular, I

like pretty much every thing you say about package names. I disagree with some of your assertions regarding project names, however. It's true that a project name doesn't need to spell out what a project does (as with Celery, Nose, etc.), but it does in fact hurt discovery and use when people use package-based project names. It's a continuing source of frustration, for example, that buildout recipe projects have names like z3c.recipe.scripts and other names that I can't ever remember, and am forced to re-google or dig up previous buildout files to find the magic names to include in my buildouts. To me, the important thing about a project name is that it be *memorable*, and that argues against using namespaced package names as project names for contributions to a larger project, such as Plone portlets, Buildout recipes, etc.

This isn't a huge point of contention for me, I just want to point out that the good naming choices for projects are more complicated than "just use the package name and let people search for it". I think there are some other points you made that are a little too cut-and-dried in the same way, but this is the only really big one.

I updated the conventions:

* added an overview of conventions, * introduced the "memorable" value.

I agree that choosing a "good" name is not easy. I suppose that the best we can do is to provide guidelines such as "ownership", "memorable" or "meaningful"... so that users can avoid some common pitfalls.

Then, it's a matter of priorities. I would say that:

1. first, we should avoid duplicates (project and packages). That's why "top-level namespace for ownership" and "use a single name" seem so important to me.

2. then, it's better if the project name is memorable and meaningful and easy to discover... but it's a less important issue than duplicates, mainly because other metadata such as description, keywords and classifiers can help.

6. Drop the language about how things are supported or not supported.

This just isn't true: Python the language supports you nesting things 6 layers deep if you feel like it, and AFAIK there are no plans to change that, nor should there be. Stick to talking here about what is or isn't a good idea, not what's supported or not supported. That's just FUD.

Removed "support" vocabulary. Changed "conventions" to "guidelines". Used only lowercase "may", "should" and "can".

7. PyPI should be the only place people have to check for a

registered distribution name; authors of projects that are hosted elsewhere can and should use "setup.py register" to claim the name, or log on and do it.

Added "Register names to PyPI" guideline. Changed the "check for name availability" recipe: PyPI is the only place.

Anyway, as I said, I think you've got some really good stuff here, but it's got a lot of other stuff hiding it. Cut away the extras (and the parts implying these guidelines are mandatory) and you've got a good Informational-track PEP.

Does it sounds better now?

Regards, Benoit

Hi,

Le 06/06/2012 10:52, Benoît Bryon a écrit :

Le 31/05/2012 18:00, PJ Eby a écrit :

...

You've definitely put in a lot of work on this, and most of the actual guidelines in your PEP are quite good. I think there's a core part of this that can and should be a good Informational-track PEP.

If it actually becomes a draft PEP, I guess we should:

• move the document in PEPs' repository
• add notes in Python packaging documentation to reference the PEP.

Updated https://bitbucket.org/benoitbryon/cpython/src/doc-package-names/Doc/packagin... Prepared migration to a PEP. I am to submit the document for review at peps@python.org. Feedback is welcome!

Le 06/06/2012 10:52, Benoît Bryon a écrit :

Also, I propose to shorten or move the "terminology" section in another document (another pep or in packaging documentation):

• it would simplify the document
• we'd better share the terminology between several documents.

Moved terminology section to packaging/introduction.rst. See https://bitbucket.org/benoitbryon/cpython/changeset/5eca478e6804#chg-Doc/pac...

Benoit

[Benoît Bryon, 2012-06-27]

http://hg.python.org/peps/file/52767ab7e140/pep-0423.txt

I think PEP 386 (about versions) should be mentioned in "Relationship with other PEPs" section.

About "Use a single name" section: sometimes one needs to add "python-" or "py" prefix to project name (f.e. if the name is already used in other programming languages and you cannot register it in your favourite forge hosting service)... but please don't add the prefix also in namespace. All these PyQts, pyudevs, pygames and pyopencls sound stupid to me (isn't it obvious that when I do `import foo` in Python, "foo" is a *Python* library?)

About ".contrib.": flask uses flask.ext.foo (namespace) and Flask-Foo (project name) schema for Flask extensions - maybe it's worth mentioning in this PEP as well.

[Benoît Bryon, 2012-06-29]

Le 28/06/2012 14:15, Piotr Ozarowski a écrit :

...

[Benoît Bryon, 2012-06-27]

...

http://hg.python.org/peps/file/52767ab7e140/pep-0423.txt

I think PEP 386 (about versions) should be mentioned in "Relationship with other PEPs" section.

Why? Right now, I can't see the relationship between projects/packages/modules names and versions.

The PEP name is "Naming conventions and recipes related to packaging" and version numbers are related to packaging (and naming) for sure.

How about PEP 396 (Module Version Numbers)?

...

About "Use a single name" section: sometimes one needs to add "python-" or "py" prefix to project name (f.e. if the name is already used in other programming languages and you cannot register it in your favourite forge hosting service)... but please don't add the prefix also in namespace. All these PyQts, pyudevs, pygames and pyopencls sound stupid to me (isn't it obvious that when I do `import foo` in Python, "foo" is a *Python* library?)

Do you mean:

• "pip install pyqt" => yes,
• "import pyqt" => no,
• "import qt" => yes?

right

Currently, if the project name is "pyqt", then the PEP proposal recommends "pip install pyqt" and "import pyqt", to make the name consistent. If one is not a good choice, change both. It is convention over configuration.

that's my point, PyQt guys cannot use Qt as project name, but "qt" it a better name for this namespace, IMO

IMHO, a "py" prefix for package name would not be a problem in this case. You are not importing Qt itself, but Python bindings for Qt.

it's not "a problem", I just think PEP should not recommend such prefixes

I mean, yes, it is obvious that when I do `import foo` in Python, then "foo" is a *Python* library. But would the reverse assertion be that if I see "import qt" in Python code, then it is obvious that Qt itself is a Python library?

There's a "readline" package in Python's stdlib, does it imply readline is something Python related or specific?

The name could have been "qtbindings", would have it been a problem then? The "py" prefix has the advantage to be clear: that's *Python* bindings for Qt. And it's a really short prefix.

qtbindings, qtlib or other similar prefixes/suffixes should not be recommended, IMHO

...

About ".contrib.": flask uses flask.ext.foo (namespace) and Flask-Foo (project name) schema for Flask extensions - maybe it's worth mentioning in this PEP as well.

Maybe it will be used in discussions or in examples, but I suppose the PEP is not the place to list all project-specific conventions. Currently the draft PEP tells: "search for specific conventions in main project (Flask) documentation".

I just thought "foo.ext.bar" is a nice convention worth mentioning (next to, not instead of "contrib" which is more general than "ext")

May package names contain hyphen (-)?

Le 29/06/2012 18:01, Paul Moore a écrit :

On 29 June 2012 15:34, Daniel Holthdholth@gmail.com wrote:

...

May package names contain hyphen (-)?

Package or distribution? Package, no because it has to be a valid Python identifier. Distribution, I'm not sure - there are funny rules to allow for things like parsing dist-info directory names, or egg filenames, unambiguously. One of the packaging PEPs would probably answer this one.

Paul.

In package/module names, as Paul said, you can't use hyphens.

About project names, currently, the draft PEP recommends using the same value for distributed module/package name and for project name. The consequence is: PEP 8 applies to project names too, which means "no hyphens" in project names (and many other rules). The exception is the dot symbol, required to create namespace packages.

Benoit

On 29 June 2012 14:05, Benoît Bryon benoit@marmelune.net wrote:

I agree that "foo.ext.bar" seems nice... but it uses 3 namespace levels. It breaks the "avoid deep nesting" rule, which recommends not more than two levels. So the PEP can't recommend this pattern, or we will also have to reconsider the "avoid deep nesting" rule.

??? I thought the PEP was about distribution naming (i.e., things published on PyPI. If the package "foo" is published under that name on PyPI, I see no reason it can't (good taste permitting) use multi-level names like foo.bar.baz internally. That's a completely different question than whether a distribution named foo.bar.baz should be available for download from PyPI (presumably alongside foo.bar.bip and foo.bop.boop...)

Maybe I'm misunderstanding the conversation here. We need to be *extremely* precise about the differences between distributions (things published to somewhere like PyPI, which can be installed independently, and have a version number, etc) and packages (which are things you import in Python). I've been just as vague as everyone else in this thread, so I'm not trying to blame anyone. But things are definitely getting muddled.

Paul.