Added docstrings excerpted from Python Library Reference.

Closes patch 556161.

4 files changed, 121 insertions, 1 deletions

diff --git a/Lib/StringIO.py b/Lib/StringIO.py
index 38b3e36..b8cba32 100644
--- a/Lib/StringIO.py
+++ b/Lib/StringIO.py
@@ -37,6 +37,17 @@ except ImportError:
 __all__ = ["StringIO"]
 
 class StringIO:
+    """class StringIO([buffer]) 
+    
+    When a StringIO object is created, it can be initialized to an existing
+    string by passing the string to the constructor. If no string is given,
+    the StringIO will start empty. 
+
+    The StringIO object can accept either Unicode or 8-bit strings, but
+    mixing the two may take some care. If both are used, 8-bit strings that
+    cannot be interpreted as 7-bit ASCII (that use the 8th bit) will cause
+    a UnicodeError to be raised when getvalue() is called. 
+    """
     def __init__(self, buf = ''):
         # Force self.buf to be a string or unicode
         if not isinstance(buf, types.StringTypes):
@@ -52,6 +63,8 @@ class StringIO:
         return iter(self.readline, '')
 
     def close(self):
+        """Free the memory buffer. 
+        """
         if not self.closed:
             self.closed = 1
             del self.buf, self.pos
@@ -165,6 +178,16 @@ class StringIO:
             raise ValueError, "I/O operation on closed file"
 
     def getvalue(self):
+        """
+        Retrieve the entire contents of the "file" at any time before
+        the StringIO object's close() method is called.
+
+        The StringIO object can accept either Unicode or 8-bit strings,
+        but mixing the two may take some care. If both are used, 8-bit
+        strings that cannot be interpreted as 7-bit ASCII (that use the
+        8th bit) will cause a UnicodeError to be raised when getvalue()
+        is called. 
+        """
         if self.buflist:
             self.buf += ''.join(self.buflist)
             self.buflist = []
diff --git a/Lib/fileinput.py b/Lib/fileinput.py
index 2f17dc8..db8ddbd 100644
--- a/Lib/fileinput.py
+++ b/Lib/fileinput.py
@@ -89,6 +89,13 @@ _state = None
 DEFAULT_BUFSIZE = 8*1024
 
 def input(files=None, inplace=0, backup="", bufsize=0):
+    """input([files[, inplace[, backup]]])
+
+    Create an instance of the FileInput class. The instance will be used
+    as global state for the functions of this module, and is also returned
+    to use during iteration. The parameters to this function will be passed
+    along to the constructor of the FileInput class. 
+    """
     global _state
     if _state and _state._file:
         raise RuntimeError, "input() already active"
@@ -96,6 +103,7 @@ def input(files=None, inplace=0, backup="", bufsize=0):
     return _state
 
 def close():
+    """Close the sequence."""
     global _state
     state = _state
     _state = None
@@ -103,36 +111,77 @@ def close():
         state.close()
 
 def nextfile():
+    """
+    Close the current file so that the next iteration will read the first
+    line from the next file (if any); lines not read from the file will
+    not count towards the cumulative line count. The filename is not
+    changed until after the first line of the next file has been read.
+    Before the first line has been read, this function has no effect;
+    it cannot be used to skip the first file. After the last line of the
+    last file has been read, this function has no effect. 
+    """
     if not _state:
         raise RuntimeError, "no active input()"
     return _state.nextfile()
 
 def filename():
+    """
+    Return the name of the file currently being read.
+    Before the first line has been read, returns None. 
+    """
     if not _state:
         raise RuntimeError, "no active input()"
     return _state.filename()
 
 def lineno():
+    """
+    Return the cumulative line number of the line that has just been read.
+    Before the first line has been read, returns 0. After the last line
+    of the last file has been read, returns the line number of that line. 
+    """
     if not _state:
         raise RuntimeError, "no active input()"
     return _state.lineno()
 
 def filelineno():
+    """
+    Return the line number in the current file. Before the first line
+    has been read, returns 0. After the last line of the last file has
+    been read, returns the line number of that line within the file. 
+    """
     if not _state:
         raise RuntimeError, "no active input()"
     return _state.filelineno()
 
 def isfirstline():
+    """
+    Returns true the line just read is the first line of its file,
+    otherwise returns false. 
+    """
     if not _state:
         raise RuntimeError, "no active input()"
     return _state.isfirstline()
 
 def isstdin():
