Mass patch by Ka-Ping Yee:

    1. Comments at the beginning of the module, before
       functions, and before classes have been turned
       into docstrings.

    2. Tabs are normalized to four spaces.

Also, removed the "remove" function from dircmp.py, which reimplements
list.remove() (it must have been very old).

Lib/Queue.py

-# A multi-producer, multi-consumer queue.
+"""A multi-producer, multi-consumer queue."""
 
 # define this exception to be compatible with Python 1.5's class
 # exceptions, but also when -X option is used.

Lib/StringIO.py

-# class StringIO implements  file-like objects that read/write a
-# string buffer (a.k.a. "memory files").
-#
-# This implements (nearly) all stdio methods.
-#
-# f = StringIO()      # ready for writing
-# f = StringIO(buf)   # ready for reading
-# f.close()           # explicitly release resources held
-# flag = f.isatty()   # always false
-# pos = f.tell()      # get current position
-# f.seek(pos)         # set current position
-# f.seek(pos, mode)   # mode 0: absolute; 1: relative; 2: relative to EOF
-# buf = f.read()      # read until EOF
-# buf = f.read(n)     # read up to n bytes
-# buf = f.readline()  # read until end of line ('\n') or EOF
-# list = f.readlines()# list of f.readline() results until EOF
-# f.write(buf)        # write at current position
-# f.writelines(list)  # for line in list: f.write(line)
-# f.getvalue()        # return whole file's contents as a string
-#
-# Notes:
-# - Using a real file is often faster (but less convenient).
-# - fileno() is left unimplemented so that code which uses it triggers
-#   an exception early.
-# - Seeking far beyond EOF and then writing will insert real null
-#   bytes that occupy space in the buffer.
-# - There's a simple test set (see end of this file).
+"""File-like objects that read from or write to a string buffer.
+
+This implements (nearly) all stdio methods.
+
+f = StringIO()      # ready for writing
+f = StringIO(buf)   # ready for reading
+f.close()           # explicitly release resources held
+flag = f.isatty()   # always false
+pos = f.tell()      # get current position
+f.seek(pos)         # set current position
+f.seek(pos, mode)   # mode 0: absolute; 1: relative; 2: relative to EOF
+buf = f.read()      # read until EOF
+buf = f.read(n)     # read up to n bytes
+buf = f.readline()  # read until end of line ('\n') or EOF
+list = f.readlines()# list of f.readline() results until EOF
+f.write(buf)        # write at current position
+f.writelines(list)  # for line in list: f.write(line)
+f.getvalue()        # return whole file's contents as a string
+
+Notes:
+- Using a real file is often faster (but less convenient).
+- fileno() is left unimplemented so that code which uses it triggers
+  an exception early.
+- Seeking far beyond EOF and then writing will insert real null
+  bytes that occupy space in the buffer.
+- There's a simple test set (see end of this file).
+"""
 
 import string
 

Lib/UserDict.py

-# A more or less complete user-defined wrapper around dictionary objects
+"""A more or less complete user-defined wrapper around dictionary objects."""
 
 class UserDict:
     def __init__(self, dict=None):

Lib/UserList.py

-# A more or less complete user-defined wrapper around list objects
+"""A more or less complete user-defined wrapper around list objects."""
 
 class UserList:
     def __init__(self, list=None):

Lib/audiodev.py

+"""Classes for manipulating audio devices (currently only for Sun and SGI)"""
+
 error = 'audiodev.error'
 
 class Play_Audio_sgi:

Lib/base64.py

 #! /usr/bin/env python
 
-# Conversions to/from base64 transport encoding as per RFC-1521.
-#
+"""Conversions to/from base64 transport encoding as per RFC-1521."""
+
 # Modified 04-Oct-95 by Jack to use binascii module
 
 import binascii
@@ -9,8 +9,8 @@ import binascii
 MAXLINESIZE = 76 # Excluding the CRLF
 MAXBINSIZE = (MAXLINESIZE/4)*3
 
-# Encode a file.
 def encode(input, output):
+    """Encode a file."""
     while 1:
         s = input.read(MAXBINSIZE)
         if not s: break
@@ -21,8 +21,8 @@ def encode(input, output):
         line = binascii.b2a_base64(s)
         output.write(line)
 
