On Wed, Nov 17, 2010 at 8:30 AM, Nick Coghlan <ncogh...@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. _______________________________________________ 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
