More trivial comment -> docstring transformations by Ka-Ping Yee,

who writes:

Here is batch 2, as a big collection of CVS context diffs.
Along with moving comments into docstrings, i've added a
couple of missing docstrings and attempted to make sure more
module docstrings begin with a one-line summary.

I did not add docstrings to the methods in profile.py for
fear of upsetting any careful optimizations there, though
i did move class documentation into class docstrings.

The convention i'm using is to leave credits/version/copyright
type of stuff in # comments, and move the rest of the descriptive
stuff about module usage into module docstrings.  Hope this is
okay.

Lib/fpformat.py

@@ -22,120 +22,120 @@ decoder = re.compile(r'^([-+]?)0*(\d*)((?:\.\d*)?)(([eE][-+]?\d+)?)$')
 # \4 exponent part (empty or begins with 'e' or 'E')
 
 try:
-	class NotANumber(ValueError):
-		pass
+    class NotANumber(ValueError):
+        pass
 except TypeError:
-	NotANumber = 'fpformat.NotANumber'
+    NotANumber = 'fpformat.NotANumber'
 
-# Return (sign, intpart, fraction, expo) or raise an exception:
-# sign is '+' or '-'
-# intpart is 0 or more digits beginning with a nonzero
-# fraction is 0 or more digits
-# expo is an integer
 def extract(s):
-	res = decoder.match(s)
-	if res is None: raise NotANumber, s
-	sign, intpart, fraction, exppart = res.group(1,2,3,4)
-	if sign == '+': sign = ''
-	if fraction: fraction = fraction[1:]
-	if exppart: expo = int(exppart[1:])
-	else: expo = 0
-	return sign, intpart, fraction, expo
+    """Return (sign, intpart, fraction, expo) or raise an exception:
+    sign is '+' or '-'
+    intpart is 0 or more digits beginning with a nonzero
+    fraction is 0 or more digits
+    expo is an integer"""
+    res = decoder.match(s)
+    if res is None: raise NotANumber, s
+    sign, intpart, fraction, exppart = res.group(1,2,3,4)
+    if sign == '+': sign = ''
+    if fraction: fraction = fraction[1:]
+    if exppart: expo = int(exppart[1:])
+    else: expo = 0
+    return sign, intpart, fraction, expo
 
-# Remove the exponent by changing intpart and fraction
 def unexpo(intpart, fraction, expo):
-	if expo > 0: # Move the point left
-		f = len(fraction)
-		intpart, fraction = intpart + fraction[:expo], fraction[expo:]
-		if expo > f:
-			intpart = intpart + '0'*(expo-f)
-	elif expo < 0: # Move the point right
-		i = len(intpart)
-		intpart, fraction = intpart[:expo], intpart[expo:] + fraction
-		if expo < -i:
-			fraction = '0'*(-expo-i) + fraction
-	return intpart, fraction
+    """Remove the exponent by changing intpart and fraction."""
+    if expo > 0: # Move the point left
+        f = len(fraction)
+        intpart, fraction = intpart + fraction[:expo], fraction[expo:]
+        if expo > f:
+            intpart = intpart + '0'*(expo-f)
+    elif expo < 0: # Move the point right
+        i = len(intpart)
+        intpart, fraction = intpart[:expo], intpart[expo:] + fraction
+        if expo < -i:
+            fraction = '0'*(-expo-i) + fraction
+    return intpart, fraction
 
-# Round or extend the fraction to size digs
 def roundfrac(intpart, fraction, digs):
-	f = len(fraction)
-	if f <= digs:
-		return intpart, fraction + '0'*(digs-f)
-	i = len(intpart)
-	if i+digs < 0:
-		return '0'*-digs, ''
-	total = intpart + fraction
-	nextdigit = total[i+digs]
-	if nextdigit >= '5': # Hard case: increment last digit, may have carry!
-		n = i + digs - 1
-		while n >= 0:
-			if total[n] != '9': break
-			n = n-1
-		else:
-			total = '0' + total
-			i = i+1
-			n = 0
-		total = total[:n] + chr(ord(total[n]) + 1) + '0'*(len(total)-n-1)
-		intpart, fraction = total[:i], total[i:]
-	if digs >= 0:
-		return intpart, fraction[:digs]
-	else:
-		return intpart[:digs] + '0'*-digs, ''
+    """Round or extend the fraction to size digs."""
+    f = len(fraction)
+    if f <= digs:
+        return intpart, fraction + '0'*(digs-f)
+    i = len(intpart)
+    if i+digs < 0:
+        return '0'*-digs, ''
+    total = intpart + fraction
+    nextdigit = total[i+digs]
+    if nextdigit >= '5': # Hard case: increment last digit, may have carry!
+        n = i + digs - 1
+        while n >= 0:
+            if total[n] != '9': break
+            n = n-1
+        else:
+            total = '0' + total
+            i = i+1
+            n = 0
+        total = total[:n] + chr(ord(total[n]) + 1) + '0'*(len(total)-n-1)
+        intpart, fraction = total[:i], total[i:]
+    if digs >= 0:
+        return intpart, fraction[:digs]
+    else:
+        return intpart[:digs] + '0'*-digs, ''
 
-# Format x as [-]ddd.ddd with 'digs' digits after the point
-# and at least one digit before.
-# If digs <= 0, the point is suppressed.
 def fix(x, digs):
-	if type(x) != type(''): x = `x`
-	try:
-		sign, intpart, fraction, expo = extract(x)
-	except NotANumber:
-		return x
-	intpart, fraction = unexpo(intpart, fraction, expo)
-	intpart, fraction = roundfrac(intpart, fraction, digs)
-	while intpart and intpart[0] == '0': intpart = intpart[1:]
-	if intpart == '': intpart = '0'
-	if digs > 0: return sign + intpart + '.' + fraction
-	else: return sign + intpart
+    """Format x as [-]ddd.ddd with 'digs' digits after the point
+    and at least one digit before.
+    If digs <= 0, the point is suppressed."""
+    if type(x) != type(''): x = `x`
+    try:
+        sign, intpart, fraction, expo = extract(x)
+    except NotANumber:
+        return x
+    intpart, fraction = unexpo(intpart, fraction, expo)
+    intpart, fraction = roundfrac(intpart, fraction, digs)
+    while intpart and intpart[0] == '0': intpart = intpart[1:]
+    if intpart == '': intpart = '0'
+    if digs > 0: return sign + intpart + '.' + fraction
+    else: return sign + intpart
 
-# Format x as [-]d.dddE[+-]ddd with 'digs' digits after the point
-# and exactly one digit before.
-# If digs is <= 0, one digit is kept and the point is suppressed.
 def sci(x, digs):
-	if type(x) != type(''): x = `x`
-	sign, intpart, fraction, expo = extract(x)
-	if not intpart:
-		while fraction and fraction[0] == '0':
-			fraction = fraction[1:]
-			expo = expo - 1
-		if fraction:
-			intpart, fraction = fraction[0], fraction[1:]
-			expo = expo - 1
-		else:
-			intpart = '0'
-	else:
-		expo = expo + len(intpart) - 1
-		intpart, fraction = intpart[0], intpart[1:] + fraction
-	digs = max(0, digs)
-	intpart, fraction = roundfrac(intpart, fraction, digs)
-	if len(intpart) > 1:
-		intpart, fraction, expo = \
-			intpart[0], intpart[1:] + fraction[:-1], \
-			expo + len(intpart) - 1
-	s = sign + intpart
-	if digs > 0: s = s + '.' + fraction
-	e = `abs(expo)`
-	e = '0'*(3-len(e)) + e
-	if expo < 0: e = '-' + e
-	else: e = '+' + e
-	return s + 'e' + e
+    """Format x as [-]d.dddE[+-]ddd with 'digs' digits after the point
+    and exactly one digit before.
+    If digs is <= 0, one digit is kept and the point is suppressed."""
+    if type(x) != type(''): x = `x`
+    sign, intpart, fraction, expo = extract(x)
+    if not intpart:
+        while fraction and fraction[0] == '0':
+            fraction = fraction[1:]
+            expo = expo - 1
+        if fraction:
+            intpart, fraction = fraction[0], fraction[1:]
+            expo = expo - 1
+        else:
+            intpart = '0'
+    else:
+        expo = expo + len(intpart) - 1
+        intpart, fraction = intpart[0], intpart[1:] + fraction
+    digs = max(0, digs)
+    intpart, fraction = roundfrac(intpart, fraction, digs)
+    if len(intpart) > 1:
+        intpart, fraction, expo = \
+            intpart[0], intpart[1:] + fraction[:-1], \
+            expo + len(intpart) - 1
+    s = sign + intpart
+    if digs > 0: s = s + '.' + fraction
+    e = `abs(expo)`
+    e = '0'*(3-len(e)) + e
+    if expo < 0: e = '-' + e
+    else: e = '+' + e
+    return s + 'e' + e
 
-# Interactive test run
 def test():
-	try:
-		while 1:
-			x, digs = input('Enter (x, digs): ')
-			print x, fix(x, digs), sci(x, digs)
-	except (EOFError, KeyboardInterrupt):
-		pass
+    """Interactive test run."""
+    try:
+        while 1:
+            x, digs = input('Enter (x, digs): ')
+            print x, fix(x, digs), sci(x, digs)
+    except (EOFError, KeyboardInterrupt):
+        pass
 

Lib/gopherlib.py

-# Gopher protocol client interface
+"""Gopher protocol client interface."""
 
 import string
 
@@ -29,180 +29,180 @@ A_IMAGE      = 'I'
 A_WHOIS      = 'w'
 A_QUERY      = 'q'
 A_GIF        = 'g'
-A_HTML       = 'h'			# HTML file
-A_WWW        = 'w'			# WWW address
+A_HTML       = 'h'          # HTML file
+A_WWW        = 'w'          # WWW address
 A_PLUS_IMAGE = ':'
 A_PLUS_MOVIE = ';'
 A_PLUS_SOUND = '<'
 
 
-# Function mapping all file types to strings; unknown types become TYPE='x'
 _names = dir()
 _type_to_name_map = {}
 def type_to_name(gtype):
-	global _type_to_name_map
-	if _type_to_name_map=={}:
-		for name in _names:
-			if name[:2] == 'A_':
-				_type_to_name_map[eval(name)] = name[2:]
-	if _type_to_name_map.has_key(gtype):
-		return _type_to_name_map[gtype]
-	return 'TYPE=' + `gtype`
+    """Map all file types to strings; unknown types become TYPE='x'."""
+    global _type_to_name_map
+    if _type_to_name_map=={}:
+        for name in _names:
+            if name[:2] == 'A_':
+                _type_to_name_map[eval(name)] = name[2:]
+    if _type_to_name_map.has_key(gtype):
+        return _type_to_name_map[gtype]
+    return 'TYPE=' + `gtype`
 
 # Names for characters and strings
 CRLF = '\r\n'
 TAB = '\t'
 
-# Send a selector to a given host and port, return a file with the reply
 def send_selector(selector, host, port = 0):
-	import socket
-	import string
-	if not port:
-		i = string.find(host, ':')
-		if i >= 0:
-			host, port = host[:i], string.atoi(host[i+1:])
-	if not port:
-		port = DEF_PORT
-	elif type(port) == type(''):
-		port = string.atoi(port)
-	s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-	s.connect(host, port)
-	s.send(selector + CRLF)
-	s.shutdown(1)
-	return s.makefile('rb')
-
-# Send a selector and a query string
+    """Send a selector to a given host and port, return a file with the reply."""
+    import socket
+    import string
+    if not port:
+        i = string.find(host, ':')
+        if i >= 0:
+            host, port = host[:i], string.atoi(host[i+1:])
+    if not port:
+        port = DEF_PORT
+    elif type(port) == type(''):
+        port = string.atoi(port)
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    s.connect(host, port)
+    s.send(selector + CRLF)
+    s.shutdown(1)
+    return s.makefile('rb')
+
 def send_query(selector, query, host, port = 0):
