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

[Benoît Bryon]

Hi,

Here is an informational PEP proposal:
http://hg.python.org/peps/file/52767ab7e140/pep-0423.txt

Could you review it for style, consistency and content?


Additional notes:

* Original discussion posted to distut...@python.org

* started on May 2012 at
http://mail.python.org/pipermail/distutils-sig/2012-May/018551.html

* continues in June 2012 at
http://mail.python.org/pipermail/distutils-sig/2012-June/018641.html

* that's why I set "Discussion-To:<distut...@python.org>"
header.

* Original document was edited as a contrib to cpython documentation:

* http://bugs.python.org/issue14899
* file history at
https://bitbucket.org/benoitbryon/cpython/history/Doc/packaging/packagenames.rst
* but it looked like a PEP, so posted to pe...@python.org...


Regards,
Benoit (benoitbb on irc.freenode.net)

_______________________________________________
Python-Dev mailing list
Pytho...@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/dev-python%2Bgarchive-30976%40googlegroups.com

[Antoine Pitrou]

Hello,

On Wed, 27 Jun 2012 11:08:45 +0200
Benoît Bryon <ben...@marmelune.net> wrote:
> Hi,
>
> Here is an informational PEP proposal:
> http://hg.python.org/peps/file/52767ab7e140/pep-0423.txt
>
> Could you review it for style, consistency and content?

There is one Zen principle this PEP is missing:

Flat is better than nested.

This PEP seems to promote the practice of having a top-level namespace
denote ownership. I think it should do the reverse: promote
meaningful top-level packages (e.g. "sphinx") as standard practice, and
allow an exception for when a piece of software is part of a larger
organizational body.

(i.e., "Community-owned projects can avoid namespace packages" should
be the first item in the PEP and renamed so that it appears common rule)

I don't think we want a Java-like landscape where everyone operates
behind their closed fences à la org.myorganization.somecommunity and
where package names shout "ownership" rather than "functionality". (*)

Also, do note that "packaging" is ambiguous in Python-land.


(*) (for the record, companies internally can do what they want; this
PEP AFAICT addresses the case of publicly released packages)

Regards

Antoine.

[Nick Coghlan]

I thought the PEP actually covered it pretty well:
- if you don't want to worry about name conflicts for every module, pick *one* short top level namespace for your group and use that
- for shared modules, use the top level namespace with PyPI as the name registry

It's reasonable advice when coupled with the "avoid more than two levels of nesting - when tempted by this, split out some peer modules" elsewhere in the doc.

[Antoine Pitrou]

On Wed, 27 Jun 2012 21:19:57 +1000
Nick Coghlan <ncog...@gmail.com> wrote:
> I thought the PEP actually covered it pretty well:
> - if you don't want to worry about name conflicts for every module, pick
> *one* short top level namespace for your group and use that
> - for shared modules, use the top level namespace with PyPI as the name
> registry

That's not very clear to me when reading the PEP.
For example, one of the items in the "overview" is "use top-level
namespace for ownership". I don't think it should be, unless we want to
promote such a practice.

