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

[Gregory P. Smith]

+1  This is already how we've been behaving for years.


On Sun, Jul 14, 2013 at 4: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:
>>
>>
> 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,
>

<snip>


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

While true, I'm not sure the last part of the sentence is necessary. Once
we've established that a leading _ indicates something is private there
isn't much point in explaining the various ways people might find them.
 I'm happy regardless of this bit being there.


> 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).
> =================
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130714/4ac29086/attachment.html>