[Python-checkins] python/dist/src/Lib StringIO.py,1.19.12.2,1.19.12.3 tabnanny.py,1.16,1.16.16.1 fileinput.py,1.8,1.8.8.1 tokenize.py,1.28,1.28.14.1

Tue, 14 May 2002 20:50:33 -0700

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

Modified Files:
      Tag: release22-maint
	StringIO.py tabnanny.py fileinput.py tokenize.py 
Log Message:
Add docstrings excerpted from the library reference.
Closes patch 556161.

Index: StringIO.py
===================================================================
RCS file: /cvsroot/python/python/dist/src/Lib/StringIO.py,v
retrieving revision 1.19.12.2
retrieving revision 1.19.12.3
diff -C2 -d -r1.19.12.2 -r1.19.12.3
*** StringIO.py	18 Mar 2002 13:31:30 -0000	1.19.12.2
--- StringIO.py	15 May 2002 03:50:31 -0000	1.19.12.3
***************
*** 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,68 ----

      def close(self):
+         """Free the memory buffer."""
          if not self.closed:
              self.closed = 1
***************
*** 166,169 ****
--- 178,191 ----

      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.16
retrieving revision 1.16.16.1
diff -C2 -d -r1.16 -r1.16.16.1
*** tabnanny.py	7 Aug 2001 17:19:25 -0000	1.16
--- tabnanny.py	15 May 2002 03:50:31 -0000	1.16.16.1
***************
*** 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:
+     """
+     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.8
retrieving revision 1.8.8.1
diff -C2 -d -r1.8 -r1.8.8.1
*** fileinput.py	24 Oct 2001 20:33:34 -0000	1.8
--- fileinput.py	15 May 2002 03:50:31 -0000	1.8.8.1
***************
*** 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.28
retrieving revision 1.28.14.1
diff -C2 -d -r1.28 -r1.28.14.1
*** tokenize.py	30 Aug 2001 20:51:58 -0000	1.28
--- tokenize.py	15 May 2002 03:50:31 -0000	1.28.14.1
***************
*** 123,126 ****
--- 123,138 ----

  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)
***************
*** 134,137 ****
--- 146,162 ----

  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'