summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRaymond Hettinger <python@rcn.com>2002-05-15 02:56:03 (GMT)
committerRaymond Hettinger <python@rcn.com>2002-05-15 02:56:03 (GMT)
commitd1fa3db52de5f337e9aae5f3baad16fe62da2d0f (patch)
tree95180a631b52bb190154b11559d0bfdcdbca17cd
parent55956c93615855b47cfc5bf9ddc2633a5f73044c (diff)
downloadcpython-d1fa3db52de5f337e9aae5f3baad16fe62da2d0f.zip
cpython-d1fa3db52de5f337e9aae5f3baad16fe62da2d0f.tar.gz
cpython-d1fa3db52de5f337e9aae5f3baad16fe62da2d0f.tar.bz2
Added docstrings excerpted from Python Library Reference.
Closes patch 556161.
-rw-r--r--Lib/StringIO.py23
-rw-r--r--Lib/fileinput.py49
-rwxr-xr-xLib/tabnanny.py25
-rw-r--r--Lib/tokenize.py25
4 files changed, 121 insertions, 1 deletions
diff --git a/Lib/StringIO.py b/Lib/StringIO.py
index 38b3e36..b8cba32 100644
--- a/Lib/StringIO.py
+++ b/Lib/StringIO.py
@@ -37,6 +37,17 @@ except ImportError:
__all__ = ["StringIO"]
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
if not isinstance(buf, types.StringTypes):
@@ -52,6 +63,8 @@ class StringIO:
return iter(self.readline, '')
def close(self):
+ """Free the memory buffer.
+ """
if not self.closed:
self.closed = 1
del self.buf, self.pos
@@ -165,6 +178,16 @@ class StringIO:
raise ValueError, "I/O operation on closed file"
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)
self.buflist = []
diff --git a/Lib/fileinput.py b/Lib/fileinput.py
index 2f17dc8..db8ddbd 100644
--- a/Lib/fileinput.py
+++ b/Lib/fileinput.py
@@ -89,6 +89,13 @@ _state = None
DEFAULT_BUFSIZE = 8*1024
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:
raise RuntimeError, "input() already active"
@@ -96,6 +103,7 @@ def input(files=None, inplace=0, backup="", bufsize=0):
return _state
def close():
+ """Close the sequence."""
global _state
state = _state
_state = None
@@ -103,36 +111,77 @@ def close():
state.close()
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()"
return _state.nextfile()
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()"
return _state.filename()
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()"
return _state.lineno()
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()"
return _state.filelineno()
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()"
return _state.isfirstline()
def isstdin():
+ """
+ Returns true if the last line was read from sys.stdin,
+ otherwise returns false.
+ """
if not _state:
raise RuntimeError, "no active input()"
return _state.isstdin()
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):
if type(files) == type(''):
diff --git a/Lib/tabnanny.py b/Lib/tabnanny.py
index 2595540..5b10474 100755
--- a/Lib/tabnanny.py
+++ b/Lib/tabnanny.py
@@ -1,6 +1,16 @@
#! /usr/bin/env python
-"""The Tab Nanny despises ambiguous indentation. She knows no mercy."""
+"""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.
@@ -48,6 +58,10 @@ def main():
check(arg)
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
def get_lineno(self):
@@ -58,6 +72,15 @@ class NannyNag(Exception):
return self.line
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:
print "%s: listing directory" % `file`
diff --git a/Lib/tokenize.py b/Lib/tokenize.py
index 27ee1bc..42aafe4 100644
--- a/Lib/tokenize.py
+++ b/Lib/tokenize.py
@@ -121,6 +121,18 @@ def printtoken(type, token, (srow, scol), (erow, ecol), line): # for testing
(srow, scol, erow, ecol, tok_name[type], repr(token))
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)
except StopTokenizing:
@@ -132,6 +144,19 @@ def tokenize_loop(readline, tokeneater):
apply(tokeneater, token_info)
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'
contstr, needcont = '', 0