diff -r 62f9d56b645a pep-0008.txt --- a/pep-0008.txt Sun Jul 14 23:29:39 2013 +1000 +++ b/pep-0008.txt Tue Jul 16 22:41:51 2013 +1000 @@ -4,11 +4,12 @@ Last-Modified: $Date$ Author: Guido van Rossum , Barry Warsaw + Nick Coghlan Status: Active Type: Process Content-Type: text/x-rst Created: 05-Jul-2001 -Post-History: 05-Jul-2001 +Post-History: 05-Jul-2001, 17-Jul-2013 Introduction @@ -23,6 +24,10 @@ Guido's original Python Style Guide essay, with some additions from Barry's style guide [2]_. +This style guide evolves over time as additional conventions are identified +and past conventions are rendered obsolete by changes in the language +itself. + A Foolish Consistency is the Hobgoblin of Little Minds ====================================================== @@ -41,7 +46,7 @@ judgment. Look at other examples and decide what looks best. And don't hesitate to ask! -Two good reasons to break a particular rule: +Three good reasons to break a particular rule: 1. When applying the rule would make the code less readable, even for someone who is used to reading code that follows the rules. @@ -50,6 +55,11 @@ for historic reasons) -- although this is also an opportunity to clean up someone else's mess (in true XP style). +3. Because the code in question predates the introduction of the rule and + there is no other reason to be modifying that code (especially if + conforming to the updated style guide risks breaking backwards + compatibility) + Code lay-out ============ @@ -132,9 +142,13 @@ Never mix tabs and spaces. The most popular way of indenting Python is with spaces only. The -second-most popular way is with tabs only. Code indented with a -mixture of tabs and spaces should be converted to using spaces -exclusively. When invoking the Python command line interpreter with +second-most popular way is with tabs only. In Python 3, these are the +only two permitted options (mixing them will raise an error). + +Code indented with a mixture of tabs and spaces should be converted to +using spaces exclusively. + +When invoking the Python 2 command line interpreter with the ``-t`` option, it issues warnings about code that illegally mixes tabs and spaces. When using ``-tt`` these warnings become errors. These options are highly recommended! @@ -269,8 +283,10 @@ - Relative imports for intra-package imports are highly discouraged. Always use the absolute package path for all imports. Even now that PEP 328 is fully implemented in Python 2.5, its style of explicit - relative imports is actively discouraged; absolute imports are more - portable and usually more readable. + relative imports is still discouraged; absolute imports are usually + more readable and tend to be better behaved (or at least give better + error messages) if the import system is incorrectly configured (such as + a directory inside the package ending up on ``sys.path``). - When importing a class from a class-containing module, it's usually okay to spell this:: @@ -285,6 +301,13 @@ and use "myclass.MyClass" and "foo.bar.yourclass.YourClass". +- Wildcard imports (``from import *``) should be avoided, as they + make it unclear which names are present in the namespace, confusing both + readers and many automated tools. There is one defensible use case for + a wildcard import, which is to republish an internal interface as part + of a public API (for example, overwriting a pure Python implementation of + an interface with the definitions from an optional accelerator module). + Whitespace in Expressions and Statements ======================================== @@ -760,6 +783,36 @@ advanced callers. +Public and internal interfaces +------------------------------ + +Any backwards compatibility guarantees apply only to public interfaces. +Accordingly, it is important that users be able to clearly distinguish +between public and internal interfaces. + +Documented interfaces are considered public, unless the documentation +explicitly declares them to be provisional or internal interfaces exempt +from the usual backwards comaptibility guarantees. All undocumented +interfaces should be assumed to be internal. + +To better support introspection, modules should explicitly declare the +names in their public API using the ``__all__`` attribute. Setting +``__all__`` to an empty list indicates that the module has no public API. + +Even with ``__all__`` set appropriately, internal interfaces (packages, +modules, classes, functions, attributes or other names) should still be +prefixed with a single leading underscore. + +An interface is also considered internal if any containing namespace +(package, module or class) is considered internal. + +Imported names should always be considered an implementation detail. Other +modules must not rely on indirect access to such imported names unless they +are an explicitly documented part of the containing module's API, such as +``os.path`` or a package's ``__init__`` module that exposes functionality +from submodules. + + Programming Recommendations ===========================