On 16 July 2013 23:39, R. David Murray <rdmur...@bitdance.com> wrote: > On Tue, 16 Jul 2013 23:19:21 +1000, Steven D'Aprano <st...@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 | ncogh...@gmail.com | Brisbane, Australia _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