-	return send_selector(selector + '\t' + query, host, port)
+    """Send a selector and a query string."""
+    return send_selector(selector + '\t' + query, host, port)
 
-# Takes a path as returned by urlparse and returns the appropriate selector
 def path_to_selector(path):
-	if path=="/":
-		return "/"
-	else:
-		return path[2:] # Cuts initial slash and data type identifier
+    """Takes a path as returned by urlparse and returns the appropriate selector."""
+    if path=="/":
+        return "/"
+    else:
+        return path[2:] # Cuts initial slash and data type identifier
 
-# Takes a path as returned by urlparse and maps it to a string
-# See section 3.4 of RFC 1738 for details
 def path_to_datatype_name(path):
-	if path=="/":
-		# No way to tell, although "INDEX" is likely
-		return "TYPE='unknown'"
-	else:
-		return type_to_name(path[1])
+    """Takes a path as returned by urlparse and maps it to a string.
+    See section 3.4 of RFC 1738 for details."""
+    if path=="/":
+        # No way to tell, although "INDEX" is likely
+        return "TYPE='unknown'"
+    else:
+        return type_to_name(path[1])
 
 # The following functions interpret the data returned by the gopher
 # server according to the expected type, e.g. textfile or directory
 
-# Get a directory in the form of a list of entries
 def get_directory(f):
-	import string
-	list = []
-	while 1:
-		line = f.readline()
-		if not line:
-			print '(Unexpected EOF from server)'
-			break
-		if line[-2:] == CRLF:
-			line = line[:-2]
-		elif line[-1:] in CRLF:
-			line = line[:-1]
-		if line == '.':
-			break
-		if not line:
-			print '(Empty line from server)'
-			continue
-		gtype = line[0]
-		parts = string.splitfields(line[1:], TAB)
-		if len(parts) < 4:
-			print '(Bad line from server:', `line`, ')'
-			continue
-		if len(parts) > 4:
-			if parts[4:] != ['+']:
-				print '(Extra info from server:',
-				print parts[4:], ')'
-		else:
-			parts.append('')
-		parts.insert(0, gtype)
-		list.append(parts)
-	return list
-
-# Get a text file as a list of lines, with trailing CRLF stripped
+    """Get a directory in the form of a list of entries."""
+    import string
+    list = []
+    while 1:
+        line = f.readline()
+        if not line:
+            print '(Unexpected EOF from server)'
+            break
+        if line[-2:] == CRLF:
+            line = line[:-2]
+        elif line[-1:] in CRLF:
+            line = line[:-1]
+        if line == '.':
+            break
+        if not line:
+            print '(Empty line from server)'
+            continue
+        gtype = line[0]
+        parts = string.splitfields(line[1:], TAB)
+        if len(parts) < 4:
+            print '(Bad line from server:', `line`, ')'
+            continue
+        if len(parts) > 4:
+            if parts[4:] != ['+']:
+                print '(Extra info from server:',
+                print parts[4:], ')'
+        else:
+            parts.append('')
+        parts.insert(0, gtype)
+        list.append(parts)
+    return list
+
 def get_textfile(f):
-	list = []
-	get_alt_textfile(f, list.append)
-	return list
+    """Get a text file as a list of lines, with trailing CRLF stripped."""
+    list = []
+    get_alt_textfile(f, list.append)
+    return list
 
-# Get a text file and pass each line to a function, with trailing CRLF stripped
 def get_alt_textfile(f, func):
-	while 1:
-		line = f.readline()
-		if not line:
-			print '(Unexpected EOF from server)'
-			break
-		if line[-2:] == CRLF:
-			line = line[:-2]
-		elif line[-1:] in CRLF:
-			line = line[:-1]
-		if line == '.':
-			break
-		if line[:2] == '..':
-			line = line[1:]
-		func(line)
-
-# Get a binary file as one solid data block
+    """Get a text file and pass each line to a function, with trailing CRLF stripped."""
+    while 1:
+        line = f.readline()
+        if not line:
+            print '(Unexpected EOF from server)'
+            break
+        if line[-2:] == CRLF:
+            line = line[:-2]
+        elif line[-1:] in CRLF:
+            line = line[:-1]
+        if line == '.':
+            break
+        if line[:2] == '..':
+            line = line[1:]
+        func(line)
+
 def get_binary(f):
-	data = f.read()
-	return data
+    """Get a binary file as one solid data block."""
+    data = f.read()
+    return data
 
-# Get a binary file and pass each block to a function
 def get_alt_binary(f, func, blocksize):
-	while 1:
-		data = f.read(blocksize)
-		if not data:
-			break
-		func(data)
+    """Get a binary file and pass each block to a function."""
+    while 1:
+        data = f.read(blocksize)
+        if not data:
+            break
+        func(data)
 
-# Trivial test program
 def test():
-	import sys
-	import getopt
-	opts, args = getopt.getopt(sys.argv[1:], '')
-	selector = DEF_SELECTOR
-	type = selector[0]
-	host = DEF_HOST
-	port = DEF_PORT
-	if args:
-		host = args[0]
-		args = args[1:]
-	if args:
-		type = args[0]
-		args = args[1:]
-		if len(type) > 1:
-			type, selector = type[0], type
-		else:
-			selector = ''
-			if args:
-				selector = args[0]
-				args = args[1:]
-		query = ''
-		if args:
-			query = args[0]
-			args = args[1:]
-	if type == A_INDEX:
-		f = send_query(selector, query, host)
-	else:
-		f = send_selector(selector, host)
-	if type == A_TEXT:
-		list = get_textfile(f)
-		for item in list: print item
-	elif type in (A_MENU, A_INDEX):
-		list = get_directory(f)
-		for item in list: print item
-	else:
-		data = get_binary(f)
-		print 'binary data:', len(data), 'bytes:', `data[:100]`[:40]
+    """Trivial test program."""
+    import sys
+    import getopt
+    opts, args = getopt.getopt(sys.argv[1:], '')
+    selector = DEF_SELECTOR
+    type = selector[0]
+    host = DEF_HOST
+    port = DEF_PORT
+    if args:
+        host = args[0]
+        args = args[1:]
+    if args:
+        type = args[0]
+        args = args[1:]
+        if len(type) > 1:
+            type, selector = type[0], type
+        else:
+            selector = ''
+            if args:
+                selector = args[0]
+                args = args[1:]
+        query = ''
+        if args:
+            query = args[0]
+            args = args[1:]
+    if type == A_INDEX:
+        f = send_query(selector, query, host)
+    else:
+        f = send_selector(selector, host)
+    if type == A_TEXT:
+        list = get_textfile(f)
+        for item in list: print item
+    elif type in (A_MENU, A_INDEX):
+        list = get_directory(f)
+        for item in list: print item
+    else:
+        data = get_binary(f)
+        print 'binary data:', len(data), 'bytes:', `data[:100]`[:40]
 
 # Run the test when run as script
 if __name__ == '__main__':
-	test()
+    test()

Lib/gzip.py

+"""This module implements a function that reads and writes a gzipped file.
+The user of the file doesn't have to worry about the compression,
+but random access is not allowed."""
+
+# based on Andrew Kuchling's minigzip.py distributed with the zlib module
+
 import time
 import string
 import zlib
 import struct
 import __builtin__
 
-# implements a python function that reads and writes a gzipped file
-# the user of the file doesn't have to worry about the compression,
-# but random access is not allowed
-
-# based on Andrew Kuchling's minigzip.py distributed with the zlib module
-
 FTEXT, FHCRC, FEXTRA, FNAME, FCOMMENT = 1, 2, 4, 8, 16
 
 READ, WRITE = 1, 2

Lib/htmlentitydefs.py

