On Sun, Jul 14, 2013 at 7:09 AM, Nick Coghlan <ncogh...@gmail.com> wrote:
> On 14 July 2013 18:11, Nick Coghlan <ncogh...@gmail.com> wrote: > >> Currently, the naming section of PEP 8 doesn't say very much about what a >> leading underscore *means* in the Python standard library. >> >> I would like to add a new "Private interfaces" subsection under "Naming >> Conventions" to say the following: >> >> ================= >> Private interfaces >> >> Unless explicitly documented otherwise, a leading underscore on any name >> indicates that it is an internal implementation detail and backwards >> compatibility guarantees do not apply. It is strongly encouraged that >> private APIs (whether modules, classes, functions, attributes or other >> names) be clearly marked in this way, as many Python users rely on >> introspection to identify available functionality and may be mislead into >> believing an API without the leading underscore is in fact a public API >> with the standard backwards compatibility guarantees. >> >> All test modules are also considered private interfaces. >> >> Even though they typically lack the leading underscore, modules imported >> by another module are also considered an implementation detail. Other >> modules *should* not rely on indirect access to such modules unless they >> are an explicitly documented part of the API (such as ``os.path``). >> ================= >> > > Slight adjustment to the proposed wording to ensure completely > undocumented modules are also considered private: > > ================= > Private interfaces > > Unless explicitly documented otherwise, a leading underscore on any name > indicates that it is an internal implementation detail and backwards > compatibility guarantees do not apply. It is strongly encouraged that > private APIs (whether modules, classes, functions, attributes or other > names) be clearly marked in this way, as Python users may rely on > introspection to identify available functionality and may be misled into > believing an API without a leading underscore is in fact a public API with > the standard backwards compatibility guarantees. > > Even when their names do not start with a leading underscore, all test > modules and all modules that are not covered in the documentation are also > considered private interfaces. > > Similarly, the specific modules and external APIs imported by a module are > always considered an implementation detail. Other modules should not rely > on indirect access to such imported interfaces unless they are an > explicitly documented part of the containing module's API (such as > ``os.path`` or a package ``__init__`` module exposing functionality from > submodules). > ================= > +1
_______________________________________________ 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