-# Decode a file.
 def decode(input, output):
+    """Decode a file."""
     while 1:
         line = input.readline()
         if not line: break
@@ -30,6 +30,7 @@ def decode(input, output):
         output.write(s)
 
 def encodestring(s):
+    """Encode a string."""
     import StringIO
     f = StringIO.StringIO(s)
     g = StringIO.StringIO()
@@ -37,14 +38,15 @@ def encodestring(s):
     return g.getvalue()
 
 def decodestring(s):
+    """Decode a string."""
     import StringIO
     f = StringIO.StringIO(s)
     g = StringIO.StringIO()
     decode(f, g)
     return g.getvalue()
 
-# Small test program
 def test():
+    """Small test program"""
     import sys, getopt
     try:
         opts, args = getopt.getopt(sys.argv[1:], 'deut')

Lib/bdb.py

-# Debugger basics
+"""Debugger basics"""
 
 import sys
 import os
@@ -119,46 +119,46 @@ class Bdb:
     # to gain control.
     
     def user_call(self, frame, argument_list):
-		# This method is called when there is the remote possibility
-		# that we ever need to stop in this function
+        """This method is called when there is the remote possibility
+        that we ever need to stop in this function."""
         pass
     
     def user_line(self, frame):
-		# This method is called when we stop or break at this line
+        """This method is called when we stop or break at this line."""
         pass
     
     def user_return(self, frame, return_value):
-		# This method is called when a return trap is set here
+        """This method is called when a return trap is set here."""
         pass
     
     def user_exception(self, frame, (exc_type, exc_value, exc_traceback)):
-		# This method is called if an exception occurs,
-		# but only if we are to stop at or just below this level
+        """This method is called if an exception occurs,
+        but only if we are to stop at or just below this level."""
         pass
     
     # Derived classes and clients can call the following methods
     # to affect the stepping state.
     
     def set_step(self):
-		# Stop after one line of code
+        """Stop after one line of code."""
         self.stopframe = None
         self.returnframe = None
         self.quitting = 0
     
     def set_next(self, frame):
-		# Stop on the next line in or below the given frame
+        """Stop on the next line in or below the given frame."""
         self.stopframe = frame
         self.returnframe = None
         self.quitting = 0
     
     def set_return(self, frame):
-		# Stop when returning from the given frame
+        """Stop when returning from the given frame."""
         self.stopframe = frame.f_back
         self.returnframe = frame
         self.quitting = 0
     
     def set_trace(self):
-		# Start debugging from here
+        """Start debugging from here."""
         try:
             1 + ''
         except:

