On Thu, Nov 11, 2010 at 11:39 PM, Tres Seaver <tsea...@palladion.com> wrote: > I would argue that the narrative documentation for the module is > normative for defining "public API", trumping even a pre-existing > '__all__'. Given that all non-private stdlib modules have such docs, > nobody should be relying on '__all__' as anything other than a convenience. > > Therefore, in the absence of an '__all__', adding one which conforms to > the docs should not require deprecations, as the set of applications / > modules which both use the undocumented names *and* do so via 'import *' > can be safely deemed "too small to worry about".
Except, as noted earlier in the thread, many Python programmers (and I count myself amongst this group) often use dir() and help() to find out what a module has available, and only resort to the written documentation if we get stuck. My personal opinion is that we should be trying to get the standard library to the point where __all__ definitions are unnecessary - if a name isn't in __all__, it should start with an underscore (and if that is true, then the __all__ definition becomes effectively redundant). That way, all sources of information (docs, dir(), help(), import *) give the same answer as to what constitutes the public API. 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
