Re: [Python-Dev] PEP 423 : naming conventions and recipes related to packaging
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 Bryonben...@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 PEP: 423 Title: Naming conventions and recipes related to packaging Version: $Revision$ Last-Modified: $Date$ Author: Benoît Bryon ben...@marmelune.net Discussions-To: distutils-...@python.org Status: Deferred Type: Informational Content-Type: text/x-rst Created: 24-May-2012 Post-History: 5-Jul-2013 Abstract This document deals with: * names of Python projects, * names of Python packages or modules being distributed, * namespace packages. It provides guidelines and recipes for distribution authors: * new projects should follow the `guidelines #overview`_ below. * existing projects should be aware of these guidelines and can follow `specific recipes for existing projects #how-to-apply-naming-guidelines-on-existing-projects`_. PEP Deferral Further consideration of this PEP has been deferred at least until after PEP 426 (package metadata 2.0) and related updates have been resolved. Rationale: issues related to names == For a long time, there have been no official reference on the how to choose names topic in the Python community. As a consequence, the Python package index (`PyPI`_) contains many naming patterns. The fact is that this heterogeneity causes some issues. Some of them are described below. .. note:: Examples were taken on July 2013. Naming things is a hard task, and naming Python projects or packages is not an exception. The purpose of this PEP is to help project authors to avoid common traps about naming, and focus on valuable things. Clashes --- Projects names are unique on `PyPI`_. But names of distributed things (packages, modules) are not. And there are clashes. As an example, pysendfile and django-sendfile projects both distribute a sendfile package. Users cannot use both in an environment. Deep nested hierarchies --- Deep nested namespaces mean deep nested hierarchies. It obfuscates valuable project contents. As an example, with plone.app.content you get a deeply nested directory hierarchy: .. code:: text plone/ └── app/ └── command/ └── ... valuable code is here... Whereas, with flat packages like sphinx, you have valuable code near the top-level directory: .. code:: text sphinx/ └── ... valuable code is here... Unrelated namespaces When project names are made of nested namespaces, and these namespaces are not strongly related, then there is confusion. As an example, it is not obvious that zc.rst2 project is a general Python project, not tied to zc (Zope Corporation), but related to docutils' reStructuredText. As a consequence, some users discard zc.rst2 project, because they think
Re: [Python-Dev] PEP 423 : naming conventions and recipes related to packaging
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 ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] PEP 423 : naming conventions and recipes related to packaging
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 ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] PEP 423 : naming conventions and recipes related to packaging
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 ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] PEP 423 : naming conventions and recipes related to packaging
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 ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] PEP 423 : naming conventions and recipes related to packaging
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 distutils-...@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:distutils-...@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 p...@python.org... Regards, Benoit (benoitbb on irc.freenode.net) ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
