[Python-checkins] python/dist/src/Lib StringIO.py,1.24,1.25 tabnanny.py,1.18,1.19 fileinput.py,1.11,1.12 tokenize.py,1.30,1.31

[rhettinger@sourceforge.net]

Update of /cvsroot/python/python/dist/src/Lib
In directory usw-pr-cvs1:/tmp/cvs-serv19779

Modified Files:
	StringIO.py tabnanny.py fileinput.py tokenize.py 
Log Message:
Added docstrings excerpted from Python Library Reference.  
Closes patch 556161.


Index: StringIO.py
===================================================================
RCS file: /cvsroot/python/python/dist/src/Lib/StringIO.py,v
retrieving revision 1.24
retrieving revision 1.25
diff -C2 -d -r1.24 -r1.25
*** StringIO.py	13 May 2002 09:42:15 -0000	1.24
--- StringIO.py	15 May 2002 02:56:03 -0000	1.25
***************
*** 38,41 ****
--- 38,52 ----
  
  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
***************
*** 53,56 ****
--- 64,69 ----
  
      def close(self):
+         """Free the memory buffer. 
+         """
          if not self.closed:
              self.closed = 1
***************
*** 166,169 ****
--- 179,192 ----
  
      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)

Index: tabnanny.py
===================================================================
RCS file: /cvsroot/python/python/dist/src/Lib/tabnanny.py,v
retrieving revision 1.18
retrieving revision 1.19
diff -C2 -d -r1.18 -r1.19
*** tabnanny.py	4 Apr 2002 22:55:58 -0000	1.18
--- tabnanny.py	15 May 2002 02:56:03 -0000	1.19
***************
*** 1,5 ****
  #! /usr/bin/env python
  
! """The Tab Nanny despises ambiguous indentation.  She knows no mercy."""
  
  # Released to the public domain, by Tim Peters, 15 April 1998.
--- 1,15 ----
  #! /usr/bin/env python
  
! """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.
***************
*** 49,52 ****
--- 59,66 ----
  
  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
***************
*** 59,62 ****
--- 73,85 ----
  
  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:

Index: fileinput.py
===================================================================
RCS file: /cvsroot/python/python/dist/src/Lib/fileinput.py,v
retrieving revision 1.11
retrieving revision 1.12
diff -C2 -d -r1.11 -r1.12
*** fileinput.py	16 Apr 2002 01:38:39 -0000	1.11
--- fileinput.py	15 May 2002 02:56:03 -0000	1.12
***************
*** 90,93 ****
--- 90,100 ----
  
  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:
***************
*** 97,100 ****
--- 104,108 ----
  
  def close():
+     """Close the sequence."""
      global _state
      state = _state
***************
*** 104,107 ****
--- 112,124 ----
  
  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()"
***************
*** 109,112 ****
--- 126,133 ----
  
  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()"
***************
*** 114,117 ****
--- 135,143 ----
  
  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()"
***************
*** 119,122 ****
--- 145,153 ----
  
  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()"
***************
*** 124,127 ****
--- 155,162 ----
  
  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()"
***************
*** 129,132 ****
--- 164,171 ----
  
  def isstdin():
+     """
+     Returns true if the last line was read from sys.stdin,
+     otherwise returns false. 
+     """
      if not _state:
          raise RuntimeError, "no active input()"
***************
*** 134,137 ****
--- 173,186 ----
  
  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):

Index: tokenize.py
===================================================================
RCS file: /cvsroot/python/python/dist/src/Lib/tokenize.py,v
retrieving revision 1.30
retrieving revision 1.31
diff -C2 -d -r1.30 -r1.31
*** tokenize.py	1 Apr 2002 00:28:59 -0000	1.30
--- tokenize.py	15 May 2002 02:56:03 -0000	1.31
***************
*** 122,125 ****
--- 122,137 ----
  
  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)
***************
*** 133,136 ****
--- 145,161 ----
  
  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'