Lib/binhex.py

 """binhex - Macintosh binhex compression/decompression
+
 easy interface:
 binhex(inputfilename, outputfilename)
 hexbin(inputfilename, outputfilename)

Lib/bisect.py

-# Bisection algorithms
+"""Bisection algorithms."""
 
 
-# Insert item x in list a, and keep it sorted assuming a is sorted
-
 def insort(a, x, lo=0, hi=None):
+    """Insert item x in list a, and keep it sorted assuming a is sorted."""
     if hi is None:
         hi = len(a)
     while lo < hi:
@@ -13,9 +12,8 @@ def insort(a, x, lo=0, hi=None):
     a.insert(lo, x)
 
 
-# Find the index where to insert item x in list a, assuming a is sorted
-
 def bisect(a, x, lo=0, hi=None):
+    """Find the index where to insert item x in list a, assuming a is sorted."""
     if hi is None:
         hi = len(a)
     while lo < hi:

Lib/calendar.py

-###############################
-# Calendar printing functions #
-###############################
+"""Calendar printing functions"""
 
 # Revision 2: uses funtions from built-in time module
 
@@ -22,42 +20,42 @@ February = 2
 mdays = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
 
 # Full and abbreviated names of weekdays
-day_name = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', \
+day_name = ['Monday', 'Tuesday', 'Wednesday', 'Thursday',
             'Friday', 'Saturday', 'Sunday']
 day_abbr = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
 
 # Full and abbreviated names of months (1-based arrays!!!)
-month_name =          ['', 'January',   'February', 'March',    'April', \
-		           'May',       'June',     'July',     'August', \
+month_name = ['', 'January', 'February', 'March', 'April',
+              'May', 'June', 'July', 'August',
               'September', 'October',  'November', 'December']
-month_abbr =       ['   ', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', \
+month_abbr = ['   ', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
               'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
 
-# Return 1 for leap years, 0 for non-leap years
 def isleap(year):
+    """Return 1 for leap years, 0 for non-leap years."""
     return year % 4 == 0 and (year % 100 <> 0 or year % 400 == 0)
 
-# Return number of leap years in range [y1, y2)
-# Assume y1 <= y2 and no funny (non-leap century) years
 def leapdays(y1, y2):
+    """Return number of leap years in range [y1, y2).
+    Assume y1 <= y2 and no funny (non-leap century) years."""
     return (y2+3)/4 - (y1+3)/4
 
-# Return weekday (0-6 ~ Mon-Sun) for year (1970-...), month (1-12), day (1-31)
 def weekday(year, month, day):
+    """Return weekday (0-6 ~ Mon-Sun) for year (1970-...), month (1-12), day (1-31)."""
     secs = mktime((year, month, day, 0, 0, 0, 0, 0, 0))
     tuple = localtime(secs)
     return tuple[6]
 
-# Return weekday (0-6 ~ Mon-Sun) and number of days (28-31) for year, month
 def monthrange(year, month):
+    """Return weekday (0-6 ~ Mon-Sun) and number of days (28-31) for year, month."""
     if not 1 <= month <= 12: raise ValueError, 'bad month number'
     day1 = weekday(year, month, 1)
     ndays = mdays[month] + (month == February and isleap(year))
     return day1, ndays
 
-# Return a matrix representing a month's calendar
-# Each row represents a week; days outside this month are zero
 def _monthcalendar(year, month):
+    """Return a matrix representing a month's calendar.
+    Each row represents a week; days outside this month are zero."""
     day1, ndays = monthrange(year, month)
     rows = []
     r7 = range(7)
@@ -70,9 +68,9 @@ def _monthcalendar(year, month):
         rows.append(row)
     return rows
 
-# Caching interface to _monthcalendar
 _mc_cache = {}
 def monthcalendar(year, month):
+    """Caching interface to _monthcalendar."""
     key = (year, month)
     if _mc_cache.has_key(key):
         return _mc_cache[key]
@@ -80,23 +78,23 @@ def monthcalendar(year, month):
         _mc_cache[key] = ret = _monthcalendar(year, month)
         return ret
 
-# Center a string in a field
 def _center(str, width):
+    """Center a string in a field."""
     n = width - len(str)
     if n <= 0: return str
     return ' '*((n+1)/2) + str + ' '*((n)/2)
 
 # XXX The following code knows that print separates items with space!
 
-# Print a single week (no newline)
 def prweek(week, width):
+    """Print a single week (no newline)."""
     for day in week:
         if day == 0: s = ''
         else: s = `day`
         print _center(s, width),
 
-# Return a header for a week
 def weekheader(width):
+    """Return a header for a week."""
     str = ''
     if width >= 9: names = day_name
     else: names = day_abbr
@@ -105,8 +103,8 @@ def weekheader(width):
         str = str + _center(names[i%7][:width], width)
     return str
 
-# Print a month's calendar
 def prmonth(year, month, w = 0, l = 0):
+    """Print a month's calendar."""
     w = max(2, w)
     l = max(1, l)
     print _center(month_name[month] + ' ' + `year`, 7*(w+1) - 1),
@@ -121,16 +119,16 @@ def prmonth(year, month, w = 0, l = 0):
 _colwidth = 7*3 - 1         # Amount printed by prweek()
 _spacing = ' '*4            # Spaces between columns
 
-# 3-column formatting for year calendars
 def format3c(a, b, c):
+    """3-column formatting for year calendars"""
     print _center(a, _colwidth),
     print _spacing,
     print _center(b, _colwidth),
     print _spacing,
     print _center(c, _colwidth)
 
-# Print a year's calendar
 def prcal(year):
+    """Print a year's calendar."""
     header = weekheader(2)
     format3c('', `year`, '')
     for q in range(January, January+12, 3):
@@ -152,9 +150,9 @@ def prcal(year):
                 print _spacing,
             print
 
