On 16 July 2013 23:39, R. David Murray <rdmurray@bitdance.com> wrote:
On Tue, 16 Jul 2013 23:19:21 +1000, Steven D'Aprano <steve@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@gmail.com | Brisbane, Australia