diff -r 7c185dda44ac pep-0008.txt --- a/pep-0008.txt Fri Jun 28 19:32:40 2013 -0700 +++ b/pep-0008.txt Wed Oct 23 14:05:19 2013 -0700 @@ -496,20 +496,28 @@ any other code, separated by a blank lin Naming Conventions ================== The naming conventions of Python's library are a bit of a mess, so we'll never get this completely consistent -- nevertheless, here are the currently recommended naming standards. New modules and packages (including third party frameworks) should be written to these standards, but where an existing library has a different style, internal consistency is preferred. +Overriding Principle +-------------------- + +Whenever names are visible to the user as public parts of the API the +naming convention should reflect usage rather than implementation. +An internal change (for example switching from a factory function to a +class) should never affect the names used in the public API. + Descriptive: Naming Styles -------------------------- There are a lot of different naming styles. It helps to be able to recognize what naming style is being used, independently from what they are used for. The following naming styles are commonly distinguished: - ``b`` (single lowercase letter) @@ -592,22 +600,36 @@ but it may be a problem when the code is Windows versions, or DOS. When an extension module written in C or C++ has an accompanying Python module that provides a higher level (e.g. more object oriented) interface, the C/C++ module has a leading underscore (e.g. ``_socket``). Class Names ~~~~~~~~~~~ -Almost without exception, class names use the CapWords convention. -Classes for internal use have a leading underscore in addition. +Class names should normally use the CapWords convention, with classes +intended solely for internal use starting with a leading underscore. + +This guideline should always be followed for abstract base classes, +any other classes where inheritance is encouraged, and classes that +are paired with a separate factory function. + +In cases where inheritance is not encouraged and it is judged to +improve readability at the point of use, the naming convention for +callables (lower_case_with_underscores) may be used instead. This is +an indication that the type is intended primarily for use "as is", +rather than through inheritance (although subclassing is still permitted). + +Note that there is a separate convention for builtin names: most builtin +names are single words (or two words run together), with the CapWords +convention used only for exception names and builtin constants. Exception Names ~~~~~~~~~~~~~~~ Because exceptions should be classes, the class naming convention applies here. However, you should use the suffix "Error" on your exception names (if the exception actually is an error). Global Variable Names ~~~~~~~~~~~~~~~~~~~~~