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

[Steven D'Aprano]

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.



-- 
Steven