Add missing docstrings.
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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):