[Python-Dev] PEP 423 : naming conventions and recipes related to packaging

[Benoît Bryon]

Let's try to summarize answers about top-level namespace with use cases
and examples... I hope I understood them well...

About "yes" or "no" meaning:

yes
   It fits the (work-in-progress) convention. You would
   recommend it.

no
   You wouldn't recommend the naming pattern for *new*
   projects (we can't require existing projects to be renamed).

=====

Project is standalone (doesn't mean "have no dependencies"),
released on PyPI:

* only one-level name is recommended, no namespace package
* yes: sphinx, flask, lettuce
* no: zc.rst2 (brand name is superfluous)

=====

Project is made of several subprojects which are not
standalone, released on PyPI:

* a namespace package is recommended

* the top-level namespace is functional: projects in
   namespace make a bigger project. They are not designed
   to work as standalone components.

* yes: ? Have you examples of such a use case?

* no: plone.app.* (too many levels)

=====

Project is related to another one (i.e. kind of contrib),
released on PyPI:

* note: there is a difference between "related to another
   project" and "depends on another project". As an example,
   Fabric depends on ssh, but is not a contrib of it.

* choice depends on conventions of related project

* if there is no specific convention, a namespace package
   is recommended

* the top-level namespace is functional: projects in
   namespace have a common characteristic, they are specific
   to something, usually another project.

* yes: collective.castle

* yes because of explicit specific convention: sphinxcontrib-feed,
   Flask-Admin

* no: castle, feed, admin, Plone.recipe.command (not specific
   to Plone, in fact related to zc.buildout)

* Use of additional metadata is highly recommended (keywords,
   topic::framework)

=====

Project is standalone, but really experimental (i.e.
name could change, not sure to publish version 0.2),
want to make it public:

* I want to share code, but I am really not sure it will
   live long. I don't want to "block" a name slot.

* use a one-level name, as any standalone public project

* publish it on gitorious/github/bitbucket accounts

* don't register it with PyPI until it becomes a bit
   mature? i.e. start with code repositories only?

* not valuable enough to be mentioned in PEP 423?
   Maybe not in the scope of PEP 423. I mean it is more
   about "what kind of projects we register with PyPI"
   than "which name to choose".

=====

Project is standalone, but specific to my own usage, i.e.
I use it as personal software. It's not private because
I want to share the code (maybe someone will like it).

* use an one-level name, as any standalone public project

* publish it on code repositories.

* register it with PyPI? if only ready to maintain and
   document?

* not valuable enough to be mentioned in PEP 423?
   Maybe not in the scope of PEP 423. I mean it is more
   about "what kind of projects we register with PyPI"
   than "which name to choose".

=====

.. note::

    conventions for private projects are provided as
    informational guidelines.


Project is private, made of only one component:

* a namespace package is recommended (not sure for this
   rule, could be an one-level project name)

* the top-level name can be any unique arbitrary value.
   The company name could be a good choice.

* the top-level namespace is not functional, but represents
   an ownership: the project is specific to the customer/product.
   It contains closed-source parts.

* yes: mycustomer.website

* no: mycustomerwebsite, website

=====

Project is private, made of several components:

* a namespace package is recommended

* the top-level name can be any unique arbitrary value.
   The company name could be a good choice.

* the top-level namespace is not functional, but represents a
   common background: as an example, all components are specific
   to the customer/product.

* yes: mywebsite.blog, mywebsite.auth, mywebsite.calendar (where
   these components could be standalone WSGI applications, but
   contain specific stuff related to the customer/product).

* no: blog, auth, calendar


=====

Do you prefer the examples above to the "top-level namespace relates to code ownership" rule?
Do you see other use cases?


Benoit