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

[Chris McDonough]

On 06/28/2012 06:36 AM, Benoît Bryon wrote:
> 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)."


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