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

[Chris McDonough]

On Mon, 2013-07-15 at 18:40 -0400, Barry Warsaw wrote:
> 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.

FWIW, I'm very skeptical of a PEP 8 guideline that would try to
proscribe that the "non-internal" API of a module or class would be
defined solely by a naming convention.

If what's being described here does become a rule, there is reason to
believe that future users who treat this PEP as the word-of-god (and
there are a *lot* of them; I hear from people literally every week who
want to "PEP8-ify" my code in some limited-value-added way) will be
harmed.  They'll be living in a fantasy world where every
non-underscore-prefixed thing is now a defacto API.  But I have lived in
a world where that has not been the case since 1998, and the chance that
I'll go back and change all my public code to satisfy a questionable
introspection convention is pretty slim.

- C


> 
> 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
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40plope.com