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

[Brett Cannon]

On Sun, Jul 14, 2013 at 7:09 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:

> 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).
> =================
>

+1
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130714/a04efc65/attachment.html>