[Doc-SIG] pydoc.py (show docs both inside and outside of Python)

Ka-Ping Yee ping@lfw.org
Thu, 11 Jan 2001 08:36:36 -0800 (PST)

I'm pleased to announce a reasonable first pass at a documentation
utility for interactive use.  "pydoc" is usable in three ways:

1.  At the shell prompt, "pydoc <name>" displays documentation
    on <name>, very much like "man".

2.  At the shell prompt, "pydoc -k <keyword>" lists modules whose
    one-line descriptions mention the keyword, like "man -k".

3.  Within Python, "from pydoc import help" provides a "help"
    function to display documentation at the interpreter prompt.

All of them use sys.path in order to guarantee that the documentation
you see matches the modules you get.

To try "pydoc", download:


I would very much appreciate your feedback, especially from testing
on non-Unix platforms.  Thank you!

I've pasted some examples from my shell below (when you actually
run pydoc, the output is piped through "less", "more", or a pager
implemented in Python, depending on what is available).

-- ?!ng

"If I have seen farther than others, it is because I was standing on a
really big heap of midgets."
    -- K. Eric Drexler

skuld[1268]% pydoc -k mail
mailbox - Classes to handle Unix style, MMDF style, and MH style mailboxes.
mailcap - Mailcap file handling.  See RFC 1524.
mimify - Mimification and unmimification of mail messages.
test.test_mailbox - (no description)

skuld[1269]% pydoc -k text
textdoc - Generate text documentation from live Python objects.
collab - Routines for collaboration, especially group editing of text documents.
gettext - Internationalization and localization support.
test.test_gettext - (no description)
curses.textpad - Simple textbox editing widget with Emacs-like keybindings.
distutils.text_file - text_file
ScrolledText - (no description)

skuld[1270]% pydoc -k html
htmldoc - Generate HTML documentation from live Python objects.
htmlentitydefs - HTML character entity references.
htmllib - HTML 2.0 parser.

skuld[1271]% pydoc md5

Python Library Documentation: built-in module md5



    This module implements the interface to RSA's MD5 message digest
    algorithm (see also Internet RFC 1321). Its use is quite
    straightforward: use the new() to create an md5 object. You can now
    feed this object with arbitrary strings using the update() method, and
    at any point you can ask it for the digest (a strong kind of 128-bit
    checksum, a.k.a. ``fingerprint'') of the contatenation of the strings
    fed to it so far using the digest() method.
    new([arg]) -- return a new md5 object, initialized with arg if provided
    md5([arg]) -- DEPRECATED, same as new, but for compatibility
    Special Objects:
    MD5Type -- type object for md5 objects

    md5(no arg info)
        new([arg]) -> md5 object
        Return a new md5 object. If arg is present, the method call update(arg)
        is made.
    new(no arg info)
        new([arg]) -> md5 object
        Return a new md5 object. If arg is present, the method call update(arg)
        is made.

skuld[1272]% pydoc types

Python Library Documentation: module types



    # Define names for all type symbols known in the standard interpreter.
    # Types that are part of optional modules (e.g. array) are not listed.

skuld[1273]% pydoc abs

Python Library Documentation: built-in function abs

abs (no arg info)
    abs(number) -> number
    Return the absolute value of the argument.

skuld[1274]% pydoc repr             

Python Library Documentation: built-in function repr

repr (no arg info)
    repr(object) -> string
    Return the canonical string representation of the object.
    For most object types, eval(repr(object)) == object.

Python Library Documentation: module repr

    repr - # Redo the `...` (representation) but with limits on most sizes.


    class Repr
        repr(self, x)
        repr1(self, x, level)
        repr_dictionary(self, x, level)
        repr_instance(self, x, level)
        repr_list(self, x, level)
        repr_long_int(self, x, level)
        repr_string(self, x, level)
        repr_tuple(self, x, level)

    repr(no arg info)

skuld[1275]% pydoc re.MatchObject

Python Library Documentation: class MatchObject in re

class MatchObject
    __init__(self, re, string, pos, endpos, regs)
    end(self, g=0)
        Return the end of the substring matched by group g
    group(self, *groups)
        Return one or more groups of the match
    groupdict(self, default=None)
        Return a dictionary containing all named subgroups of the match
    groups(self, default=None)
        Return a tuple containing all subgroups of the match object
    span(self, g=0)
        Return (start, end) of the substring matched by group g
    start(self, g=0)
        Return the start of the substring matched by group g

skuld[1276]% pydoc xml    

Python Library Documentation: package xml

    xml - Core XML support for Python.


    This package contains three sub-packages:
    dom -- The W3C Document Object Model.  This supports DOM Level 1 +
    parsers -- Python wrappers for XML parsers (currently only supports Expat).
    sax -- The Simple API for XML, developed by XML-Dev, led by David
           Megginson and ported to Python by Lars Marius Garshol.  This
           supports the SAX 2 API.


skuld[1277]% pydoc lovelyspam
no Python documentation found for lovelyspam

skuld[1278]% python
Python 1.5.2 (#1, Dec 12 2000, 02:25:44)  [GCC egcs-2.91.66 19990314/Linux (egcs- on linux2
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>> from pydoc import help
>>> help(int)
Help on built-in function int:

int (no arg info)
    int(x) -> integer
    Convert a string or number to an integer, if possible.
    A floating point argument will be truncated towards zero.

>>> help("urlparse.urljoin")
Help on function urljoin in module urlparse:

urljoin(base, url, allow_fragments=1)
    # Join a base URL and a possibly relative URL to form an absolute
    # interpretation of the latter.
>>> import random
>>> help(random.generator)
Help on class generator in module random:

class generator(whrandom.whrandom)
    Random generator class.
    __init__(self, a=None)
        Constructor.  Seed from current time or hashable value.
    seed(self, a=None)
        Seed the generator from current time or hashable value.