+    """
+    Returns true if the last line was read from sys.stdin,
+    otherwise returns false. 
+    """
     if not _state:
         raise RuntimeError, "no active input()"
     return _state.isstdin()
 
 class FileInput:
+    """class FileInput([files[, inplace[, backup]]])
+    
+    Class FileInput is the implementation of the module; its methods
+    filename(), lineno(), fileline(), isfirstline(), isstdin(), nextfile()
+    and close() correspond to the functions of the same name in the module.
+    In addition it has a readline() method which returns the next
+    input line, and a __getitem__() method which implements the
+    sequence behavior. The sequence must be accessed in strictly
+    sequential order; random access and readline() cannot be mixed. 
+    """
 
     def __init__(self, files=None, inplace=0, backup="", bufsize=0):
         if type(files) == type(''):
diff --git a/Lib/tabnanny.py b/Lib/tabnanny.py
index 2595540..5b10474 100755
--- a/Lib/tabnanny.py
+++ b/Lib/tabnanny.py
@@ -1,6 +1,16 @@
 #! /usr/bin/env python
 
-"""The Tab Nanny despises ambiguous indentation.  She knows no mercy."""
+"""The Tab Nanny despises ambiguous indentation.  She knows no mercy.
+
+tabnanny -- Detection of ambiguous indentation 
+
+For the time being this module is intended to be called as a script.
+However it is possible to import it into an IDE and use the function
+check() described below. 
+
+Warning: The API provided by this module is likely to change in future
+releases; such changes may not be backward compatible. 
+"""
 
 # Released to the public domain, by Tim Peters, 15 April 1998.
 
@@ -48,6 +58,10 @@ def main():
         check(arg)
 
 class NannyNag(Exception):
+    """
+    Raised by tokeneater() if detecting an ambiguous indent.
+    Captured and handled in check(). 
+    """
     def __init__(self, lineno, msg, line):
         self.lineno, self.msg, self.line = lineno, msg, line
     def get_lineno(self):
@@ -58,6 +72,15 @@ class NannyNag(Exception):
         return self.line
 
 def check(file):
+    """check(file_or_dir)
+    
+    If file_or_dir is a directory and not a symbolic link, then recursively
+    descend the directory tree named by file_or_dir, checking all .py files
+    along the way. If file_or_dir is an ordinary Python source file, it is
+    checked for whitespace related problems. The diagnostic messages are
+    written to standard output using the print statement.     
+    """
+    
     if os.path.isdir(file) and not os.path.islink(file):
         if verbose:
             print "%s: listing directory" % `file`
diff --git a/Lib/tokenize.py b/Lib/tokenize.py
index 27ee1bc..42aafe4 100644
--- a/Lib/tokenize.py
+++ b/Lib/tokenize.py
@@ -121,6 +121,18 @@ def printtoken(type, token, (srow, scol), (erow, ecol), line): # for testing
         (srow, scol, erow, ecol, tok_name[type], repr(token))
 
 def tokenize(readline, tokeneater=printtoken):
+    """
+    The tokenize() function accepts two parameters: one representing the
+    input stream, and one providing an output mechanism for tokenize().
+    
+    The first parameter, readline, must be a callable object which provides
+    the same interface as the readline() method of built-in file objects.
+    Each call to the function should return one line of input as a string. 
+
+    The second parameter, tokeneater, must also be a callable object. It is
+    called once for each token, with five arguments, corresponding to the
+    tuples generated by generate_tokens(). 
+    """
     try:
         tokenize_loop(readline, tokeneater)
     except StopTokenizing:
@@ -132,6 +144,19 @@ def tokenize_loop(readline, tokeneater):
         apply(tokeneater, token_info)
 
 def generate_tokens(readline):
+    """
+    The generate_tokens() generator requires one argment, readline, which
+    must be a callable object which provides the same interface as the
+    readline() method of built-in file objects. Each call to the function
+    should return one line of input as a string.
+    
+    The generator produces 5-tuples with these members: the token type; the
+    token string; a 2-tuple (srow, scol) of ints specifying the row and
+    column where the token begins in the source; a 2-tuple (erow, ecol) of
+    ints specifying the row and column where the token ends in the source;
+    and the line on which the token was found. The line passed is the
+    logical line; continuation lines are included. 
+    """
     lnum = parenlev = continued = 0
     namechars, numchars = string.ascii_letters + '_', '0123456789'
     contstr, needcont = '', 0