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

[Barry Warsaw]

Working from what I think is the latest version.

In general, i'd rather be prescriptive of future conventions than descriptive
of current conventions.  It's okay to exempt existing code, and as a general
rule we've never been fond of rewriting existing code to update it to new
standards or APIs.  We don't need to do so here either.

On Jul 15, 2013, at 05:48 PM, Nick Coghlan wrote:

>Private interfaces

"Internal" or "Non-public"

>Unless explicitly documented otherwise, a leading underscore on any
>name indicates that it is an internal implementation detail and any
>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.

How about:

"All internal interfaces (modules, classes, functions, attributes or other
names) should be prefixed with a single leading underscore.  Such names are
internal implementation details for which no backward compatibility guarantees
are made, unless otherwise specified.

Existing code and other narrowly accepted exceptions may override this
recommendation, in which case the docstrings and/or documentation for such
code must clearly and explicitly state the internal status of the APIs.

Imported names should always be considered an implementation detail.  Other
modules must not rely on indirect access to such imported names unless they
are an explicitly documented part of the containing module's API, such as
``os.path`` or a package's ``__init__`` module that exposes functionality from
submodules.  Public names exported by a module should be include in the
module's ``__all__`` attribute."

>While the explicit use of a leading underscore is the preferred solution,
>the names of some private (or partially private) modules (such as ``test``
>and ``idlelib``) lack the leading underscore either for historical reasons
>or because they expose a public command line interface through the
>``-m`` switch. Such modules should include an explicit disclaimer in
>their module docstring, indicating that they do not use the leading
>underscore convention and noting where the definition of the public
>API (if any) can be found (the public API definition may also be part
>of the module docstring).
>
>As a general principle, 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 that exposes functionality
>from submodules).

Cheers,
-Barry