-# Unrelated but handy function to calculate Unix timestamp from GMT
 EPOCH = 1970
 def timegm(tuple):
+    """Unrelated but handy function to calculate Unix timestamp from GMT."""
     year, month, day, hour, minute, second = tuple[:6]
     assert year >= EPOCH
     assert 1 <= month <= 12

Lib/cmd.py

-# A generic class to build line-oriented command interpreters
-#
-# Interpreters constructed with this class obey the following conventions:
-#
-# 1. End of file on input is processed as the command 'EOF'.
-# 2. A command is parsed out of each line by collecting the prefix composed
-#    of characters in the identchars member.
-# 3. A command `foo' is dispatched to a method 'do_foo()'; the do_ method
-#    is passed a single argument consisting of the remainder of the line.
-# 4. Typing an empty line repeats the last command.  (Actually, it calls the
-#    method `emptyline', which may be overridden in a subclass.)
-# 5. There is a predefined `help' method.  Given an argument `topic', it
-#    calls the command `help_topic'.  With no arguments, it lists all topics
-#    with defined help_ functions, broken into up to three topics; documented
-#    commands, miscellaneous help topics, and undocumented commands.
-# 6. The command '?' is a synonym for `help'.  The command '!' is a synonym
-#    for `shell', if a do_shell method exists.
-#
-# The `default' method may be overridden to intercept commands for which there
-# is no do_ method.
-#
-# The data member `self.ruler' sets the character used to draw separator lines
-# in the help messages.  If empty, no ruler line is drawn.  It defaults to "=".
-#
-# If the value of `self.intro' is nonempty when the cmdloop method is called,
-# it is printed out on interpreter startup.  This value may be overridden
-# via an optional argument to the cmdloop() method.
-#
-# The data members `self.doc_header', `self.misc_header', and
-# `self.undoc_header' set the headers used for the help function's
-# listings of documented functions, miscellaneous topics, and undocumented
-# functions respectively.
-#
-# These interpreters use raw_input; thus, if the readline module is loaded,
-# they automatically support Emacs-like command history and editing features.
-#
+"""A generic class to build line-oriented command interpreters.
+
+Interpreters constructed with this class obey the following conventions:
+
+1. End of file on input is processed as the command 'EOF'.
+2. A command is parsed out of each line by collecting the prefix composed
+   of characters in the identchars member.
+3. A command `foo' is dispatched to a method 'do_foo()'; the do_ method
+   is passed a single argument consisting of the remainder of the line.
+4. Typing an empty line repeats the last command.  (Actually, it calls the
+   method `emptyline', which may be overridden in a subclass.)
+5. There is a predefined `help' method.  Given an argument `topic', it
+   calls the command `help_topic'.  With no arguments, it lists all topics
+   with defined help_ functions, broken into up to three topics; documented
+   commands, miscellaneous help topics, and undocumented commands.
+6. The command '?' is a synonym for `help'.  The command '!' is a synonym
+   for `shell', if a do_shell method exists.
+
+The `default' method may be overridden to intercept commands for which there
+is no do_ method.
+
+The data member `self.ruler' sets the character used to draw separator lines
+in the help messages.  If empty, no ruler line is drawn.  It defaults to "=".
+
+If the value of `self.intro' is nonempty when the cmdloop method is called,
+it is printed out on interpreter startup.  This value may be overridden
+via an optional argument to the cmdloop() method.
+
+The data members `self.doc_header', `self.misc_header', and
+`self.undoc_header' set the headers used for the help function's
+listings of documented functions, miscellaneous topics, and undocumented
+functions respectively.
+
+These interpreters use raw_input; thus, if the readline module is loaded,
+they automatically support Emacs-like command history and editing features.
+"""
 
 import string
 

Lib/cmp.py

-# Module 'cmp'
+"""Efficiently compare files, boolean outcome only (equal / not equal).
 
-# Efficiently compare files, boolean outcome only (equal / not equal).
-
-# Tricks (used in this order):
-#	- Files with identical type, size & mtime are assumed to be clones
-#	- Files with different type or size cannot be identical
-#	- We keep a cache of outcomes of earlier comparisons
-#	- We don't fork a process to run 'cmp' but read the files ourselves
+Tricks (used in this order):
+    - Files with identical type, size & mtime are assumed to be clones
+    - Files with different type or size cannot be identical
+    - We keep a cache of outcomes of earlier comparisons
+    - We don't fork a process to run 'cmp' but read the files ourselves
+"""
 
 import os
 
 cache = {}
 
