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

[Nick Coghlan]

On 16 July 2013 23:39, R. David Murray <rdmurray at bitdance.com> wrote:
> 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.

And, indeed, you're correct (the issue that eventually became the
functools.singledispatch PEP started life with a title like "move
simplegeneric to functools and make it public").

For the general case, the patch I posted to the issue tracker sets the
precedence as docs -> __all__ -> leading underscore. If a module has
public APIs that aren't in __all__, it should cover them in the docs,
otherwise people should assume they're private. It's OK if there are
exceptions to that general rule - there's a reason PEP 8 has the great
big qualifier pointing out that it isn't universally applicable (even
if we might sometimes wish otherwise).

Cheers,
Nick.

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