[Python-Dev] Tweaking PEP 8 guidelines for use of leading underscores

[Nick Coghlan]

On 14 July 2013 18:11, Nick Coghlan <ncoghlan at 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).
=================



-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130714/3017dc71/attachment.html>