[Python-Dev] Breaking undocumented API (original) (raw)

Nick Coghlan ncoghlan at gmail.com
Thu Nov 11 15:02:58 CET 2010

On Thu, Nov 11, 2010 at 11:39 PM, Tres Seaver <tseaver at 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   |   ncoghlan at gmail.com   |   Brisbane, Australia

More information about the Python-Dev mailing list