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

[R. David Murray]

On Tue, 16 Jul 2013 23:19:21 +1000, Steven D'Aprano <steve at pearwood.info> wrote:
> On 16/07/13 20:28, Richard Oudkerk wrote:
> > On 16/07/2013 6:44am, Nick Coghlan wrote:
> >> Clarifying what constitutes an internal interface in a way that
> >> doesn't require renaming anything is a necessary prerequisite for
> >> bundling or bootstrapping the pip CLI in Python 3.4 (as pip exposes
> >> its internal implemetnation API as "import pip" rather than "import
> >> _pip" and renaming it would lead to a lot of pointless code churn).
> >> Without that concern, the topic never would have come up.
> >
> > BTW, how does the use of __all__ effect things?  Somewhere I got the idea that if a module uses __all__ then anything not listed is internal.  I take it that is wrong?
> 
> 
> That is not how I interpret __all__. In the absence of any explicit documentation, I interpret __all__ as nothing more than a list of names which wildcard imports will bring in, without necessarily meaning that other names are private. For example, I might have a module explicitly designed for wildcard imports at the interactive interpreter:
> 
> from module import *
> 
> brings in the functions which I expect will be useful interactively, not necessarily the entire public API.
> 
> For example, pkgutil includes classes with single-underscore methods, which I take as private. It also has a function simplegeneric, which is undocumented and not listed in __all__. In in the absence of even a comment saying "Don't use this", I take it as an oversight, not policy that simplegeneric is private.

I think you'd be wrong about that, though.  simplegeneric should really be
treated as private.  I'm speaking here not about the general principle of
the thing, but about my understanding of simplegeneric's specific history.

--David