-def cmp(f1, f2, shallow=1): # Compare two files, use the cache if possible.
-	# Return 1 for identical files, 0 for different.
-	# Raise exceptions if either file could not be statted, read, etc.
+def cmp(f1, f2, shallow=1):
+    """Compare two files, use the cache if possible.
+    Return 1 for identical files, 0 for different.
+    Raise exceptions if either file could not be statted, read, etc."""
     s1, s2 = sig(os.stat(f1)), sig(os.stat(f2))
     if s1[0] <> 8 or s2[0] <> 8:
         # Either is a not a plain file -- always report as different
@@ -42,15 +42,17 @@ def cmp(f1, f2, shallow=1): # Compare two files, use the cache if possible.
     cache[key] = s1, s2, outcome
     return outcome
 
-def sig(st): # Return signature (i.e., type, size, mtime) from raw stat data
-	# 0-5: st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid
-	# 6-9: st_size, st_atime, st_mtime, st_ctime
+def sig(st):
+    """Return signature (i.e., type, size, mtime) from raw stat data
+    0-5: st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid
+    6-9: st_size, st_atime, st_mtime, st_ctime"""
     type = st[0] / 4096
     size = st[6]
     mtime = st[8]
     return type, size, mtime
 
-def do_cmp(f1, f2): # Compare two files, really
+def do_cmp(f1, f2):
+    """Compare two files, really."""
     bufsize = 8*1024 # Could be tuned
     fp1 = open(f1, 'rb')
     fp2 = open(f2, 'rb')

Lib/cmpcache.py

-# Module 'cmpcache'
-#
-# Efficiently compare files, boolean outcome only (equal / not equal).
-#
-# Tricks (used in this order):
-#	- Use the statcache module to avoid statting files more than once
-#	- Files with identical type, size & mtime are assumed to be clones
-#	- Files with different type or size cannot be identical
-#	- We keep a cache of outcomes of earlier comparisons
-#	- We don't fork a process to run 'cmp' but read the files ourselves
+"""Efficiently compare files, boolean outcome only (equal / not equal).
+
+Tricks (used in this order):
+    - Use the statcache module to avoid statting files more than once
+    - Files with identical type, size & mtime are assumed to be clones
+    - Files with different type or size cannot be identical
+    - We keep a cache of outcomes of earlier comparisons
+    - We don't fork a process to run 'cmp' but read the files ourselves
+"""
 
 import os
 from stat import *
@@ -19,12 +18,11 @@ import statcache
 cache = {}
 
 
-# Compare two files, use the cache if possible.
-# May raise os.error if a stat or open of either fails.
-#
 def cmp(f1, f2, shallow=1):
-	# Return 1 for identical files, 0 for different.
-	# Raise exceptions if either file could not be statted, read, etc.
+    """Compare two files, use the cache if possible.
+    May raise os.error if a stat or open of either fails.
+    Return 1 for identical files, 0 for different.
+    Raise exceptions if either file could not be statted, read, etc."""
     s1, s2 = sig(statcache.stat(f1)), sig(statcache.stat(f2))
     if not S_ISREG(s1[0]) or not S_ISREG(s2[0]):
         # Either is a not a plain file -- always report as different
@@ -49,14 +47,12 @@ def cmp(f1, f2, shallow=1):
     cache[key] = s1, s2, outcome
     return outcome
 
-# Return signature (i.e., type, size, mtime) from raw stat data.
-#
 def sig(st):
+    """Return signature (i.e., type, size, mtime) from raw stat data."""
     return S_IFMT(st[ST_MODE]), st[ST_SIZE], st[ST_MTIME]
 
-# Compare two files, really.
-#
 def do_cmp(f1, f2):
+    """Compare two files, really."""
     #print '    cmp', f1, f2 # XXX remove when debugged
     bufsize = 8*1024 # Could be tuned
     fp1 = open(f1, 'rb')

Lib/copy_reg.py

-# Helper to provide extensibility for pickle/cPickle.
+"""Helper to provide extensibility for pickle/cPickle."""
 
 dispatch_table = {}
 safe_constructors = {}

