[Python-checkins] python/dist/src/Lib StringIO.py,1.34,1.35

[rhettinger at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv3535

Modified Files:
	StringIO.py 
Log Message:
Add missing docstrings.

Index: StringIO.py
===================================================================
RCS file: /cvsroot/python/python/dist/src/Lib/StringIO.py,v
retrieving revision 1.34
retrieving revision 1.35
diff -C2 -d -r1.34 -r1.35
*** StringIO.py	8 Mar 2004 18:17:31 -0000	1.34
--- StringIO.py	14 Mar 2004 07:54:37 -0000	1.35
***************
*** 67,70 ****
--- 67,76 ----
  
      def next(self):
+         """A file object is its own iterator, for example iter(f) returns f
+         (unless f is closed). When a file is used as an iterator, typically
+         in a for loop (for example, for line in f: print line), the next()
+         method is called repeatedly. This method returns the next input line,
+         or raises StopIteration when EOF is hit.
+         """
          if self.closed:
              raise StopIteration
***************
*** 82,89 ****
--- 88,106 ----
  
      def isatty(self):
+         """Returns False because StringIO objects are not connected to a
+         tty-like device.
+         """
          _complain_ifclosed(self.closed)
          return False
  
      def seek(self, pos, mode = 0):
+         """Set the file's current position.
+ 
+         The mode argument is optional and defaults to 0 (absolute file
+         positioning); other values are 1 (seek relative to the current
+         position) and 2 (seek relative to the file's end).
+ 
+         There is no return value.
+         """
          _complain_ifclosed(self.closed)
          if self.buflist:
***************
*** 97,104 ****
--- 114,129 ----
  
      def tell(self):
+         """Return the file's current position."""
          _complain_ifclosed(self.closed)
          return self.pos
  
      def read(self, n = -1):
+         """Read at most size bytes from the file
+         (less if the read hits EOF before obtaining size bytes).
+ 
+         If the size argument is negative or omitted, read all data until EOF
+         is reached. The bytes are returned as a string object. An empty
+         string is returned when EOF is encountered immediately.
+         """
          _complain_ifclosed(self.closed)
          if self.buflist:
***************
*** 114,117 ****
--- 139,154 ----
  
      def readline(self, length=None):
+         """Read one entire line from the file.
+ 
+         A trailing newline character is kept in the string (but may be absent
+         when a file ends with an incomplete line). If the size argument is
+         present and non-negative, it is a maximum byte count (including the
+         trailing newline) and an incomplete line may be returned.
+ 
+         An empty string is returned only when EOF is encountered immediately.
+ 
+         Note: Unlike stdio's fgets(), the returned string contains null
+         characters ('\0') if they occurred in the input.
+         """
          _complain_ifclosed(self.closed)
          if self.buflist:
***************
*** 131,134 ****
--- 168,178 ----
  
      def readlines(self, sizehint = 0):
+         """Read until EOF using readline() and return a list containing the
+         lines thus read.
+ 
+         If the optional sizehint argument is present, instead of reading up
+         to EOF, whole lines totalling approximately sizehint bytes (or more
+         to accommodate a final whole line).
+         """
          total = 0
          lines = []
***************
*** 143,146 ****
--- 187,200 ----
  
      def truncate(self, size=None):
+         """Truncate the file's size.
+ 
+         If the optional size argument is present, the file is truncated to
+         (at most) that size. The size defaults to the current position.
+         The current file position is not changed unless the position
+         is beyond the new file size.
+ 
+         If the specified size exceeds the file's current size, the
+         file remains unchanged.
+         """
          _complain_ifclosed(self.closed)
          if size is None:
***************
*** 153,156 ****
--- 207,214 ----
  
      def write(self, s):
+         """Write a string to the file.
+ 
+         There is no return value.
+         """
          _complain_ifclosed(self.closed)
          if not s: return
***************
*** 180,183 ****
--- 238,248 ----
  
      def writelines(self, iterable):
+         """Write a sequence of strings to the file. The sequence can be any
+         iterable object producing strings, typically a list of strings. There
+         is no return value.
+ 
+         (The name is intended to match readlines(); writelines() does not add
+         line separators.)
+         """
          write = self.write
          for line in iterable:
***************
*** 185,188 ****
--- 250,255 ----
  
      def flush(self):
+         """Flush the internal buffer
+         """
          _complain_ifclosed(self.closed)