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

[Nick Coghlan]

On 15 July 2013 17:31, Terry Reedy <tjreedy at udel.edu> wrote:
> I do not think absence of documentation is a good signal. I would rather say
> that any private or partially private package that does not have a _ name
> *must* have a docstring saying that it is all or mostly  private. (Or be a
> subpackage or module of something so marked.) And presuming that it is
> associated with something that is documented, then the doc should state that
> the implementation files are private.
>
> In other words, I suggest that "modules that are not explicitly covered in
> the documentation ... [whose] names do not start with a leading underscore"
> should be empty. And I think "even if they include a module level
> documentation string." is backwards. Such files *should* have a docstring
> that serves as a substitute for a _ prefix.

I (now) agree - a disclaimer in the docstring is a better signal than
an absence of documentation, and one we can reasonably make a
requirement even for external applications that we bundle or otherwise
bless as the "obvious way to do it" (as is happening with pip).

=================
Private interfaces

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.

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

--
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia