diff options
Diffstat (limited to 'Lib/StringIO.py')
| -rw-r--r-- | Lib/StringIO.py | 67 |
1 files changed, 67 insertions, 0 deletions
diff --git a/Lib/StringIO.py b/Lib/StringIO.py index 9b79a88..1b9fa7b 100644 --- a/Lib/StringIO.py +++ b/Lib/StringIO.py @@ -66,6 +66,12 @@ class StringIO: return self 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 r = self.readline() @@ -81,10 +87,21 @@ class StringIO: del self.buf, self.pos 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: self.buf += ''.join(self.buflist) @@ -96,10 +113,18 @@ class StringIO: self.pos = max(0, pos) 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: self.buf += ''.join(self.buflist) @@ -113,6 +138,18 @@ class StringIO: return r 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: self.buf += ''.join(self.buflist) @@ -130,6 +167,13 @@ class StringIO: return r 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 = [] line = self.readline() @@ -142,6 +186,16 @@ class StringIO: return lines 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: size = self.pos @@ -152,6 +206,10 @@ class StringIO: self.buf = self.getvalue()[:size] def write(self, s): + """Write a string to the file. + + There is no return value. + """ _complain_ifclosed(self.closed) if not s: return # Force s to be a string or unicode @@ -179,11 +237,20 @@ class StringIO: self.pos = newpos 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: write(line) def flush(self): + """Flush the internal buffer + """ _complain_ifclosed(self.closed) def getvalue(self): |