[Python-Dev] Breaking undocumented API

[Alexander Belopolsky]

On Wed, Nov 17, 2010 at 8:30 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:
..
> The library documentation is *not* the right place for quibbling about
> what constitutes a public API when using other means than the library
> documentation to find APIs to call.
>
+1

People who bother to read the Library Reference most likely already
know that it is the authoritative source.  People who read the sources
or use deep introspection most likely know that they are walking on
thin ice.   The only grey area is help() and dir().  Unfortunately may
novice guides recommend using these tools for learning as follows:

>>> L = []
>>> dir(L)
['append', 'count', 'extend', 'index', 'insert', 'pop', 'remove',
'reverse', 'sort']
>>> help(L.append)
Help on built-in function append:
...

See http://docs.python.org/faq/general.html#is-python-a-good-language-for-beginning-programmers

Given the quirkiness of dir(), this is probably not the best practice.
 For the standard library however,

>>> help('module')

or

$ pydoc module

already refer users to the official manual.  Unfortunately this
feature is slightly broken in 3.x (the link takes you to 2.x
documentation instead of 3.x).

I have opened a bug report about this,
http://bugs.python.org/issue10446, and would like to add a sentence or
two to the "MODULE DOC" section explaining the differences between the
auto-generated docs and the official manual.

We may also revisit the rules used by help() to decide what to include
on the auto-generated module implementation.  Note that currently
help() output excludes names not in __all__ is the module has __all__
defined.  While I advocated this rule earlier in this thread, I now
realize that it may not be quite practical.  Consider the recent
addition of open() to the tokenize module.  It was documented in the
manual, but (wisely) excluded from tokenize.__all__.

It appears that this discussion is converging to the conclusion that
public API = documented in the reST manual.  An unfortunate
consequence is that it is not easy to discover public API
programmatically.  However, "not easy" does not mean "impossible."
ReST documentation is highly structured and Sphinx already generates
various indices that can be easily queried.  Maybe some of these
indices should be distilled into something compact and made available
to pydoc by the build process.  This would allow help(anyobject)
display a deep link to the official documentation or a warning that
anyobject is undocumented.