Lib/dircache.py

-# Module 'dircache'
-#
-# Return a sorted list of the files in a directory, using a cache
-# to avoid reading the directory more often than necessary.
-# Also contains a subroutine to append slashes to directories.
+"""Return a sorted list of the files in a directory, using a cache
+to avoid reading the directory more often than necessary.
+Also contains a subroutine to append slashes to directories."""
 
 import os
 
 cache = {}
 
-def listdir(path): # List directory contents, using cache
+def listdir(path):
+    """List directory contents, using cache."""
     try:
         cached_mtime, list = cache[path]
         del cache[path]
@@ -29,7 +28,8 @@ def listdir(path): # List directory contents, using cache
 
 opendir = listdir # XXX backward compatibility
 
-def annotate(head, list): # Add '/' suffixes to directories
+def annotate(head, list):
+    """Add '/' suffixes to directories."""
     for i in range(len(list)):
         if os.path.isdir(os.path.join(head, list[i])):
             list[i] = list[i] + '/'

Lib/dircmp.py

-# Module 'dirmp'
-#
-# Defines a class to build directory diff tools on.
+"""A class to build directory diff tools on."""
 
 import os
 
@@ -9,20 +7,21 @@ import cmpcache
 import statcache
 from stat import *
 
-# Directory comparison class.
-#
 class dircmp:
-	#
-	def new(self, a, b): # Initialize
+    """Directory comparison class."""
+
+    def new(self, a, b):
+        """Initialize."""
         self.a = a
         self.b = b
         # Properties that caller may change before calling self.run():
         self.hide = [os.curdir, os.pardir] # Names never to be shown
         self.ignore = ['RCS', 'tags'] # Names ignored in comparison
-		#
+
         return self
-	#
-	def run(self): # Compare everything except common subdirectories
+
+    def run(self):
+        """Compare everything except common subdirectories."""
         self.a_list = filter(dircache.listdir(self.a), self.hide)
         self.b_list = filter(dircache.listdir(self.b), self.hide)
         self.a_list.sort()
@@ -30,8 +29,9 @@ class dircmp:
         self.phase1()
         self.phase2()
         self.phase3()
-	#
-	def phase1(self): # Compute common names
+
+    def phase1(self):
+        """Compute common names."""
         self.a_only = []
         self.common = []
         for x in self.a_list:
@@ -39,21 +39,22 @@ class dircmp:
                 self.common.append(x)
             else:
                 self.a_only.append(x)
-		#
+
         self.b_only = []
         for x in self.b_list:
             if x not in self.common:
                 self.b_only.append(x)
-	#
-	def phase2(self): # Distinguish files, directories, funnies
+
+    def phase2(self):
+        """Distinguish files, directories, funnies."""
         self.common_dirs = []
         self.common_files = []
         self.common_funny = []
-		#
+
         for x in self.common:
             a_path = os.path.join(self.a, x)
             b_path = os.path.join(self.b, x)
-			#
+
             ok = 1
             try:
                 a_stat = statcache.stat(a_path)
@@ -65,7 +66,7 @@ class dircmp:
             except os.error, why:
                 # print 'Can\'t stat', b_path, ':', why[1]
                 ok = 0
-			#
+
             if ok:
                 a_type = S_IFMT(a_stat[ST_MODE])
                 b_type = S_IFMT(b_stat[ST_MODE])
@@ -79,15 +80,17 @@ class dircmp:
                     self.common_funny.append(x)
             else:
                 self.common_funny.append(x)
-	#
-	def phase3(self): # Find out differences between common files
+
+    def phase3(self):
+        """Find out differences between common files."""
         xx = cmpfiles(self.a, self.b, self.common_files)
         self.same_files, self.diff_files, self.funny_files = xx
-	#
-	def phase4(self): # Find out differences between common subdirectories
-		# A new dircmp object is created for each common subdirectory,
-		# these are stored in a dictionary indexed by filename.
-		# The hide and ignore properties are inherited from the parent
+
+    def phase4(self):
+        """Find out differences between common subdirectories.
+        A new dircmp object is created for each common subdirectory,
+        these are stored in a dictionary indexed by filename.
+        The hide and ignore properties are inherited from the parent."""
         self.subdirs = {}
         for x in self.common_dirs:
             a_x = os.path.join(self.a, x)