Similarly, I think the section about private projects ("Private
(including closed-source) projects use a namespace") should be removed.
It is not our duty to promote naming standards for private (i.e.
internal) projects. Also, I don't see what's so important about using
your company's name as a top-level namespace. You don't need it for
conflict avoidance: you can just as well use distinctive project names.

[Paul Moore]

On 27 June 2012 12:34, Antoine Pitrou <soli...@pitrou.net> wrote:
> On Wed, 27 Jun 2012 21:19:57 +1000
> Nick Coghlan <ncog...@gmail.com> wrote:
>> I thought the PEP actually covered it pretty well:
>> - if you don't want to worry about name conflicts for every module, pick
>> *one* short top level namespace for your group and use that
>> - for shared modules, use the top level namespace with PyPI as the name
>> registry
>
> That's not very clear to me when reading the PEP.
> For example, one of the items in the "overview" is "use top-level
> namespace for ownership". I don't think it should be, unless we want to
> promote such a practice.

I agree. I only skimmed the PEP, but even on a skimming, I got the
impression that it was promoting the use of namespaces for ownership,
in a Java-like way. The part Nick quoted is substantially more
reasonable (assuming that's a direct quote, rather than Nick's
summarisation) but the principle should be made clear right at the
top.

I'd say that a headline item should be something like;

Using namespaces:
- "Flat is better than nested" - where possible, use a single
top-level name for your package (check on PyPI that the name you
choose isn't in use).
- Where you expect to have multiple packages all relating to the same
top-level functionality, it may make sense to use a single top-level
namespace package, and put your packages underneath that.
- There should never be a need to use more than one level of
namespace (if you think there is, you should probably promote each of
the level-2 namespaces.to the top level).
- Namespaces (and package names) should always be based on
functionality, never on ownership[1].

Personal or private code doesn't need to follow these guidelines, but
be aware that personal code often ends up more widely used than
originally envisaged...

[1] Sorry, Barry. There clearly needs to be an exception for the flufl
namespace :-)

Paul.

[Paul Moore]

On 27 June 2012 13:20, Paul Moore <p.f....@gmail.com> wrote:
> I agree. I only skimmed the PEP, but even on a skimming, I got the
> impression that it was promoting the use of namespaces for ownership,
> in a Java-like way. The part Nick quoted is substantially more
> reasonable (assuming that's a direct quote, rather than Nick's
> summarisation) but the principle should be made clear right at the
> top.

Reading in a bit more depth, I'd say that I specifically disagree with
this section:

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

This helps avoid clashes between project names.

Ownership could be:

* an individual.
[...]
* an organization.
[...]
* a group or community.
[...]
* a group or community related to another package.
"""

I'd say a top-level namespace should *never* (hello again, Barry!)
relate to an individual. And never to an organisation either, the
Django case notwithstanding. In the case of Django, I see the
top-level namespace as belonging to the *software* Django, not to the
*organisation*, the Django foundation. In fact, with the exception of
the "an individual" case, I'd say all of the others are actually
referring to the software rather than the organisation/group/community
owning that project.

To be honest, I see this whole section as misguided - the top-level
namespace is the project. Simple as that. Oh, and the terminology is
further muddled here, as the "top level namespace" is usually not a
namespace package in the sense of PEP 420.

Generally, the impression I get is that the PEP is recommending more
levels of nesting than I would agree with: But it's hard to be sure,
because the concept of nesting feels a bit overloaded. The key for me
is that generally, I like to be able to type "import X" where X is not
a dotted name, and then refer to X.x1, X.x2, etc. I'd call that no
levels of nesting, to be honest. For complex stuff, subpackages
("import X.Y") might be needed, but that's rare (and even then, key
names should be exposed directly from X).

Paul.

PS Having said all this, I don't maintain any code on PyPI - I'm a
user not a producer. That may affect my perspective...

[Yury Selivanov]

On 2012-06-27, at 10:57 AM, Paul Moore wrote:

> Generally, the impression I get is that the PEP is recommending more
> levels of nesting than I would agree with: But it's hard to be sure,
> because the concept of nesting feels a bit overloaded. The key for me
> is that generally, I like to be able to type "import X" where X is not
> a dotted name, and then refer to X.x1, X.x2, etc. I'd call that no
> levels of nesting, to be honest. For complex stuff, subpackages
> ("import X.Y") might be needed, but that's rare (and even then, key
> names should be exposed directly from X).

Why instead of writing 'import project' you don't want to write
'from acme import project'?

With python adoption (enterprise too) growing, we will inevitably
find out that one single namespace (PyPI) is not enough, and
name collisions will become a frequent headache.

-
Yury

[PJ Eby]

On Wed, Jun 27, 2012 at 10:57 AM, Paul Moore <p.f....@gmail.com> wrote:

For complex stuff, subpackages
("import X.Y") might be needed, but that's rare (and even then, key
names should be exposed directly from X).

Paul.

PS Having said all this, I don't maintain any code on PyPI - I'm a
user not a producer. That may affect my perspective...

That, and if you don't work with web stuff or networking stuff.  Things having lots of subpackages are quite the rule there.

Also, functional naming for top-level modules is actually an anti-pattern: an invitation to naming conflicts, especially with future stdlib contents.  Suppose two people want to write an "email" package?  Unless you jam the ownership into the name (e.g. joes_email and bobs_email), what are you supposed to do?

This is why we have popular packages with names like nose and celery and django and pyramid and lamson: because unique memorable names > functionally descriptive names.

[Benoît Bryon]

Le 27/06/2012 13:34, Antoine Pitrou a écrit :
> Similarly, I think the section about private projects ("Private
> (including closed-source) projects use a namespace") should be removed.
> It is not our duty to promote naming standards for private (i.e.
> internal) projects.

The intention in the proposed PEP is to promote standards
for general Python usage, which implicitely includes both public
and private use.

The proposed PEP tries to explain how the conventions
apply in most use cases. Public and private scopes are mentioned
explicitely because they were identified as valuable use cases.

Here are some reasons why the "private code" use case has
been identified as valuable:

* New Python developers (or more accurately new distribution
authors) may wonder "What makes a good name?", even if they are
working in a private area. Guidelines covering private code would
be welcome.

* At work, I already had discussions about naming patterns for
closed source projects. These discussions consumed some energy
made the team focus on some "less valuable" topics. We searched
for an official convention and didn't find one. We made choices
but none of us was really satisfied about it. An external
arbitration from a trusted authority would have been welcome,
even if we were making closed-source software.

* As Paul said, "personal code often ends up more widely used than
originally envisaged". So following the convention from the start
may help.

* Here, the PEP already covers (or tries to) most public code use
cases. It's quite easy to extend it to private code. I feel
drawbacks are negligible compared to potential benefits.

.. note:: IMHO, main drawback is "read this long document".

* Isn't it obvious that, at last, people do what they want to in
private code? In fact, they also do in public code. I mean the
document is an informational PEP. It recommends to apply conventions
but the actual choice is left to developers.


That said, would the changes below improve the document?

* Keep the parts about private and closed-source code, but add a
note to insist on "in private code, you obviously do what you want
to" and "be aware that personal code often ends up more widely used
than originally envisaged".

* At the beginning of the document, add a section like
http://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds


Another option would have been to deal with "general Python code"
and don't mention "public" and "private" areas, i.e. implicitely
cover both. I haven't followed this way because it is implicit.

> Also, I don't see what's so important about using
> your company's name as a top-level namespace. You don't need it for
> conflict avoidance: you can just as well use distinctive project names.

Using company's name as top-level namespace has been proven a
good practice:

* avoids clashes and confusion with public projects, i.e. don't
create a "cms" private project because there could be a "cms"
project on PyPI.

* makes it easy to release the code as open-source: don't change
the project name.

* if there is no reason at all for the project to contain the
company name (i.e. the project is not specific to the company),
why not realeasing it as open source? (with a one-level name)

Using company's name is not the only option. But, as far as I know,
it fits most use cases, which is enough (and required) for a
convention.

Another option is to use any arbitrary name as top-level namespace.
You can. If an arbitrary name seems obvious to you, feel free to
use it. But, in most cases, company's name is an obvious choice.

So, would you appreciate a change so that:

* company name is recommended as a best practice.
* but any arbitrary name can be used.

Could be something in:

1. "For private projects, use company name (or any unique arbitrary name)
as top-level namespace".

2. "For private projects, use any arbitrary name (company name is
generally a good choice) as top-level namespace".

3. "For private projects, use a top-level namespace (company name is
generally a good choice, but you can use any unique arbitrary name)."


Benoit

[Benoît Bryon]

Le 27/06/2012 12:50, Antoine Pitrou a écrit :
> There is one Zen principle this PEP is missing:
> Flat is better than nested.
>
> This PEP seems to promote the practice of having a top-level namespace
> denote ownership. I think it should do the reverse: promote
> meaningful top-level packages (e.g. "sphinx") as standard practice, and
> allow an exception for when a piece of software is part of a larger
> organizational body.

The PEP's intention is to tell what Nick described. Maybe
the words are not clear...


Notes about the order of items in the overview:

1. respect names registered on PyPI. This is a requirement.

2. adopt specific conventions if any, i.e. don't break the
rules that already exist in existing projects. This
convention makes the PEP backward compatible. It is the
first rule because, for project-related contributions, the
first action should be to read the documentation of the main
project.

3. important thing is to avoid name collisions. This is a
requirement for project names, and a strong recommendation
for package/module names.

4. use a single name. This rule simplifies the action of choosing
a name and brings consistency. If you already know how your
package/module is imported in code, you can simply use it as
project name.

5. then, we'd better make it easy to find and remember the project.
This is a strong advice.

6. then, all the points above being considered, we'd better use
flat names.

7. rules about syntax (PEP 8).

8. state about specific conventions, if any. This is the complement
of point 2.

9. ask.


Would you appreciate a reordering?
Could be something like that:

1. adopt specific conventions if any.

2. avoid name collisions.

3. you'd better use flat names.

4. you'd better make it easy to find and remember the project.

5. you'd better use a single name and distribute only one
package at a time

6. follow rules about syntax (PEP 8)

7. once you are done, state about specific choices, if any.
This is the complement of point 1.

8. if in doubt, ask.

> (i.e., "Community-owned projects can avoid namespace packages" should
> be the first item in the PEP and renamed so that it appears common rule)

I guess we could move "shared projects can use a one-level
name" before guidelines related to private projects.


Benoit

[Paul Moore]

On 28 June 2012 11:36, Benoît Bryon <ben...@marmelune.net> wrote:
>> Also, I don't see what's so important about using
>> your company's name as a top-level namespace. You don't need it for
>> conflict avoidance: you can just as well use distinctive project names.
>
> Using company's name as top-level namespace has been proven a
> good practice:

Not to me. This is what Java does, and whenever I have encountered it,
I have found it a major pain.

As an individual developer, I have no company name. The "use your
domain" option doesn't help either, as I have 3 registered domains to
my name, none of which I use consistently enough to want to use as the
definitive domain to identify "my" code forever.

What if I abandon a project, and someone else picks it up? Do they
need to change the name?

I have lots of little projects. Do they all have to sit under a single
namespace package "paul"? That's a maintenance problem, as there's no
standard namespace package facility prior to 3.3 (I don't use
setuptools, in general).

The concept of using a company/domain/personal name as the top level
raises far more questions than it answers for me...

Paul.

[Antoine Pitrou]

On Thu, 28 Jun 2012 12:35:24 +0200
Benoît Bryon <ben...@marmelune.net> wrote:
>
> Would you appreciate a reordering?
> Could be something like that:
>
> 1. adopt specific conventions if any.
>
> 2. avoid name collisions.
>
> 3. you'd better use flat names.
>
> 4. you'd better make it easy to find and remember the project.
>
> 5. you'd better use a single name and distribute only one
> package at a time
>
> 6. follow rules about syntax (PEP 8)
>
> 7. once you are done, state about specific choices, if any.
> This is the complement of point 1.
>
> 8. if in doubt, ask.

Yes, that would be better.

I think the PEP also needs to spell out the rationale better.
Also, reminding the distinction between modules, packages and
namespace packages could be useful to the reader, especially if it's
supposed to end up in the documentation.

Regards

Antoine.

[Benoît Bryon]

Le 27/06/2012 22:08, Yury Selivanov a écrit :
> With python adoption (enterprise too) growing, we will inevitably
> find out that one single namespace (PyPI) is not enough, and
> name collisions will become a frequent headache.

An argument for top-level namespace is related to PyPI
as a central place to publish Python code VS code
released in popular code repositories:

* many developers don't register projects with PyPI,
even if open source. As an example, many projects
are hosted on code repositories, such as Github.com,
and not on PyPI.

* one reason (not the only one) is that, as an individual,
publishing some "proof of concept" code at PyPI scares
me:

* it is very personal, at least at the beginning. Not
sure it is interesting.

* what if the project gets abandoned? It will remain
on PyPI and block a name slot.

* on Github, people work in a user space. All projects are
managed under the user account. Groups and companies
can use organization accounts. This scheme seems popular
and comfortable.

* on Github, people can fork projects. Project names are
not unique, but "user/organization+project name" is
unique. It seems to work well.

* sometimes, forks become more popular than original
projects. Sometimes original projects are abandoned
and several forks are active.

* Notice that distinct projects (i.e. not forks) can
have the same name, provided they are owned by distinct
users.

* Also notice that there is no deep nesting. There are
only two levels: one for the user or organization, one
for the project.

* if we consider PyPI as the unique reference and
central place to check for (public) name availability,
then shouldn't we promote registration with PyPI?

* there are other reasons why authors should register
with PyPI. As an example the ability to ``pip install
project`` without using complicated pip options.

* if many projects on Github are published on PyPI, then
what would happen? I bet that, without adequate naming
conventions, there will be many name collisions.

* so promoting top-level namespace (including individual)
can help.

* a risk is that it also becomes difficult to find a
project within PyPI. But having lots of projects in
PyPI is not the problem. The problem is more or less
related to the search. Meaningful names, memorable
names and packaging metadata are important for that
purpose. And if necessary, we will be able to improve
PyPI search engine or list/browse views.


Benoit

[Chris McDonough]

It's probably always a reasonable idea to use a brand-prefixed namespace
for *private* packages but in my experience it's almost always a bad
idea to publish any set of otherwise-unrelated packages that share a
branded namespace prefix to PyPI.

I know this because I've been involved with it at least twice with
"zope." and "repoze." brands/namespaces. The meaning of both of those
namespaces has become soft over time and both now mean basically "this
code was created by a group of people" instead of "this code is useful
under a circumstance or for a purpose". Those namespaces are both the
moral equivalent of a "garbage barge" class in development: code related
to the namespace might do anything ("zope" now means a company and two
completely different application servers; "repoze" never really meant
anything, it was always a pure brand).

People typically look for code on PyPI that solves a problem, and
branding in namespacing there is usually confusing. E.g. there are many
highly-general useful things in both the zope. and repoze. namespace
packages, but people are skittish about the meaning of the namespaces
and tend to look for a "more generic" solution. They are often right to
do so. Putting a package in a "garbage barge" namespace does make it
easy to avoid conflicts when publishing to PyPI, but it also makes it
easy to avoid doing other release management tasks like creating good
docs and making sure your package doesn't depend inappropriately on
other unrelated same-namespace packages. And even if a particular
distribution from a namespace has great docs and great release
management practices, it's often the case that the distribution is
ignored by potential consumers because it's just too hard to wade
through the meaning of the branding.

So I'd suggest that if the namespace represents a brand, the brand
should be related to a concrete bit of software (e.g. django, pyramid)
rather than a project or a company to avoid the fate of the
above-mentioned namespace. At least for *public* releases of software;
for private ones it matters a lot less.

- C

[R. David Murray]

On Thu, 28 Jun 2012 08:14:07 -0400, Chris McDonough <chr...@plope.com> wrote:
> It's probably always a reasonable idea to use a brand-prefixed namespace
> for *private* packages but in my experience it's almost always a bad
> idea to publish any set of otherwise-unrelated packages that share a
> branded namespace prefix to PyPI.
>
> I know this because I've been involved with it at least twice with
> "zope." and "repoze." brands/namespaces. The meaning of both of those
> namespaces has become soft over time and both now mean basically "this
> code was created by a group of people" instead of "this code is useful
> under a circumstance or for a purpose". Those namespaces are both the
> moral equivalent of a "garbage barge" class in development: code related
> to the namespace might do anything ("zope" now means a company and two
> completely different application servers; "repoze" never really meant
> anything, it was always a pure brand).
>
> People typically look for code on PyPI that solves a problem, and
> branding in namespacing there is usually confusing. E.g. there are many
> highly-general useful things in both the zope. and repoze. namespace
> packages, but people are skittish about the meaning of the namespaces
> and tend to look for a "more generic" solution. They are often right to

Looking at Zope mostly from the outside (I was involved with zope
development during an early stage of zope 3, but I haven't been involved
or used it for years), this matches my perception as well. The zope
namespace made some sense early on, but as the project got refactored
into more cleanly separated pieces, it ends up just getting in the way
of wider adoption of the most useful pieces.

For what it is worth, notice that perl does not use organization names,
it uses functional names.

Which languages other than Java use organizational names?

--David

[R. David Murray]

On Thu, 28 Jun 2012 12:53:47 +0200, =?ISO-8859-1?Q?Beno=EEt_Bryon?= <ben...@marmelune.net> wrote:
> Le 27/06/2012 22:08, Yury Selivanov a écrit :
> > With python adoption (enterprise too) growing, we will inevitably
> > find out that one single namespace (PyPI) is not enough, and
> > name collisions will become a frequent headache.
>

> * on Github, people work in a user space. All projects are
> managed under the user account. Groups and companies
> can use organization accounts. This scheme seems popular
> and comfortable.
>
> * on Github, people can fork projects. Project names are
> not unique, but "user/organization+project name" is
> unique. It seems to work well.
>
> * sometimes, forks become more popular than original
> projects. Sometimes original projects are abandoned
> and several forks are active.
>
> * Notice that distinct projects (i.e. not forks) can
> have the same name, provided they are owned by distinct
> users.

That is completely irrelevant. The top level name in the github case
isolates the forks only. It has nothing to do with the organization of
the *software*, only the *forks*. Within the fork, the software itself
retains the same name...that's the whole point.

--David

[Ethan Furman]

Chris McDonough wrote:
> People typically look for code on PyPI that solves a problem, and
> branding in namespacing there is usually confusing. E.g. there are many
> highly-general useful things in both the zope

When I search PyPI I ignore anything with djange, zope, etc., as I have
zero interest in pulling in a bunch of unrelated packages that I don't
need. If some of these pieces are truly stand-alone it would be nice if
they were presented that way.

~Ethan~

[Glenn Linderman]

On 6/28/2012 9:36 AM, Ethan Furman wrote:

When I search PyPI I ignore anything with djange, zope, etc., as I have zero interest in pulling in a bunch of unrelated packages that I don't need.  If some of these pieces are truly stand-alone it would be nice if they were presented that way.

+1 Precisely.

If a user wishes to install packages into "who_made_it" or "where_did_it_come_from" namespaces, and has a version of Python that supports namespaces, it would probably be a good idea for installers to easily permit that.  Then, if there are naming conflicts among packages from different sources, and they wish to use more than one "mypackage"... one from PyPI and one (or 3) from github, they can decide to name them as

mypackage (hah, this one is from PyPI and they used it first)
github.mypackage (first one from github)
github_fred.mypackage (the one by fred from github)
github_mary.mypackage (the one by mary from github)

The may choose to rename mypackage as PyPI.mypackage and github.mypackage as github_billy.mypackage to help discriminate, now that they have a need to discriminate, but that should be their choice, change versus compatibility.

Happily, it is possible to do either of the following to keep code names shorter:

import github_fred.mypackage as mypackage

import github_fred.mypackage as fredpackage

Reading JAVA code with lots of fully qualified by organization name is thoroughly confusing... it is unambiguous where the code came from, but it is also distracting when trying to understand the code, with all these long names that are irrelevant to the logic of the code.

And, of course, "mypackage" may be a set of alternative implementations of similar functionality, or it may be completely different functionalities that happen to use the same name (just as in English, when one word can have multitple definitions).

Maybe the PEP would be more useful by having it define package metadata standards such as

mypackage.__organization__ = 'The company or group or individual that created this package'
mypackage.__obtained_from__ = 'The location from which this package was obtained'

The former would be supplied by the package author; the latter would be filled in by the repository publisher (which may or may not be the same as the __organization__), or be a requirement to upload to the repository, or something along that line, so you'd know where to start a search for an updated version.

[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

[Benoît Bryon]

Hi!

Attached is a an updated proposal for PEP 423.
You can also find it online at https://gist.github.com/benoitbryon/2815051

I am attending at EuroPython 2013 in Florence. Isn't it a great
opportunity to get feedback and discuss about a PEP? I registered an
open-space session and a lightning-talk today!

Some notes about the update...

The main point that was discussed in the previous proposal was the
"top-level namespace relates to code ownership rule". Here is a quote
from Antoine Pitrou:

Le 27/06/2012 12:50, Antoine Pitrou a écrit :

> On Wed, 27 Jun 2012 11:08:45 +0200
> Benoît Bryon<ben...@marmelune.net> wrote:
>> Hi,
>>
>> Here is an informational PEP proposal:
>> http://hg.python.org/peps/file/52767ab7e140/pep-0423.txt
>>
>> Could you review it for style, consistency and content?
> There is one Zen principle this PEP is missing:
>
> Flat is better than nested.
>
> This PEP seems to promote the practice of having a top-level namespace
> denote ownership. I think it should do the reverse: promote
> meaningful top-level packages (e.g. "sphinx") as standard practice, and
> allow an exception for when a piece of software is part of a larger
> organizational body.

So, the main change in the proposal I'm sending today is the removal of
this "ownership" rule.
It has been replaced by "Use a single namespace (except special cases)".

Some additional changes have been performed, such as removal of some
sections about "opportunity" or "promote migrations". I also added a
"Rationale" section where I pointed out some issues related to naming.

The PEP has been marked as "deferred" because it was inactive and it is
partly related to PEP 426. I left this deferred state.

I am aware that some links in the PEP are broken... I will fix them
later. My very first motivation is to get feedback about the "big"
changes in the PEP. I wanted the update to be sent before
EuroPython-2013's open-space session. I guess a detailed review would be
nice anyway, for links, style, grammar...

Also, I wonder whether the PEP could be shortened or not. Sometimes I
cannot find straightforward words to explain things, so perhaps someone
with better skills in english language could help. Or maybe some parts,
such as the "How to rename a project" section, could be moved in other
documents.

Regards,

Benoît

[Markus Unterwaditzer]

In your first plone example you first use plone.app.content, but then present the directory structure of plone.app.command.

Apart from that, the PEP seems legit to me, contentwise. I think some parts are clumsily formulated, but IMO rewriting these parts wouldn't even decrease the text's length or improve readability.

-- Markus (from phone)

>------------------------------------------------------------------------

>
>_______________________________________________
>Python-Dev mailing list
>Pytho...@python.org
>http://mail.python.org/mailman/listinfo/python-dev
>Unsubscribe:

>http://mail.python.org/mailman/options/python-dev/markus%40unterwaditzer.net