diff options
author | Raymond Hettinger <python@rcn.com> | 2002-05-15 02:56:03 (GMT) |
---|---|---|
committer | Raymond Hettinger <python@rcn.com> | 2002-05-15 02:56:03 (GMT) |
commit | d1fa3db52de5f337e9aae5f3baad16fe62da2d0f (patch) | |
tree | 95180a631b52bb190154b11559d0bfdcdbca17cd | |
parent | 55956c93615855b47cfc5bf9ddc2633a5f73044c (diff) | |
download | cpython-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.py | 23 | ||||
-rw-r--r-- | Lib/fileinput.py | 49 | ||||
-rwxr-xr-x | Lib/tabnanny.py | 25 | ||||
-rw-r--r-- | Lib/tokenize.py | 25 |
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 |