@@ -96,13 +99,15 @@ class dircmp:
             newdd.hide = self.hide
             newdd.ignore = self.ignore
             newdd.run()
-	#
-	def phase4_closure(self): # Recursively call phase4() on subdirectories
+
+    def phase4_closure(self):
+        """Recursively call phase4() on subdirectories."""
         self.phase4()
         for x in self.subdirs.keys():
             self.subdirs[x].phase4_closure()
-	#
-	def report(self): # Print a report on the differences between a and b
+
+    def report(self):
+        """Print a report on the differences between a and b."""
         # Assume that phases 1 to 3 have been executed
         # Output format is purposely lousy
         print 'diff', self.a, self.b
@@ -120,9 +125,10 @@ class dircmp:
             print 'Common subdirectories :', self.common_dirs
         if self.common_funny:
             print 'Common funny cases :', self.common_funny
-	#
-	def report_closure(self): # Print reports on self and on subdirs
-		# If phase 4 hasn't been done, no subdir reports are printed
+
+    def report_closure(self):
+        """Print reports on self and on subdirs.
+        If phase 4 hasn't been done, no subdir reports are printed."""
         self.report()
         try:
             x = self.subdirs
@@ -131,8 +137,9 @@ class dircmp:
         for x in self.subdirs.keys():
             print
             self.subdirs[x].report_closure()
-	#
-	def report_phase4_closure(self): # Report and do phase 4 recursively
+
+    def report_phase4_closure(self):
+        """Report and do phase 4 recursively."""
         self.report()
         self.phase4()
         for x in self.subdirs.keys():
@@ -140,26 +147,26 @@ class dircmp:
             self.subdirs[x].report_phase4_closure()
 
 
-# Compare common files in two directories.
-# Return:
-#	- files that compare equal
-#	- files that compare different
-#	- funny cases (can't stat etc.)
-#
 def cmpfiles(a, b, common):
+    """Compare common files in two directories.
+    Return:
+        - files that compare equal
+        - files that compare different
+        - funny cases (can't stat etc.)"""
+
     res = ([], [], [])
     for x in common:
         res[cmp(os.path.join(a, x), os.path.join(b, x))].append(x)
     return res
 
 
-# Compare two files.
-# Return:
-#	0 for equal
-#	1 for different
-#	2 for funny cases (can't stat, etc.)
-#
 def cmp(a, b):
+    """Compare two files.
+    Return:
+        0 for equal
+        1 for different
+        2 for funny cases (can't stat, etc.)"""
+
     try:
         if cmpcache.cmp(a, b): return 0
         return 1
@@ -167,28 +174,18 @@ def cmp(a, b):
         return 2
 
 
-# Remove a list item.
-# NB: This modifies the list argument.
-#
-def remove(list, item):
-	for i in range(len(list)):
-		if list[i] == item:
-			del list[i]
-			break
-
-
-# Return a copy with items that occur in skip removed.
-#
 def filter(list, skip):
+    """Return a copy with items that occur in skip removed."""
+
     result = []
     for item in list:
         if item not in skip: result.append(item)
     return result
 
 
-# Demonstration and testing.
-#
 def demo():
+    """Demonstration and testing."""
+
     import sys
     import getopt
     options, args = getopt.getopt(sys.argv[1:], 'r')
@@ -200,4 +197,5 @@ def demo():
     else:
         dd.report()
 
-# demo()
+if __name__ == "__main__":
+    demo()

Lib/fpformat.py

-# General floating point formatting functions.
+"""General floating point formatting functions.
 
-# Functions:
-# fix(x, digits_behind)
-# sci(x, digits_behind)
+Functions:
+fix(x, digits_behind)
+sci(x, digits_behind)
 
-# Each takes a number or a string and a number of digits as arguments.
-
-# Parameters:
-# x:             number to be formatted; or a string resembling a number
-# digits_behind: number of digits behind the decimal point
+Each takes a number or a string and a number of digits as arguments.
 
+Parameters:
+x:             number to be formatted; or a string resembling a number
+digits_behind: number of digits behind the decimal point
+"""
 
 import re