+"""HTML character entity references."""
+
 entitydefs = {
     'AElig':	'\306',  	# latin capital letter AE = latin capital ligature AE, U+00C6 ISOlat1
     'Aacute':	'\301',  	# latin capital letter A with acute, U+00C1 ISOlat1

Lib/imghdr.py

-# Recognizing image files based on their first few bytes.
+"""Recognize image file formats based on their first few bytes."""
 
 
 #-------------------------#
@@ -6,25 +6,25 @@
 #-------------------------#
 
 def what(file, h=None):
-	if h is None:
-		if type(file) == type(''):
-			f = open(file, 'rb')
-			h = f.read(32)
-		else:
-			location = file.tell()
-			h = file.read(32)
-			file.seek(location)
-			f = None	
-	else:
-		f = None
-	try:
-		for tf in tests:
-			res = tf(h, f)
-			if res:
-				return res
-	finally:
-		if f: f.close()
-	return None
+    if h is None:
+        if type(file) == type(''):
+            f = open(file, 'rb')
+            h = f.read(32)
+        else:
+            location = file.tell()
+            h = file.read(32)
+            file.seek(location)
+            f = None    
+    else:
+        f = None
+    try:
+        for tf in tests:
+            res = tf(h, f)
+            if res:
+                return res
+    finally:
+        if f: f.close()
+    return None
 
 
 #---------------------------------#
@@ -34,81 +34,81 @@ def what(file, h=None):
 tests = []
 
 def test_rgb(h, f):
-	# SGI image library
-	if h[:2] == '\001\332':
-		return 'rgb'
+    """SGI image library"""
+    if h[:2] == '\001\332':
+        return 'rgb'
 
 tests.append(test_rgb)
 
 def test_gif(h, f):
-	# GIF ('87 and '89 variants)
-	if h[:6] in ('GIF87a', 'GIF89a'):
-		return 'gif'
+    """GIF ('87 and '89 variants)"""
+    if h[:6] in ('GIF87a', 'GIF89a'):
+        return 'gif'
 
 tests.append(test_gif)
 
 def test_pbm(h, f):
-	# PBM (portable bitmap)
-	if len(h) >= 3 and \
-		h[0] == 'P' and h[1] in '14' and h[2] in ' \t\n\r':
-		return 'pbm'
+    """PBM (portable bitmap)"""
+    if len(h) >= 3 and \
+        h[0] == 'P' and h[1] in '14' and h[2] in ' \t\n\r':
+        return 'pbm'
 
 tests.append(test_pbm)
 
 def test_pgm(h, f):
-	# PGM (portable graymap)
-	if len(h) >= 3 and \
-		h[0] == 'P' and h[1] in '25' and h[2] in ' \t\n\r':
-		return 'pgm'
+    """PGM (portable graymap)"""
+    if len(h) >= 3 and \
+        h[0] == 'P' and h[1] in '25' and h[2] in ' \t\n\r':
+        return 'pgm'
 
 tests.append(test_pgm)
 
 def test_ppm(h, f):
-	# PPM (portable pixmap)
-	if len(h) >= 3 and \
-		h[0] == 'P' and h[1] in '36' and h[2] in ' \t\n\r':
-		return 'ppm'
+    """PPM (portable pixmap)"""
+    if len(h) >= 3 and \
+        h[0] == 'P' and h[1] in '36' and h[2] in ' \t\n\r':
+        return 'ppm'
 
 tests.append(test_ppm)
 
 def test_tiff(h, f):
-	# TIFF (can be in Motorola or Intel byte order)
-	if h[:2] in ('MM', 'II'):
-		return 'tiff'
+    """TIFF (can be in Motorola or Intel byte order)"""
+    if h[:2] in ('MM', 'II'):
+        return 'tiff'
 
 tests.append(test_tiff)
 
 def test_rast(h, f):
-	# Sun raster file
-	if h[:4] == '\x59\xA6\x6A\x95':
-		return 'rast'
+    """Sun raster file"""
+    if h[:4] == '\x59\xA6\x6A\x95':
+        return 'rast'
 
 tests.append(test_rast)
 
 def test_xbm(h, f):
-	# X bitmap (X10 or X11)
-	s = '#define '
-	if h[:len(s)] == s:
-		return 'xbm'
+    """X bitmap (X10 or X11)"""
+    s = '#define '
+    if h[:len(s)] == s:
+        return 'xbm'
 
 tests.append(test_xbm)
 
 def test_jpeg(h, f):
-	# JPEG data in JFIF format
-	if h[6:10] == 'JFIF':
-		return 'jpeg'
+    """JPEG data in JFIF format"""
+    if h[6:10] == 'JFIF':
+        return 'jpeg'
 
 tests.append(test_jpeg)
 
 def test_bmp(h, f):
-	if h[:2] == 'BM':
-		return 'bmp'
-		
+    if h[:2] == 'BM':
+        return 'bmp'
+        
 tests.append(test_bmp)
 
 def test_png(h, f):
-	if h[:8] == "\211PNG\r\n\032\n":
-		return 'png'
+    if h[:8] == "\211PNG\r\n\032\n":
+        return 'png'
 
 tests.append(test_png)
 
@@ -117,37 +117,37 @@ tests.append(test_png)
 #--------------------#
 
 def test():
-	import sys
-	recursive = 0
-	if sys.argv[1:] and sys.argv[1] == '-r':
-		del sys.argv[1:2]
-		recursive = 1
-	try:
-		if sys.argv[1:]:
-			testall(sys.argv[1:], recursive, 1)
-		else:
-			testall(['.'], recursive, 1)
-	except KeyboardInterrupt:
-		sys.stderr.write('\n[Interrupted]\n')
-		sys.exit(1)
+    import sys
+    recursive = 0
+    if sys.argv[1:] and sys.argv[1] == '-r':
+        del sys.argv[1:2]
+        recursive = 1
+    try:
+        if sys.argv[1:]:
+            testall(sys.argv[1:], recursive, 1)
+        else:
+            testall(['.'], recursive, 1)
+    except KeyboardInterrupt:
+        sys.stderr.write('\n[Interrupted]\n')
+        sys.exit(1)
 
 def testall(list, recursive, toplevel):
-	import sys
-	import os
-	for filename in list:
-		if os.path.isdir(filename):
-			print filename + '/:',
-			if recursive or toplevel:
-				print 'recursing down:'
-				import glob
-				names = glob.glob(os.path.join(filename, '*'))
-				testall(names, recursive, 0)
-			else:
-				print '*** directory (use -r) ***'
-		else:
-			print filename + ':',
-			sys.stdout.flush()
-			try:
-				print what(filename)
-			except IOError:
-				print '*** not found ***'
+    import sys
+    import os
+    for filename in list:
+        if os.path.isdir(filename):
+            print filename + '/:',
+            if recursive or toplevel:
+                print 'recursing down:'
+                import glob
+                names = glob.glob(os.path.join(filename, '*'))
+                testall(names, recursive, 0)
+            else:
+                print '*** directory (use -r) ***'
+        else:
+            print filename + ':',
+            sys.stdout.flush()
+            try:
+                print what(filename)
+            except IOError:
+                print '*** not found ***'

Lib/keyword.py

 #! /usr/bin/env python
-#
-#  Keywords (from "graminit.c")
-#
-#  This file is automatically generated; please don't muck it up!
-#
-#  To update the symbols in this file, 'cd' to the top directory of
-#  the python source tree after building the interpreter and run:
-#
-#    python Lib/keyword.py
+
+"""Keywords (from "graminit.c")
+
+This file is automatically generated; please don't muck it up!
+
+To update the symbols in this file, 'cd' to the top directory of
+the python source tree after building the interpreter and run:
+
+    python Lib/keyword.py
+"""
 
 kwlist = [
 #--start keywords--

Lib/linecache.py

-# Cache lines from files.
-# This is intended to read lines from modules imported -- hence if a filename
-# is not found, it will look down the module search path for a file by
-# that name.
+"""Cache lines from files.
+
+This is intended to read lines from modules imported -- hence if a filename
+is not found, it will look down the module search path for a file by
+that name.
+"""
 
 import sys
 import os
 from stat import *
 
 def getline(filename, lineno):
-	lines = getlines(filename)
-	if 1 <= lineno <= len(lines):
-		return lines[lineno-1]
-	else:
-		return ''
+    lines = getlines(filename)
+    if 1 <= lineno <= len(lines):
+        return lines[lineno-1]
+    else:
+        return ''
 
 
 # The cache
@@ -20,71 +22,71 @@ def getline(filename, lineno):
 cache = {} # The cache
 
 
-# Clear the cache entirely
-
 def clearcache():
-	global cache
-	cache = {}
+    """Clear the cache entirely."""
 
+    global cache
+    cache = {}
 
-# Get the lines for a file from the cache.
-# Update the cache if it doesn't contain an entry for this file already.
 
 def getlines(filename):
-	if cache.has_key(filename):
-		return cache[filename][2]
-	else:
-		return updatecache(filename)
+    """Get the lines for a file from the cache.
+    Update the cache if it doesn't contain an entry for this file already."""
 
+    if cache.has_key(filename):
+        return cache[filename][2]
+    else:
+        return updatecache(filename)
 
-# Discard cache entries that are out of date.
-# (This is not checked upon each call!)
 
 def checkcache():
-	for filename in cache.keys():
-		size, mtime, lines, fullname = cache[filename]
-		try:
-			stat = os.stat(fullname)
-		except os.error:
-			del cache[filename]
-			continue
-		if size <> stat[ST_SIZE] or mtime <> stat[ST_MTIME]:
-			del cache[filename]
+    """Discard cache entries that are out of date.
+    (This is not checked upon each call!)"""
 
+    for filename in cache.keys():
+        size, mtime, lines, fullname = cache[filename]
+        try:
+            stat = os.stat(fullname)
+        except os.error:
+            del cache[filename]
+            continue
+        if size <> stat[ST_SIZE] or mtime <> stat[ST_MTIME]:
+            del cache[filename]
 
-# Update a cache entry and return its list of lines.
-# If something's wrong, print a message, discard the cache entry,
-# and return an empty list.
 
 def updatecache(filename):
-	if cache.has_key(filename):
-		del cache[filename]
-	if not filename or filename[0] + filename[-1] == '<>':
-		return []
-	fullname = filename
-	try:
-		stat = os.stat(fullname)
-	except os.error, msg:
-		# Try looking through the module search path
-		basename = os.path.split(filename)[1]
-		for dirname in sys.path:
-			fullname = os.path.join(dirname, basename)
-			try:
-				stat = os.stat(fullname)
-				break
-			except os.error:
-				pass
-		else:
-			# No luck
-##			print '*** Cannot stat', filename, ':', msg
-			return []
-	try:
-		fp = open(fullname, 'r')
-		lines = fp.readlines()
-		fp.close()
-	except IOError, msg:
-##		print '*** Cannot open', fullname, ':', msg
-		return []
-	size, mtime = stat[ST_SIZE], stat[ST_MTIME]
-	cache[filename] = size, mtime, lines, fullname
-	return lines
+    """Update a cache entry and return its list of lines.
+    If something's wrong, print a message, discard the cache entry,
+    and return an empty list."""
+
+    if cache.has_key(filename):
+        del cache[filename]
+    if not filename or filename[0] + filename[-1] == '<>':
+        return []
+    fullname = filename
+    try:
+        stat = os.stat(fullname)
+    except os.error, msg:
+        # Try looking through the module search path
+        basename = os.path.split(filename)[1]
+        for dirname in sys.path:
+            fullname = os.path.join(dirname, basename)
+            try:
+                stat = os.stat(fullname)
+                break
+            except os.error:
+                pass
+        else:
+            # No luck
+##          print '*** Cannot stat', filename, ':', msg
+            return []
+    try:
+        fp = open(fullname, 'r')
+        lines = fp.readlines()
+        fp.close()
+    except IOError, msg:
+##      print '*** Cannot open', fullname, ':', msg
+        return []
+    size, mtime = stat[ST_SIZE], stat[ST_MTIME]
+    cache[filename] = size, mtime, lines, fullname
+    return lines

Lib/macpath.py

-# module 'macpath' -- pathname (or -related) operations for the Macintosh
+"""Pathname and path-related operations for the Macintosh."""
 
 import string
 import os
@@ -10,77 +10,77 @@ from stat import *
 normcase = string.lower
 
 
-# Return true if a path is absolute.
-# On the Mac, relative paths begin with a colon,
-# but as a special case, paths with no colons at all are also relative.
-# Anything else is absolute (the string up to the first colon is the
-# volume name).
-
 def isabs(s):
-	return ':' in s and s[0] <> ':'
+    """Return true if a path is absolute.
+    On the Mac, relative paths begin with a colon,
+    but as a special case, paths with no colons at all are also relative.
+    Anything else is absolute (the string up to the first colon is the
+    volume name)."""
+
+    return ':' in s and s[0] <> ':'
 
 
 def join(s, *p):
-	path = s
-	for t in p:
-		if (not s) or isabs(t):
-			path = t
-			continue
-		if t[:1] == ':':
-			t = t[1:]
-		if ':' not in path:
-			path = ':' + path
-		if path[-1:] <> ':':
-			path = path + ':'
-		path = path + t
-	return path
-
-
-# Split a pathname in two parts: the directory leading up to the final bit,
-# and the basename (the filename, without colons, in that directory).
-# The result (s, t) is such that join(s, t) yields the original argument.
+    path = s
+    for t in p:
+        if (not s) or isabs(t):
+            path = t
+            continue
+        if t[:1] == ':':
+            t = t[1:]
+        if ':' not in path:
+            path = ':' + path
+        if path[-1:] <> ':':
+            path = path + ':'
+        path = path + t
+    return path
+
 
 def split(s):
-	if ':' not in s: return '', s
-	colon = 0
-	for i in range(len(s)):
-		if s[i] == ':': colon = i+1
-	path, file = s[:colon-1], s[colon:]
-	if path and not ':' in path:
-		path = path + ':'
-	return path, file
+    """Split a pathname into two parts: the directory leading up to the final
+    bit, and the basename (the filename, without colons, in that directory).
+    The result (s, t) is such that join(s, t) yields the original argument."""
 
+    if ':' not in s: return '', s
+    colon = 0
+    for i in range(len(s)):
+        if s[i] == ':': colon = i+1
+    path, file = s[:colon-1], s[colon:]
+    if path and not ':' in path:
+        path = path + ':'
+    return path, file
 
-# Split a path in root and extension.
-# The extension is everything starting at the last dot in the last
-# pathname component; the root is everything before that.
-# It is always true that root + ext == p.
 
 def splitext(p):
-	root, ext = '', ''
-	for c in p:
-		if c == ':':
-			root, ext = root + ext + c, ''
-		elif c == '.':
-			if ext:
-				root, ext = root + ext, c
-			else:
-				ext = c
-		elif ext:
-			ext = ext + c
-		else:
-			root = root + c
-	return root, ext
-
-
-# Split a pathname into a drive specification and the rest of the
-# path.  Useful on DOS/Windows/NT; on the Mac, the drive is always
-# empty (don't use the volume name -- it doesn't have the same
-# syntactic and semantic oddities as DOS drive letters, such as there
-# being a separate current directory per drive).
+    """Split a path into root and extension.
+    The extension is everything starting at the last dot in the last
+    pathname component; the root is everything before that.
+    It is always true that root + ext == p."""
+
+    root, ext = '', ''
+    for c in p:
+        if c == ':':
+            root, ext = root + ext + c, ''
+        elif c == '.':
+            if ext:
+                root, ext = root + ext, c
+            else:
+                ext = c
+        elif ext:
+            ext = ext + c
+        else:
+            root = root + c
+    return root, ext
+
 
 def splitdrive(p):
-	return '', p
+    """Split a pathname into a drive specification and the rest of the
+    path.  Useful on DOS/Windows/NT; on the Mac, the drive is always
+    empty (don't use the volume name -- it doesn't have the same
+    syntactic and semantic oddities as DOS drive letters, such as there
+    being a separate current directory per drive)."""
+
+    return '', p
 
 
 # Short interfaces to split()
@@ -89,14 +89,14 @@ def dirname(s): return split(s)[0]
 def basename(s): return split(s)[1]
 
 
-# Return true if the pathname refers to an existing directory.
-
 def isdir(s):
-	try:
-		st = os.stat(s)
-	except os.error:
-		return 0
-	return S_ISDIR(st[ST_MODE])
+    """Return true if the pathname refers to an existing directory."""
+
+    try:
+        st = os.stat(s)
+    except os.error:
+        return 0
+    return S_ISDIR(st[ST_MODE])
 
 
 # Get size, mtime, atime of files.
@@ -117,105 +117,103 @@ def getatime(filename):
     return st[ST_MTIME]
 
 
-# Return true if the pathname refers to a symbolic link.
-# (Always false on the Mac, until we understand Aliases.)
-
 def islink(s):
-	return 0
+    """Return true if the pathname refers to a symbolic link.
+    Always false on the Mac, until we understand Aliases.)"""
 
+    return 0
 
-# Return true if the pathname refers to an existing regular file.
 
 def isfile(s):
-	try:
-		st = os.stat(s)
-	except os.error:
-		return 0
-	return S_ISREG(st[ST_MODE])
+    """Return true if the pathname refers to an existing regular file."""
 
+    try:
+        st = os.stat(s)
+    except os.error:
+        return 0
+    return S_ISREG(st[ST_MODE])
 
-# Return true if the pathname refers to an existing file or directory.
 
 def exists(s):
-	try:
-		st = os.stat(s)
-	except os.error:
-		return 0
-	return 1
-
-#
-# dummy expandvars to retain interface-compatability with other
-# operating systems.
+    """Return true if the pathname refers to an existing file or directory."""
+
+    try:
+        st = os.stat(s)
+    except os.error:
+        return 0
+    return 1
+
+
 def expandvars(path):
-	return path
+    """Dummy to retain interface-compatibility with other operating systems."""
+    return path
 
-#
-# dummy expanduser to retain interface-compatability with other
-# operating systems.
-def expanduser(path):
-	return path
 
-# Normalize a pathname: get rid of '::' sequences by backing up,
-# e.g., 'foo:bar::bletch' becomes 'foo:bletch'.
-# Raise the exception norm_error below if backing up is impossible,
-# e.g., for '::foo'.
-# XXX The Unix version doesn't raise an exception but simply
-# returns an unnormalized path.  Should do so here too.
+def expanduser(path):
+    """Dummy to retain interface-compatibility with other operating systems."""
+    return path
 
 norm_error = 'macpath.norm_error: path cannot be normalized'
 
 def normpath(s):
-	import string
-	if ':' not in s:
-		return ':' + s
-	f = string.splitfields(s, ':')
-	pre = []
-	post = []
-	if not f[0]:
-		pre = f[:1]
-		f = f[1:]
-	if not f[len(f)-1]:
-		post = f[-1:]
-		f = f[:-1]
-	res = []
-	for seg in f:
-		if seg:
-			res.append(seg)
-		else:
-			if not res: raise norm_error, 'path starts with ::'
-			del res[len(res)-1]
-			if not (pre or res):
-				raise norm_error, 'path starts with volume::'
-	if pre: res = pre + res
-	if post: res = res + post
-	s = res[0]
-	for seg in res[1:]:
-		s = s + ':' + seg
-	return s
-
-
-# Directory tree walk.
-# For each directory under top (including top itself),
-# func(arg, dirname, filenames) is called, where
-# dirname is the name of the directory and filenames is the list
-# of files (and subdirectories etc.) in the directory.
-# The func may modify the filenames list, to implement a filter,
-# or to impose a different order of visiting.
+    """Normalize a pathname: get rid of '::' sequences by backing up,
+    e.g., 'foo:bar::bletch' becomes 'foo:bletch'.
+    Raise the exception norm_error below if backing up is impossible,
+    e.g., for '::foo'."""
+    # XXX The Unix version doesn't raise an exception but simply
+    # returns an unnormalized path.  Should do so here too.
+
+    import string
+    if ':' not in s:
+        return ':' + s
+    f = string.splitfields(s, ':')
+    pre = []
+    post = []
+    if not f[0]:
+        pre = f[:1]
+        f = f[1:]
+    if not f[len(f)-1]:
+        post = f[-1:]
+        f = f[:-1]
+    res = []
+    for seg in f:
+        if seg:
+            res.append(seg)
+        else:
+            if not res: raise norm_error, 'path starts with ::'
+            del res[len(res)-1]
+            if not (pre or res):
+                raise norm_error, 'path starts with volume::'
+    if pre: res = pre + res
+    if post: res = res + post
+    s = res[0]
+    for seg in res[1:]:
+        s = s + ':' + seg
+    return s
+
 
 def walk(top, func, arg):
-	try:
-		names = os.listdir(top)
-	except os.error:
-		return
-	func(arg, top, names)
-	for name in names:
-		name = join(top, name)
-		if isdir(name):
-			walk(name, func, arg)
-
-
-# Return an absolute path.
+    """Directory tree walk.
+    For each directory under top (including top itself),
+    func(arg, dirname, filenames) is called, where
+    dirname is the name of the directory and filenames is the list
+    of files (and subdirectories etc.) in the directory.
+    The func may modify the filenames list, to implement a filter,
+    or to impose a different order of visiting."""
+
+    try:
+        names = os.listdir(top)
+    except os.error:
+        return
+    func(arg, top, names)
+    for name in names:
+        name = join(top, name)
+        if isdir(name):
+            walk(name, func, arg)
+
+
 def abspath(path):
+    """Return an absolute path."""
     if not isabs(path):
         path = join(os.getcwd(), path)
     return normpath(path)

Lib/mailcap.py

@@ -9,8 +9,11 @@ import string
 def getcaps():
     """Return a dictionary containing the mailcap database.
     
-    The dictionary maps a MIME type (in all lowercase,
-    e.g. 'text/plain') to a list of corresponding mailcap entries.
+    The dictionary maps a MIME type (in all lowercase, e.g. 'text/plain')
+    to a list of dictionaries corresponding to mailcap entries.  The list
+    collects all the entries for that MIME type from all available mailcap
+    files.  Each dictionary contains key-value pairs for that MIME type,
+    where the viewing command is stored with the key "view".
 
     """
     caps = {}
@@ -48,6 +51,14 @@ def listmailcapfiles():
 # Part 2: the parser.
 
 def readmailcapfile(fp):
+    """Read a mailcap file and return a dictionary keyed by MIME type.
+
+    Each MIME type is mapped to an entry consisting of a list of
+    dictionaries; the list will contain more than one such dictionary
+    if a given MIME type appears more than once in the mailcap file.
+    Each dictionary contains key-value pairs for that MIME type, where
+    the viewing command is stored with the key "view".
+    """
     caps = {}
     while 1:
         line = fp.readline()
@@ -78,6 +89,11 @@ def readmailcapfile(fp):
     return caps
 
 def parseline(line):
+    """Parse one entry in a mailcap file and return a dictionary.
+
+    The viewing command is stored as the value with the key "view",
+    and the rest of the fields produce key-value pairs in the dict.
+    """
     fields = []
     i, n = 0, len(line)
     while i < n:
@@ -104,6 +120,7 @@ def parseline(line):
     return key, fields
 
 def parsefield(line, i, n):
+    """Separate one key-value pair in a mailcap entry."""
     start = i
     while i < n:
         c = line[i]

Lib/mimetools.py

-# Various tools used by MIME-reading or MIME-writing programs.
+"""Various tools used by MIME-reading or MIME-writing programs."""
 
 
 import os
@@ -7,10 +7,9 @@ import string
 import tempfile
 
 
-# A derived class of rfc822.Message that knows about MIME headers and
-# contains some hooks for decoding encoded and multipart messages.
-
 class Message(rfc822.Message):
+	"""A derived class of rfc822.Message that knows about MIME headers and
+	contains some hooks for decoding encoded and multipart messages."""
 
 	def __init__(self, fp, seekable = 1):
 		rfc822.Message.__init__(self, fp, seekable)
@@ -96,17 +95,17 @@ class Message(rfc822.Message):
 # -----------------
 
 
-# Return a random string usable as a multipart boundary.
-# The method used is so that it is *very* unlikely that the same
-# string of characters will every occur again in the Universe,
-# so the caller needn't check the data it is packing for the
-# occurrence of the boundary.
-#
-# The boundary contains dots so you have to quote it in the header.
-
 _prefix = None
 
 def choose_boundary():
+	"""Return a random string usable as a multipart boundary.
+	The method used is so that it is *very* unlikely that the same
+	string of characters will every occur again in the Universe,
+	so the caller needn't check the data it is packing for the
+	occurrence of the boundary.
+
+	The boundary contains dots so you have to quote it in the header."""
+
 	global _prefix
 	import time
 	import random
@@ -131,6 +130,7 @@ def choose_boundary():
 # Subroutines for decoding some common content-transfer-types
 
 def decode(input, output, encoding):
+	"""Decode common content-transfer-encodings (base64, quopri, uuencode)."""
 	if encoding == 'base64':
 		import base64
 		return base64.decode(input, output)
@@ -147,6 +147,7 @@ def decode(input, output, encoding):
 		      'unknown Content-Transfer-Encoding: %s' % encoding
 
 def encode(input, output, encoding):
+	"""Encode common content-transfer-encodings (base64, quopri, uuencode)."""
 	if encoding == 'base64':
 		import base64
 		return base64.encode(input, output)

Lib/mimify.py

@@ -2,7 +2,7 @@
 
 '''Mimification and unmimification of mail messages.
 
-decode quoted-printable parts of a mail message or encode using
+Decode quoted-printable parts of a mail message or encode using
 quoted-printable.
 
 Usage:
@@ -39,9 +39,8 @@ mime_head = re.compile('=\\?iso-8859-1\\?q\\?([^? \t\n]+)\\?=', re.I)
 repl = re.compile('^subject:\\s+re: ', re.I)
 
 class File:
-	'''A simple fake file object that knows about limited
-	   read-ahead and boundaries.
-	   The only supported method is readline().'''
+	"""A simple fake file object that knows about limited read-ahead and
+	boundaries.  The only supported method is readline()."""
 
 	def __init__(self, file, boundary):
 		self.file = file
@@ -87,7 +86,7 @@ class HeaderFile:
 			self.peek = None
 
 def mime_decode(line):
-	'''Decode a single line of quoted-printable text to 8bit.'''
+	"""Decode a single line of quoted-printable text to 8bit."""
 	newline = ''
 	pos = 0
 	while 1:
@@ -100,7 +99,7 @@ def mime_decode(line):
 	return newline + line[pos:]
 
 def mime_decode_header(line):
-	'''Decode a header line to 8bit.'''
+	"""Decode a header line to 8bit."""
 	newline = ''
 	pos = 0
 	while 1:
@@ -115,7 +114,7 @@ def mime_decode_header(line):
 	return newline + line[pos:]
 
 def unmimify_part(ifile, ofile, decode_base64 = 0):
-	'''Convert a quoted-printable part of a MIME mail message to 8bit.'''
+	"""Convert a quoted-printable part of a MIME mail message to 8bit."""
 	multipart = None
 	quoted_printable = 0
 	is_base64 = 0
@@ -200,7 +199,7 @@ def unmimify_part(ifile, ofile, decode_base64 = 0):
 			ofile.write(pref + line)
 
 def unmimify(infile, outfile, decode_base64 = 0):
-	'''Convert quoted-printable parts of a MIME mail message to 8bit.'''
+	"""Convert quoted-printable parts of a MIME mail message to 8bit."""
 	if type(infile) == type(''):
 		ifile = open(infile)
 		if type(outfile) == type('') and infile == outfile:
@@ -221,8 +220,8 @@ mime_char = re.compile('[=\177-\377]') # quote these chars in body
 mime_header_char = re.compile('[=?\177-\377]') # quote these in header
 
 def mime_encode(line, header):
-	'''Code a single line as quoted-printable.
-	   If header is set, quote some extra characters.'''
+	"""Code a single line as quoted-printable.
+	If header is set, quote some extra characters."""
 	if header:
 		reg = mime_header_char
 	else:
@@ -255,7 +254,7 @@ def mime_encode(line, header):
 mime_header = re.compile('([ \t(]|^)([-a-zA-Z0-9_+]*[\177-\377][-a-zA-Z0-9_+\177-\377]*)([ \t)]|\n)')
 
 def mime_encode_header(line):
-	'''Code a single header line as quoted-printable.'''
+	"""Code a single header line as quoted-printable."""
 	newline = ''
 	pos = 0
 	while 1:
@@ -273,7 +272,7 @@ cte = re.compile('^content-transfer-encoding:', re.I)
 iso_char = re.compile('[\177-\377]')
 
 def mimify_part(ifile, ofile, is_mime):
-	'''Convert an 8bit part of a MIME mail message to quoted-printable.'''
+	"""Convert an 8bit part of a MIME mail message to quoted-printable."""
 	has_cte = is_qp = is_base64 = 0
 	multipart = None
 	must_quote_body = must_quote_header = has_iso_chars = 0
@@ -408,7 +407,7 @@ def mimify_part(ifile, ofile, is_mime):
 			ofile.write(line)
 
 def mimify(infile, outfile):
-	'''Convert 8bit parts of a MIME mail message to quoted-printable.'''
+	"""Convert 8bit parts of a MIME mail message to quoted-printable."""
 	if type(infile) == type(''):
 		ifile = open(infile)
 		if type(outfile) == type('') and infile == outfile:

Lib/multifile.py

-# A class that makes each part of a multipart message "feel" like an
-# ordinary file, as long as you use fp.readline().  Allows recursive
-# use, for nested multipart messages.  Probably best used together
-# with module mimetools.
-#
-# Suggested use:
-#
-# real_fp = open(...)
-# fp = MultiFile(real_fp)
-#
-# "read some lines from fp"
-# fp.push(separator)
-# while 1:
-#	"read lines from fp until it returns an empty string" (A)
-#	if not fp.next(): break
-# fp.pop()
-# "read remaining lines from fp until it returns an empty string"
-#
-# The latter sequence may be used recursively at (A).
-# It is also allowed to use multiple push()...pop() sequences.
-#
-# If seekable is given as 0, the class code will not do the bookeeping
-# it normally attempts in order to make seeks relative to the beginning of the
-# current file part.  This may be useful when using MultiFile with a non-
-# seekable stream object.
+"""A readline()-style interface to the parts of a multipart message.
+
+The MultiFile class makes each part of a multipart message "feel" like
+an ordinary file, as long as you use fp.readline().  Allows recursive
+use, for nested multipart messages.  Probably best used together
+with module mimetools.
+
+Suggested use:
+
+real_fp = open(...)
+fp = MultiFile(real_fp)
+
+"read some lines from fp"
+fp.push(separator)
+while 1:
+	"read lines from fp until it returns an empty string" (A)
+	if not fp.next(): break
+fp.pop()
+"read remaining lines from fp until it returns an empty string"
+
+The latter sequence may be used recursively at (A).
+It is also allowed to use multiple push()...pop() sequences.
+
+If seekable is given as 0, the class code will not do the bookeeping
+it normally attempts in order to make seeks relative to the beginning of the
+current file part.  This may be useful when using MultiFile with a non-
+seekable stream object.
+"""
 
 import sys
 import string
@@ -30,9 +33,9 @@ import string
 Error = 'multifile.Error'
 
 class MultiFile:
-	#
+
 	seekable = 0
-	#
+
 	def __init__(self, fp, seekable=1):
 		self.fp = fp
 		self.stack = [] # Grows down
@@ -42,12 +45,12 @@ class MultiFile:
 			self.seekable = 1
 			self.start = self.fp.tell()
 			self.posstack = [] # Grows down
-	#
+
 	def tell(self):
 		if self.level > 0:
 			return self.lastpos
 		return self.fp.tell() - self.start
-	#
+
 	def seek(self, pos, whence=0):
 		here = self.tell()
 		if whence:
@@ -64,7 +67,7 @@ class MultiFile:
 		self.fp.seek(pos + self.start)
 		self.level = 0
 		self.last = 0
-	#
+
 	def readline(self):
 		if self.level > 0:
 			return ''
@@ -105,7 +108,7 @@ class MultiFile:
 		if self.level > 1:
 			raise Error,'Missing endmarker in MultiFile.readline()'
 		return ''
-	#
+
 	def readlines(self):
 		list = []
 		while 1:
@@ -113,10 +116,10 @@ class MultiFile:
 			if not line: break
 			list.append(line)
 		return list
-	#
+
 	def read(self): # Note: no size argument -- read until EOF only!
 		return string.joinfields(self.readlines(), '')
-	#
+
 	def next(self):
 		while self.readline(): pass
 		if self.level > 1 or self.last:
@@ -126,7 +129,7 @@ class MultiFile:
 		if self.seekable:
 			self.start = self.fp.tell()
 		return 1
-	#
+
 	def push(self, sep):
 		if self.level > 0:
 			raise Error, 'bad MultiFile.push() call'
@@ -134,7 +137,7 @@ class MultiFile:
 		if self.seekable:
 			self.posstack.insert(0, self.start)
 			self.start = self.fp.tell()
-	#
+
 	def pop(self):
 		if self.stack == []:
 			raise Error, 'bad MultiFile.pop() call'
@@ -149,12 +152,12 @@ class MultiFile:
 			del self.posstack[0]
 			if self.level > 0:
 				self.lastpos = abslastpos - self.start
-	#
+
 	def is_data(self, line):
 		return line[:2] <> '--'
-	#
+
 	def section_divider(self, str):
 		return "--" + str
-	#
+
 	def end_marker(self, str):
 		return "--" + str + "--"

Lib/mutex.py

-# Mutual exclusion -- for use with module sched
+"""Mutual exclusion -- for use with module sched
+
+A mutex has two pieces of state -- a 'locked' bit and a queue.
+When the mutex is not locked, the queue is empty.
+Otherwise, the queue contains 0 or more (function, argument) pairs
+representing functions (or methods) waiting to acquire the lock.
+When the mutex is unlocked while the queue is not empty,
+the first queue entry is removed and its function(argument) pair called,
+implying it now has the lock.
+
+Of course, no multi-threading is implied -- hence the funny interface
+for lock, where a function is called once the lock is aquired.
+"""
 
-# A mutex has two pieces of state -- a 'locked' bit and a queue.
-# When the mutex is not locked, the queue is empty.
-# Otherwise, the queue contains 0 or more (function, argument) pairs
-# representing functions (or methods) waiting to acquire the lock.
-# When the mutex is unlocked while the queue is not empty,
-# the first queue entry is removed and its function(argument) pair called,
-# implying it now has the lock.
-#
-# Of course, no multi-threading is implied -- hence the funny interface
-# for lock, where a function is called once the lock is aquired.
-#
 class mutex:
-	#
-	# Create a new mutex -- initially unlocked
-	#
 	def __init__(self):
+		"""Create a new mutex -- initially unlocked."""
 		self.locked = 0
 		self.queue = []
-	#
-	# Test the locked bit of the mutex
-	#
+
 	def test(self):
+		"""Test the locked bit of the mutex."""
 		return self.locked
-	#
-	# Atomic test-and-set -- grab the lock if it is not set,
-	# return true if it succeeded
-	#
+
 	def testandset(self):
+		"""Atomic test-and-set -- grab the lock if it is not set,
+		return true if it succeeded."""
 		if not self.locked:
 			self.locked = 1
 			return 1
 		else:
 			return 0
-	#
-	# Lock a mutex, call the function with supplied argument
-	# when it is acquired.
-	# If the mutex is already locked, place function and argument
-	# in the queue.
-	#
+
 	def lock(self, function, argument):
+		"""Lock a mutex, call the function with supplied argument
+		when it is acquired.  If the mutex is already locked, place
+		function and argument in the queue."""
 		if self.testandset():
 			function(argument)
 		else:
 			self.queue.append((function, argument))
-	#
-	# Unlock a mutex.  If the queue is not empty, call the next
-	# function with its argument.
-	#
+
 	def unlock(self):
+		"""Unlock a mutex.  If the queue is not empty, call the next
+		function with its argument."""
 		if self.queue:
 			function, argument = self.queue[0]
 			del self.queue[0]
 			function(argument)
 		else:
 			self.locked = 0
-	#

Lib/netrc.py

+"""An object-oriented interface to .netrc files."""
+
 # Module and documentation by Eric S. Raymond, 21 Dec 1998 
 
 import os, shlex
@@ -63,7 +65,7 @@ class netrc:
                     raise SyntaxError, "bad follower token %s, file %s, line %d"%(tt,file,lexer.lineno)
 
     def authenticators(self, host):
-        "Return a (user, account, password) tuple for given host."
+        """Return a (user, account, password) tuple for given host."""
         if self.hosts.has_key(host):
             return self.hosts[host]
         elif self.hosts.has_key('default'):
@@ -72,7 +74,7 @@ class netrc:
             return None
 
     def __repr__(self):
-        "Dump the class data in the format of a .netrc file"
+        """Dump the class data in the format of a .netrc file."""
         rep = ""
         for host in self.hosts.keys():
             attrs = self.hosts[host]

Lib/nturl2path.py

-#
-# nturl2path convert a NT pathname to a file URL and 
-# vice versa  
+"""Convert a NT pathname to a file URL and vice versa."""
 
 def url2pathname(url):
 	""" Convert a URL to a DOS path...
@@ -34,7 +32,6 @@ def url2pathname(url):
 	return path
 
 def pathname2url(p):
-
 	""" Convert a DOS path name to a file url...
 		C:\foo\bar\spam.foo
 

Lib/os.py

-# os.py -- either mac, dos or posix depending on what system we're on.
-
-# This exports:
-# - all functions from either posix or mac, e.g., os.unlink, os.stat, etc.
-# - os.path is either module posixpath or macpath
-# - os.name is either 'posix' or 'mac'
-# - os.curdir is a string representing the current directory ('.' or ':')
-# - os.pardir is a string representing the parent directory ('..' or '::')
-# - os.sep is the (or a most common) pathname separator ('/' or ':' or '\\')
-# - os.altsep is the alternatte pathname separator (None or '/')
-# - os.pathsep is the component separator used in $PATH etc
-# - os.defpath is the default search path for executables
-
-# Programs that import and use 'os' stand a better chance of being
-# portable between different platforms.  Of course, they must then
-# only use functions that are defined by all platforms (e.g., unlink
-# and opendir), and leave all pathname manipulation to os.path
-# (e.g., split and join).
+"""os.py -- either mac, dos or posix depending on what system we're on.
+
+This exports:
+  - all functions from either posix or mac, e.g., os.unlink, os.stat, etc.
+  - os.path is either module posixpath or macpath
+  - os.name is either 'posix' or 'mac'
+  - os.curdir is a string representing the current directory ('.' or ':')
+  - os.pardir is a string representing the parent directory ('..' or '::')
+  - os.sep is the (or a most common) pathname separator ('/' or ':' or '\\')
+  - os.altsep is the alternatte pathname separator (None or '/')
+  - os.pathsep is the component separator used in $PATH etc
+  - os.defpath is the default search path for executables
+
+Programs that import and use 'os' stand a better chance of being
+portable between different platforms.  Of course, they must then
+only use functions that are defined by all platforms (e.g., unlink
+and opendir), and leave all pathname manipulation to os.path
+(e.g., split and join).
+"""
 
 import sys
 

Lib/pdb.py

 #! /usr/bin/env python
 
-# pdb.py -- finally, a Python debugger!
+"""pdb.py -- finally, a Python debugger!"""
 
 # (See pdb.doc for documentation.)
 
@@ -106,18 +106,18 @@ class Pdb(bdb.Bdb, cmd.Cmd):
 	# Override Bdb methods (except user_call, for now)
 	
 	def user_line(self, frame):
-		# This function is called when we stop or break at this line
+		"""This function is called when we stop or break at this line."""
 		self.interaction(frame, None)
 	
 	def user_return(self, frame, return_value):
-		# This function is called when a return trap is set here
+		"""This function is called when a return trap is set here."""
 		frame.f_locals['__return__'] = return_value
 		print '--Return--'
 		self.interaction(frame, None)
 	
 	def user_exception(self, frame, (exc_type, exc_value, exc_traceback)):
-		# This function is called if an exception occurs,
-		# but only if we are to stop at or just below this level
+		"""This function is called if an exception occurs,
+		but only if we are to stop at or just below this level."""
 		frame.f_locals['__exception__'] = exc_type, exc_value
 		if type(exc_type) == type(''):
 			exc_type_name = exc_type
@@ -148,7 +148,7 @@ class Pdb(bdb.Bdb, cmd.Cmd):
 			print '***', exc_type_name + ':', v
 
 	def precmd(self, line):
-		# Handle alias expansion and ';;' separator
+		"""Handle alias expansion and ';;' separator."""
 		if not line:
 			return line
 		args = string.split(line)
@@ -262,7 +262,7 @@ class Pdb(bdb.Bdb, cmd.Cmd):
 
 	# To be overridden in derived debuggers
 	def defaultFile(self):
-		# Produce a reasonable default
+		"""Produce a reasonable default."""
 		filename = self.curframe.f_code.co_filename
 		if filename == '<string>' and mainpyfile:
 			filename = mainpyfile
@@ -384,7 +384,7 @@ class Pdb(bdb.Bdb, cmd.Cmd):
 				print 'is now unconditional.'
 
 	def do_ignore(self,arg):
-		# arg is bp number followed by ignore count
+		"""arg is bp number followed by ignore count."""
 		args = string.split(arg)
 		bpnum = int(string.strip(args[0]))
 		try:
@@ -406,10 +406,10 @@ class Pdb(bdb.Bdb, cmd.Cmd):
 				print bpnum, 'is reached.'
 
 	def do_clear(self, arg):
-		# Three possibilities, tried in this order:
-		# clear -> clear all breaks, ask for confirmation
-		# clear file:lineno -> clear all breaks at file:lineno
-		# clear bpno bpno ... -> clear breakpoints by number
+		"""Three possibilities, tried in this order:
+		clear -> clear all breaks, ask for confirmation
+		clear file:lineno -> clear all breaks at file:lineno
+		clear bpno bpno ... -> clear breakpoints by number"""
 		if not arg:
 			try:
 				reply = raw_input('Clear all breaks? ')
@@ -851,9 +851,8 @@ class Pdb(bdb.Bdb, cmd.Cmd):
 	def help_pdb(self):
 		help()
 
-	# Helper function for break/clear parsing -- may be overridden
-
 	def lookupmodule(self, filename):
+		"""Helper function for break/clear parsing -- may be overridden."""
 		root, ext = os.path.splitext(filename)
 		if ext == '':
 			filename = filename + '.py'

Lib/pickle.py

-"""create portable serialized representations of Python objects.
+"""Create portable serialized representations of Python objects.
 
 See module cPickle for a (much) faster implementation.
 See module copy_reg for a mechanism for registering custom picklers.

Lib/pipes.py

-# Conversion pipeline templates
-# =============================
-
-
-# The problem:
-# ------------
-# 
-# Suppose you have some data that you want to convert to another format
-# (e.g. from GIF image format to PPM image format).  Maybe the
-# conversion involves several steps (e.g. piping it through compress or
-# uuencode).  Some of the conversion steps may require that their input
-# is a disk file, others may be able to read standard input; similar for
-# their output.  The input to the entire conversion may also be read
-# from a disk file or from an open file, and similar for its output.
-# 
-# The module lets you construct a pipeline template by sticking one or
-# more conversion steps together.  It will take care of creating and
-# removing temporary files if they are necessary to hold intermediate
-# data.  You can then use the template to do conversions from many
-# different sources to many different destinations.  The temporary
-# file names used are different each time the template is used.
-#
-# The templates are objects so you can create templates for many
-# different conversion steps and store them in a dictionary, for
-# instance.
-
-
-# Directions:
-# -----------
-#
-# To create a template:
-#   t = Template()
-#
-# To add a conversion step to a template:
-#   t.append(command, kind)
-# where kind is a string of two characters: the first is '-' if the
-# command reads its standard input or 'f' if it requires a file; the
-# second likewise for the output. The command must be valid /bin/sh
-# syntax.  If input or output files are required, they are passed as
-# $IN and $OUT; otherwise, it must be  possible to use the command in
-# a pipeline.
-#
-# To add a conversion step at the beginning:
-#   t.prepend(command, kind)
-#
-# To convert a file to another file using a template:
-#   sts = t.copy(infile, outfile)
-# If infile or outfile are the empty string, standard input is read or
-# standard output is written, respectively.  The return value is the
-# exit status of the conversion pipeline.
-# 
-# To open a file for reading or writing through a conversion pipeline:
-#   fp = t.open(file, mode)
-# where mode is 'r' to read the file, or 'w' to write it -- just like
-# for the built-in function open() or for os.popen().
-#
-# To create a new template object initialized to a given one:
-#   t2 = t.clone()
-#
-# For an example, see the function test() at the end of the file.
+"""Conversion pipeline templates.
+
+The problem:
+------------
+
+Suppose you have some data that you want to convert to another format
+(e.g. from GIF image format to PPM image format).  Maybe the
+conversion involves several steps (e.g. piping it through compress or
+uuencode).  Some of the conversion steps may require that their input
+is a disk file, others may be able to read standard input; similar for
+their output.  The input to the entire conversion may also be read
+from a disk file or from an open file, and similar for its output.
+
+The module lets you construct a pipeline template by sticking one or
+more conversion steps together.  It will take care of creating and
+removing temporary files if they are necessary to hold intermediate
+data.  You can then use the template to do conversions from many
+different sources to many different destinations.  The temporary
+file names used are different each time the template is used.
+
+The templates are objects so you can create templates for many
+different conversion steps and store them in a dictionary, for
+instance.
+
+
+Directions:
+-----------
+
+To create a template:
+    t = Template()
+
+To add a conversion step to a template:
+   t.append(command, kind)
+where kind is a string of two characters: the first is '-' if the
+command reads its standard input or 'f' if it requires a file; the
+second likewise for the output. The command must be valid /bin/sh
+syntax.  If input or output files are required, they are passed as
+$IN and $OUT; otherwise, it must be  possible to use the command in
+a pipeline.
+
+To add a conversion step at the beginning:
+   t.prepend(command, kind)
+
+To convert a file to another file using a template:
+  sts = t.copy(infile, outfile)
+If infile or outfile are the empty string, standard input is read or
+standard output is written, respectively.  The return value is the
+exit status of the conversion pipeline.
+
+To open a file for reading or writing through a conversion pipeline:
+   fp = t.open(file, mode)
+where mode is 'r' to read the file, or 'w' to write it -- just like
+for the built-in function open() or for os.popen().
+
+To create a new template object initialized to a given one:
+   t2 = t.clone()
+
+For an example, see the function test() at the end of the file.
+"""
 
 
 import sys
@@ -81,37 +80,36 @@ stepkinds = [FILEIN_FILEOUT, STDIN_FILEOUT, FILEIN_STDOUT, STDIN_STDOUT, \
 	     SOURCE, SINK]
 
 
-# A pipeline template is a Template object:
-
 class Template:
+	"""Class representing a pipeline template."""
 
-	# Template() returns a fresh pipeline template
 	def __init__(self):
+		"""Template() returns a fresh pipeline template."""
 		self.debugging = 0
 		self.reset()
 
-	# t.__repr__() implements `t`
 	def __repr__(self):
+		"""t.__repr__() implements `t`."""
 		return '<Template instance, steps=' + `self.steps` + '>'
 
-	# t.reset() restores a pipeline template to its initial state
 	def reset(self):
+		"""t.reset() restores a pipeline template to its initial state."""
 		self.steps = []
 
-	# t.clone() returns a new pipeline template with identical
-	# initial state as the current one
 	def clone(self):
+		"""t.clone() returns a new pipeline template with identical
+		initial state as the current one."""
 		t = Template()
 		t.steps = self.steps[:]
 		t.debugging = self.debugging
 		return t
 
-	# t.debug(flag) turns debugging on or off
 	def debug(self, flag):
+		"""t.debug(flag) turns debugging on or off."""
 		self.debugging = flag
 
-	# t.append(cmd, kind) adds a new step at the end
 	def append(self, cmd, kind):
+		"""t.append(cmd, kind) adds a new step at the end."""
 		if type(cmd) <> type(''):
 			raise TypeError, \
 			      'Template.append: cmd must be a string'
@@ -132,8 +130,8 @@ class Template:
 			      'Template.append: missing $OUT in cmd'
 		self.steps.append((cmd, kind))
 
-	# t.prepend(cmd, kind) adds a new step at the front
 	def prepend(self, cmd, kind):
+		"""t.prepend(cmd, kind) adds a new step at the front."""
 		if type(cmd) <> type(''):
 			raise TypeError, \
 			      'Template.prepend: cmd must be a string'
@@ -154,9 +152,9 @@ class Template:
 			      'Template.prepend: missing $OUT in cmd'
 		self.steps.insert(0, (cmd, kind))
 
-	# t.open(file, rw) returns a pipe or file object open for
-	# reading or writing; the file is the other end of the pipeline
 	def open(self, file, rw):
+		"""t.open(file, rw) returns a pipe or file object open for
+		reading or writing; the file is the other end of the pipeline."""
 		if rw == 'r':
 			return self.open_r(file)
 		if rw == 'w':
@@ -164,10 +162,9 @@ class Template:
 		raise ValueError, \
 		      'Template.open: rw must be \'r\' or \'w\', not ' + `rw`
 
-	# t.open_r(file) and t.open_w(file) implement
-	# t.open(file, 'r') and t.open(file, 'w') respectively
-
 	def open_r(self, file):
+		"""t.open_r(file) and t.open_w(file) implement
+		t.open(file, 'r') and t.open(file, 'w') respectively."""
 		if self.steps == []:
 			return open(file, 'r')
 		if self.steps[-1][1] == SINK:

Lib/popen2.py

+"""Spawn a command with pipes to its stdin, stdout, and optionally stderr.
+
+The normal os.popen(cmd, mode) call spawns a shell command and provides a
+file interface to just the input or output of the process depending on
+whether mode is 'r' or 'w'.  This module provides the functions popen2(cmd)
+and popen3(cmd) which return two or three pipes to the spawned command.
+"""
+
 import os
 import sys
 import string
@@ -11,7 +19,15 @@ def _cleanup():
         inst.poll()
 
 class Popen3:
+    """Class representing a child process.  Normally instances are created
+    by the factory functions popen2() and popen3()."""
+
     def __init__(self, cmd, capturestderr=0, bufsize=-1):
+        """The parameter 'cmd' is the shell command to execute in a
+        sub-process.  The 'capturestderr' flag, if true, specifies that
+        the object should capture standard error output of the child process.
+        The default is false.  If the 'bufsize' parameter is specified, it
+        specifies the size of the I/O buffers to/from the child process."""
         if type(cmd) == type(''):
             cmd = ['/bin/sh', '-c', cmd]
         p2cread, p2cwrite = os.pipe()
@@ -51,7 +67,10 @@ class Popen3:
             self.childerr = None
         self.sts = -1 # Child not completed yet
         _active.append(self)
+
     def poll(self):
+        """Return the exit status of the child process if it has finished,
+        or -1 if it hasn't finished yet."""
         if self.sts < 0:
             try:
                 pid, sts = os.waitpid(self.pid, os.WNOHANG)
@@ -61,7 +80,9 @@ class Popen3:
             except os.error:
                 pass
         return self.sts
+
     def wait(self):
+        """Wait for and return the exit status of the child process."""
         pid, sts = os.waitpid(self.pid, 0)
         if pid == self.pid:
             self.sts = sts
@@ -69,11 +90,17 @@ class Popen3:
         return self.sts
 
 def popen2(cmd, bufsize=-1):
+    """Execute the shell command 'cmd' in a sub-process.  If 'bufsize' is
+    specified, it sets the buffer size for the I/O pipes.  The file objects
+    (child_stdout, child_stdin) are returned."""
     _cleanup()
     inst = Popen3(cmd, 0, bufsize)
     return inst.fromchild, inst.tochild
 
 def popen3(cmd, bufsize=-1):
+    """Execute the shell command 'cmd' in a sub-process.  If 'bufsize' is
+    specified, it sets the buffer size for the I/O pipes.  The file objects
+    (child_stdout, child_stdin, child_stderr) are returned."""
     _cleanup()
     inst = Popen3(cmd, 1, bufsize)
     return inst.fromchild, inst.tochild, inst.childerr

Lib/posixfile.py

-#
-# Start of posixfile.py
-#
-
-#
-# Extended file operations
-#
-# f = posixfile.open(filename, [mode, [bufsize]])
-#       will create a new posixfile object
-#
-# f = posixfile.fileopen(fileobject)
-#       will create a posixfile object from a builtin file object
-#
-# f.file()
-#       will return the original builtin file object
-#
-# f.dup()
-#       will return a new file object based on a new filedescriptor
-#
-# f.dup2(fd)
-#       will return a new file object based on the given filedescriptor
-#
-# f.flags(mode)
-#       will turn on the associated flag (merge)
-#       mode can contain the following characters:
-#
-#   (character representing a flag)
-#       a       append only flag
-#       c       close on exec flag
-#       n       no delay flag
-#       s       synchronization flag
-#   (modifiers)
-#       !       turn flags 'off' instead of default 'on'
-#       =       copy flags 'as is' instead of default 'merge'
-#       ?       return a string in which the characters represent the flags
-#               that are set
-#
-#       note: - the '!' and '=' modifiers are mutually exclusive.
-#             - the '?' modifier will return the status of the flags after they
-#               have been changed by other characters in the mode string
-#
-# f.lock(mode [, len [, start [, whence]]])
-#       will (un)lock a region
-#       mode can contain the following characters:
-#
-#   (character representing type of lock)
-#       u       unlock
-#       r       read lock
-#       w       write lock
-#   (modifiers)
-#       |       wait until the lock can be granted
-#       ?       return the first lock conflicting with the requested lock
-#               or 'None' if there is no conflict. The lock returned is in the
-#               format (mode, len, start, whence, pid) where mode is a
-#               character representing the type of lock ('r' or 'w')
-#
-#       note: - the '?' modifier prevents a region from being locked; it is
-#               query only
-#
+"""Extended file operations available in POSIX.
+
+f = posixfile.open(filename, [mode, [bufsize]])
+      will create a new posixfile object
+
+f = posixfile.fileopen(fileobject)
+      will create a posixfile object from a builtin file object
+
+f.file()
+      will return the original builtin file object
+
+f.dup()
+      will return a new file object based on a new filedescriptor
+
+f.dup2(fd)
+      will return a new file object based on the given filedescriptor
+
+f.flags(mode)
+      will turn on the associated flag (merge)
+      mode can contain the following characters:
+
+  (character representing a flag)
+      a       append only flag
+      c       close on exec flag
+      n       no delay flag
+      s       synchronization flag
+  (modifiers)
+      !       turn flags 'off' instead of default 'on'
+      =       copy flags 'as is' instead of default 'merge'
+      ?       return a string in which the characters represent the flags
+              that are set
+
+      note: - the '!' and '=' modifiers are mutually exclusive.
+            - the '?' modifier will return the status of the flags after they
+              have been changed by other characters in the mode string
+
+f.lock(mode [, len [, start [, whence]]])
+      will (un)lock a region
+      mode can contain the following characters:
+
+  (character representing type of lock)
+      u       unlock
+      r       read lock
+      w       write lock
+  (modifiers)
+      |       wait until the lock can be granted
+      ?       return the first lock conflicting with the requested lock
+              or 'None' if there is no conflict. The lock returned is in the
+              format (mode, len, start, whence, pid) where mode is a
+              character representing the type of lock ('r' or 'w')
+
+      note: - the '?' modifier prevents a region from being locked; it is
+              query only
+"""
 
 class _posixfile_:
+    """File wrapper class that provides extra POSIX file routines."""
+
     states = ['open', 'closed']
 
     #
@@ -215,13 +212,12 @@ class _posixfile_:
                 else:
                     return 'w', l_len, l_start, l_whence, l_pid
 
-#
-# Public routine to obtain a posixfile object
-#
 def open(name, mode='r', bufsize=-1):
+    """Public routine to open a file as a posixfile object."""
     return _posixfile_().open(name, mode, bufsize)
 
 def fileopen(file):
+    """Public routine to get a posixfile object from a Python file object."""
     return _posixfile_().fileopen(file)
 
 #

Lib/posixpath.py

-# Module 'posixpath' -- common operations on Posix pathnames.
-# Some of this can actually be useful on non-Posix systems too, e.g.
-# for manipulation of the pathname component of URLs.
-# The "os.path" name is an alias for this module on Posix systems;
-# on other systems (e.g. Mac, Windows), os.path provides the same
-# operations in a manner specific to that platform, and is an alias
-# to another module (e.g. macpath, ntpath).
-"""Common pathname manipulations, Posix version. 
-Instead of importing this module
-directly, import os and refer to this module as os.path.
+"""Common operations on Posix pathnames.
+
+Instead of importing this module directly, import os and refer to
+this module as os.path.  The "os.path" name is an alias for this
+module on Posix systems; on other systems (e.g. Mac, Windows),
+os.path provides the same operations in a manner specific to that
+platform, and is an alias to another module (e.g. macpath, ntpath).
+
+Some of this can actually be useful on non-Posix systems too, e.g.
+for manipulation of the pathname component of URLs.
 """
 
 import os
@@ -369,8 +369,8 @@ def normpath(path):
     return slashes + string.joinfields(comps, '/')
 
 
-# Return an absolute path.
 def abspath(path):
+    """Return an absolute path."""
     if not isabs(path):
         path = join(os.getcwd(), path)
     return normpath(path)

Lib/profile.py

@@ -7,6 +7,7 @@
 #
 # See profile.doc for more information
 
+"""Class for profiling Python code."""
 
 # Copyright 1994, by InfoSeek Corporation, all rights reserved.
 # Written by James Roskind
@@ -79,44 +80,43 @@ def help():
 		print 'along the Python search path'
 
 
-#**************************************************************************
-# class Profile documentation:
-#**************************************************************************
-# self.cur is always a tuple.  Each such tuple corresponds to a stack
-# frame that is currently active (self.cur[-2]).  The following are the
-# definitions of its members.  We use this external "parallel stack" to
-# avoid contaminating the program that we are profiling. (old profiler
-# used to write into the frames local dictionary!!) Derived classes
-# can change the definition of some entries, as long as they leave
-# [-2:] intact.
-#
-# [ 0] = Time that needs to be charged to the parent frame's function.  It is
-#        used so that a function call will not have to access the timing data
-#        for the parents frame.
-# [ 1] = Total time spent in this frame's function, excluding time in
-#        subfunctions
-# [ 2] = Cumulative time spent in this frame's function, including time in
-#        all subfunctions to this frame.
-# [-3] = Name of the function that corresonds to this frame.  
-# [-2] = Actual frame that we correspond to (used to sync exception handling)
-# [-1] = Our parent 6-tuple (corresonds to frame.f_back)
-#**************************************************************************
-# Timing data for each function is stored as a 5-tuple in the dictionary
-# self.timings[].  The index is always the name stored in self.cur[4].
-# The following are the definitions of the members:
-#
-# [0] = The number of times this function was called, not counting direct
-#       or indirect recursion,
-# [1] = Number of times this function appears on the stack, minus one
-# [2] = Total time spent internal to this function
-# [3] = Cumulative time that this function was present on the stack.  In
-#       non-recursive functions, this is the total execution time from start
-#       to finish of each invocation of a function, including time spent in
-#       all subfunctions.
-# [5] = A dictionary indicating for each function name, the number of times
-#       it was called by us.
-#**************************************************************************
 class Profile:
+	"""Profiler class.
+	
+	self.cur is always a tuple.  Each such tuple corresponds to a stack
+	frame that is currently active (self.cur[-2]).  The following are the
+	definitions of its members.  We use this external "parallel stack" to
+	avoid contaminating the program that we are profiling. (old profiler
+	used to write into the frames local dictionary!!) Derived classes
+	can change the definition of some entries, as long as they leave
+	[-2:] intact.
+
+	[ 0] = Time that needs to be charged to the parent frame's function.
+	       It is used so that a function call will not have to access the
+	       timing data for the parent frame.
+	[ 1] = Total time spent in this frame's function, excluding time in
+	       subfunctions
+	[ 2] = Cumulative time spent in this frame's function, including time in
+	       all subfunctions to this frame.
+	[-3] = Name of the function that corresonds to this frame.  
+	[-2] = Actual frame that we correspond to (used to sync exception handling)
+	[-1] = Our parent 6-tuple (corresonds to frame.f_back)
+
+	Timing data for each function is stored as a 5-tuple in the dictionary
+	self.timings[].  The index is always the name stored in self.cur[4].
+	The following are the definitions of the members:
+
+	[0] = The number of times this function was called, not counting direct
+	      or indirect recursion,
+	[1] = Number of times this function appears on the stack, minus one
+	[2] = Total time spent internal to this function
+	[3] = Cumulative time that this function was present on the stack.  In
+	      non-recursive functions, this is the total execution time from start
+	      to finish of each invocation of a function, including time spent in
+	      all subfunctions.
+	[5] = A dictionary indicating for each function name, the number of times
+	      it was called by us.
+	"""
 
 	def __init__(self, timer=None):
 		self.timings = {}
@@ -449,19 +449,16 @@ class Profile:
 
 
 
-#****************************************************************************
-# OldProfile class documentation
-#****************************************************************************
-#
-# The following derived profiler simulates the old style profile, providing
-# errant results on recursive functions. The reason for the usefulnes of this
-# profiler is that it runs faster (i.e., less overhead).  It still creates
-# all the caller stats, and is quite useful when there is *no* recursion
-# in the user's code.
-#
-# This code also shows how easy it is to create a modified profiler.
-#****************************************************************************
 class OldProfile(Profile):
+	"""A derived profiler that simulates the old style profile, providing
+	errant results on recursive functions. The reason for the usefulness of
+	this profiler is that it runs faster (i.e., less overhead).  It still
+	creates all the caller stats, and is quite useful when there is *no*
+	recursion in the user's code.
+	
+	This code also shows how easy it is to create a modified profiler.
+	"""
+
 	def trace_dispatch_exception(self, frame, t):
 		rt, rtt, rct, rfn, rframe, rcur = self.cur
 		if rcur and not rframe is frame:
@@ -509,16 +506,13 @@ class OldProfile(Profile):
 
 		
 
-#****************************************************************************
-# HotProfile class documentation
-#****************************************************************************
-#
-# This profiler is the fastest derived profile example.  It does not
-# calculate caller-callee relationships, and does not calculate cumulative
-# time under a function.  It only calculates time spent in a function, so
-# it runs very quickly (re: very low overhead)
-#****************************************************************************
 class HotProfile(Profile):
+	"""The fastest derived profile example.  It does not calculate
+	caller-callee relationships, and does not calculate cumulative
+	time under a function.  It only calculates time spent in a
+	function, so it runs very quickly due to its very low overhead.
+	"""
+
 	def trace_dispatch_exception(self, frame, t):
 		rt, rtt, rfn, rframe, rcur = self.cur
 		if rcur and not rframe is frame:

Lib/pstats.py

-#
+"""Class for printing reports on profiled python code."""
+
 # Class for printing reports on profiled python code. rev 1.0  4/1/94
 #
 # Based on prior profile module by Sjoerd Mullender...
@@ -37,41 +38,38 @@ import string
 import marshal
 import re
 
-#**************************************************************************
-# Class Stats documentation
-#**************************************************************************
-# This class is used for creating reports from data generated by the
-# Profile class.  It is a "friend" of that class, and imports data either
-# by direct access to members of Profile class, or by reading in a dictionary
-# that was emitted (via marshal) from the Profile class.
-#
-# The big change from the previous Profiler (in terms of raw functionality)
-# is that an "add()" method has been provided to combine Stats from
-# several distinct profile runs.  Both the constructor and the add()
-# method now take arbitrarilly many file names as arguments.
-#
-# All the print methods now take an argument that indicats how many lines
-# to print.  If the arg is a floating point number between 0 and 1.0, then
-# it is taken as a decimal percentage of the availabel lines to be printed
-# (e.g., .1 means print 10% of all available lines).  If it is an integer,
-# it is taken to mean the number of lines of data that you wish to have
-# printed.
-#
-# The sort_stats() method now processes some additionaly options (i.e., in
-# addition to the old -1, 0, 1, or 2).  It takes an arbitrary number of quoted
-# strings to select the sort order.  For example sort_stats('time', 'name')
-# sorts on the major key of "internal function time", and on the minor
-# key of 'the name of the function'.  Look at the two tables in sort_stats()
-# and get_sort_arg_defs(self) for more examples.
-#
-# All methods now return "self",  so you can string together commands like:
-#    Stats('foo', 'goo').strip_dirs().sort_stats('calls').\
-#                               print_stats(5).print_callers(5)
-# 
-#**************************************************************************
 import fpformat
 
 class Stats:
+	"""This class is used for creating reports from data generated by the
+	Profile class.  It is a "friend" of that class, and imports data either
+	by direct access to members of Profile class, or by reading in a dictionary
+	that was emitted (via marshal) from the Profile class.
+
+	The big change from the previous Profiler (in terms of raw functionality)
+	is that an "add()" method has been provided to combine Stats from
+	several distinct profile runs.  Both the constructor and the add()
+	method now take arbitrarilly many file names as arguments.
+
+	All the print methods now take an argument that indicats how many lines
+	to print.  If the arg is a floating point number between 0 and 1.0, then
+	it is taken as a decimal percentage of the availabel lines to be printed
+	(e.g., .1 means print 10% of all available lines).  If it is an integer,
+	it is taken to mean the number of lines of data that you wish to have
+	printed.
+
+	The sort_stats() method now processes some additionaly options (i.e., in
+	addition to the old -1, 0, 1, or 2).  It takes an arbitrary number of quoted
+	strings to select the sort order.  For example sort_stats('time', 'name')
+	sorts on the major key of "internal function time", and on the minor
+	key of 'the name of the function'.  Look at the two tables in sort_stats()
+	and get_sort_arg_defs(self) for more examples.
+
+	All methods now return "self",  so you can string together commands like:
+	    Stats('foo', 'goo').strip_dirs().sort_stats('calls').\
+	                        print_stats(5).print_callers(5)
+	"""
+	
 	def __init__(self, *args):
 		if not len(args):
 			arg = None
@@ -182,8 +180,8 @@ class Stats:
 		  "time"      : (((2,-1),              ), "internal time"),\
 		  }
 
-	# Expand all abbreviations that are unique
 	def get_sort_arg_defs(self):
+		"""Expand all abbreviations that are unique."""
 		if not self.sort_arg_dict:
 			self.sort_arg_dict = dict = {}
 			std_list = dict.keys()
@@ -289,9 +287,9 @@ class Stats:
 				all_callees[func2][func]  = callers[func2]
 		return
 
-        #******************************************************************
+	#******************************************************************
 	# The following functions support actual printing of reports
-        #******************************************************************
+	#******************************************************************
 
 	# Optional "amount" is either a line count, or a percentage of lines.
 
@@ -447,17 +445,14 @@ class Stats:
 		pass # has no return value, so use at end of line :-)
 
 
-#**************************************************************************
-# class TupleComp Documentation
-#**************************************************************************
-# This class provides a generic function for comparing any two tuples.
-# Each instance records a list of tuple-indicies (from most significant
-# to least significant), and sort direction (ascending or decending) for
-# each tuple-index.  The compare functions can then be used as the function
-# argument to the system sort() function when a list of tuples need to be
-# sorted in the instances order.
-#**************************************************************************
 class TupleComp:
+	"""This class provides a generic function for comparing any two tuples.
+	Each instance records a list of tuple-indicies (from most significant
+	to least significant), and sort direction (ascending or decending) for
+	each tuple-index.  The compare functions can then be used as the function
+	argument to the system sort() function when a list of tuples need to be
+	sorted in the instances order."""
+
 	def __init__(self, comp_select_list):
 		self.comp_select_list = comp_select_list
 
@@ -495,16 +490,16 @@ def func_split(func_name):
 # such as callers and callees. 
 #**************************************************************************
 
-    # Add together all the stats for two profile entries
-def add_func_stats(target, source):				
+def add_func_stats(target, source):
+	"""Add together all the stats for two profile entries."""
 	cc, nc, tt, ct, callers = source
 	t_cc, t_nc, t_tt, t_ct, t_callers = target
 	return (cc+t_cc, nc+t_nc, tt+t_tt, ct+t_ct, \
 		  add_callers(t_callers, callers))
 
 
-    # Combine two caller lists in a single list.
 def add_callers(target, source):
+	"""Combine two caller lists in a single list."""
 	new_callers = {}
 	for func in target.keys():
 		new_callers[func] = target[func]
@@ -515,8 +510,8 @@ def add_callers(target, source):
 			new_callers[func] = source[func]
 	return new_callers
 
-     # Sum the caller statistics to get total number of calls recieved
 def count_calls(callers):
+	"""Sum the caller statistics to get total number of calls received."""
 	nc = 0
 	for func in callers.keys():
 		nc = nc + callers[func]
@@ -529,4 +524,3 @@ def count_calls(callers):
 def f8(x):
 	return string.rjust(fpformat.fix(x, 3), 8)
 
-

Lib/pty.py

-# pty.py -- Pseudo terminal utilities.
+"""Pseudo terminal utilities."""
 
 # Bugs: No signal handling.  Doesn't set slave termios and window size.
 #	Only tested on Linux.
@@ -16,8 +16,9 @@ STDERR_FILENO = 2
 
 CHILD = 0
 
-# Open pty master.  Returns (master_fd, tty_name).  SGI and Linux/BSD version.
 def master_open():
+	"""Open pty master and return (master_fd, tty_name).
+	SGI and Linux/BSD version."""
 	try:
 		import sgi
 	except ImportError:
@@ -38,14 +39,15 @@ def master_open():
 			return (fd, '/dev/tty' + x + y)
 	raise os.error, 'out of pty devices'
 
-# Open the pty slave.  Acquire the controlling terminal.
-# Returns file descriptor.  Linux version.  (Should be universal? --Guido)
 def slave_open(tty_name):
+	"""Open the pty slave and acquire the controlling terminal.
+	Return the file descriptor.  Linux version."""
+	# (Should be universal? --Guido)
 	return os.open(tty_name, FCNTL.O_RDWR)
 
-# Fork and make the child a session leader with a controlling terminal.
-# Returns (pid, master_fd)
 def fork():
+	"""Fork and make the child a session leader with a controlling terminal.
+	Return (pid, master_fd)."""
 	master_fd, tty_name = master_open() 
 	pid = os.fork()
 	if pid == CHILD:
@@ -66,21 +68,21 @@ def fork():
 	# Parent and child process.
 	return pid, master_fd
 
-# Write all the data to a descriptor.
 def writen(fd, data):
+	"""Write all the data to a descriptor."""
 	while data != '':
 		n = os.write(fd, data)
 		data = data[n:]
 
-# Default read function.
 def read(fd):
+	"""Default read function."""
 	return os.read(fd, 1024)
 
-# Parent copy loop.
-# Copies  
-# 	pty master -> standard output	(master_read)
-# 	standard input -> pty master	(stdin_read)
 def copy(master_fd, master_read=read, stdin_read=read):
+	"""Parent copy loop.
+	Copies  
+	  	pty master -> standard output	(master_read)
+	  	standard input -> pty master	(stdin_read)"""
 	while 1:
 		rfds, wfds, xfds = select(
 			[master_fd, STDIN_FILENO], [], [])
@@ -91,8 +93,8 @@ def copy(master_fd, master_read=read, stdin_read=read):
 			data = stdin_read(STDIN_FILENO)
 			writen(master_fd, data)
 
-# Create a spawned process.
 def spawn(argv, master_read=read, stdin_read=read):
+	"""Create a spawned process."""
 	if type(argv) == type(''):
 		argv = (argv,)
 	pid, master_fd = fork()

Lib/py_compile.py

@@ -7,7 +7,7 @@ import imp
 MAGIC = imp.get_magic()
 
 def wr_long(f, x):
-    "Internal; write a 32-bit int to a file in little-endian order."
+    """Internal; write a 32-bit int to a file in little-endian order."""
     f.write(chr( x        & 0xff))
     f.write(chr((x >> 8)  & 0xff))
     f.write(chr((x >> 16) & 0xff))