Actually, the previous batch's comment should have been different;
*this* set of patches is Ka-Ping's final sweep:
The attached patches update the standard library so that all modules
have docstrings beginning with one-line summaries.
A new docstring was added to formatter. The docstring for os.py
was updated to mention nt, os2, ce in addition to posix, dos, mac.
diff --git a/Lib/asynchat.py b/Lib/asynchat.py
index e725a2b..8b2f59f 100644
--- a/Lib/asynchat.py
+++ b/Lib/asynchat.py
@@ -25,28 +25,31 @@
# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
# ======================================================================
+"""A class supporting chat-style (command/response) protocols.
+
+This class adds support for 'chat' style protocols - where one side
+sends a 'command', and the other sends a response (examples would be
+the common internet protocols - smtp, nntp, ftp, etc..).
+
+The handle_read() method looks at the input stream for the current
+'terminator' (usually '\r\n' for single-line responses, '\r\n.\r\n'
+for multi-line output), calling self.found_terminator() on its
+receipt.
+
+for example:
+Say you build an async nntp client using this class. At the start
+of the connection, you'll have self.terminator set to '\r\n', in
+order to process the single-line greeting. Just before issuing a
+'LIST' command you'll set it to '\r\n.\r\n'. The output of the LIST
+command will be accumulated (using your own 'collect_incoming_data'
+method) up to the terminator, and then control will be returned to
+you - by calling your self.found_terminator() method.
+"""
+
import socket
import asyncore
import string
-# This class adds support for 'chat' style protocols - where one side
-# sends a 'command', and the other sends a response (examples would be
-# the common internet protocols - smtp, nntp, ftp, etc..).
-
-# The handle_read() method looks at the input stream for the current
-# 'terminator' (usually '\r\n' for single-line responses, '\r\n.\r\n'
-# for multi-line output), calling self.found_terminator() on its
-# receipt.
-
-# for example:
-# Say you build an async nntp client using this class. At the start
-# of the connection, you'll have self.terminator set to '\r\n', in
-# order to process the single-line greeting. Just before issuing a
-# 'LIST' command you'll set it to '\r\n.\r\n'. The output of the LIST
-# command will be accumulated (using your own 'collect_incoming_data'
-# method) up to the terminator, and then control will be returned to
-# you - by calling your self.found_terminator() method
-
class async_chat (asyncore.dispatcher):
"""This is an abstract class. You must derive from this class, and add
the two methods collect_incoming_data() and found_terminator()"""
diff --git a/Lib/asyncore.py b/Lib/asyncore.py
index 07b9fc3..8e11d76 100644
--- a/Lib/asyncore.py
+++ b/Lib/asyncore.py
@@ -25,6 +25,27 @@
# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
# ======================================================================
+"""Basic infrastructure for asynchronous socket service clients and servers.
+
+There are only two ways to have a program on a single processor do "more
+than one thing at a time". Multi-threaded programming is the simplest and
+most popular way to do it, but there is another very different technique,
+that lets you have nearly all the advantages of multi-threading, without
+actually using multiple threads. it's really only practical if your program
+is largely I/O bound. If your program is CPU bound, then pre-emptive
+scheduled threads are probably what you really need. Network servers are
+rarely CPU-bound, however.
+
+If your operating system supports the select() system call in its I/O
+library (and nearly all do), then you can use it to juggle multiple
+communication channels at once; doing other work while your I/O is taking
+place in the "background." Although this strategy can seem strange and
+complex, especially at first, it is in many ways easier to understand and
+control than multi-threaded programming. The module documented here solves
+many of the difficult problems for you, making the task of building
+sophisticated high-performance network servers and clients a snap.
+"""
+
import select
import socket
import string
diff --git a/Lib/binhex.py b/Lib/binhex.py
index 3fc7234..db6a7ef 100644
--- a/Lib/binhex.py
+++ b/Lib/binhex.py
@@ -1,4 +1,4 @@
-"""binhex - Macintosh binhex compression/decompression
+"""Macintosh binhex compression/decompression.
easy interface:
binhex(inputfilename, outputfilename)
diff --git a/Lib/copy.py b/Lib/copy.py
index 2d9de3c..e4679de 100644
--- a/Lib/copy.py
+++ b/Lib/copy.py
@@ -1,6 +1,4 @@
-"""\
-Generic (shallow and deep) copying operations
-=============================================
+"""Generic (shallow and deep) copying operations.
Interface summary:
diff --git a/Lib/dircache.py b/Lib/dircache.py
index b0a3665..a35e16d 100644
--- a/Lib/dircache.py
+++ b/Lib/dircache.py
@@ -1,6 +1,8 @@
-"""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."""
+"""Read and cache directory listings.
+
+The listdir() routine returns a sorted list of the files in a directory,
+using a cache to avoid reading the directory more often than necessary.
+The annotate() routine appends slashes to directories."""
import os
diff --git a/Lib/dospath.py b/Lib/dospath.py
index 2ad21f0..4e4be56 100644
--- a/Lib/dospath.py
+++ b/Lib/dospath.py
@@ -1,4 +1,4 @@
-"""Module 'dospath' -- common operations on DOS pathnames"""
+"""Common operations on DOS pathnames."""
import os
import stat
diff --git a/Lib/formatter.py b/Lib/formatter.py
index 4b340d5..4d6a129 100644
--- a/Lib/formatter.py
+++ b/Lib/formatter.py
@@ -1,3 +1,23 @@
+"""Generic output formatting.
+
+Formatter objects transform an abstract flow of formatting events into
+specific output events on writer objects. Formatters manage several stack
+structures to allow various properties of a writer object to be changed and
+restored; writers need not be able to handle relative changes nor any sort
+of ``change back'' operation. Specific writer properties which may be
+controlled via formatter objects are horizontal alignment, font, and left
+margin indentations. A mechanism is provided which supports providing
+arbitrary, non-exclusive style settings to a writer as well. Additional
+interfaces facilitate formatting events which are not reversible, such as
+paragraph separation.
+
+Writer objects encapsulate device interfaces. Abstract devices, such as
+file formats, are supported as well as physical devices. The provided
+implementations all work with abstract devices. The interface makes
+available mechanisms for setting the properties which formatter objects
+manage and inserting data into the output.
+"""
+
import string
import sys
from types import StringType
diff --git a/Lib/ftplib.py b/Lib/ftplib.py
index eee8e5a..94ae880 100644
--- a/Lib/ftplib.py
+++ b/Lib/ftplib.py
@@ -1,4 +1,5 @@
-'''An FTP client class, and some helper functions.
+"""An FTP client class and some helper functions.
+
Based on RFC 959: File Transfer Protocol
(FTP), by J. Postel and J. Reynolds
@@ -31,7 +32,7 @@
A nice test that reveals some of the network dialogue would be:
python ftplib.py -d localhost -l -p -l
-'''
+"""
import os
diff --git a/Lib/getopt.py b/Lib/getopt.py
index b5fdaed..692b8b9 100644
--- a/Lib/getopt.py
+++ b/Lib/getopt.py
@@ -1,4 +1,4 @@
-"""Module getopt -- Parser for command line options.
+"""Parser for command line options.
This module helps scripts to parse the command line arguments in
sys.argv. It supports the same conventions as the Unix getopt()
diff --git a/Lib/gzip.py b/Lib/gzip.py
index ee39169..25278be 100644
--- a/Lib/gzip.py
+++ b/Lib/gzip.py
@@ -1,4 +1,5 @@
-"""This module implements a function that reads and writes a gzipped file.
+"""Functions that read and write gzipped files.
+
The user of the file doesn't have to worry about the compression,
but random access is not allowed."""
diff --git a/Lib/locale.py b/Lib/locale.py
index d85cabf..9be729d 100644
--- a/Lib/locale.py
+++ b/Lib/locale.py
@@ -1,4 +1,5 @@
-"Support for number formatting using the current locale settings"
+"""Support for number formatting using the current locale settings."""
+
# Author: Martin von Loewis
from _locale import *
diff --git a/Lib/macurl2path.py b/Lib/macurl2path.py
index 4c43d21..c971eda 100644
--- a/Lib/macurl2path.py
+++ b/Lib/macurl2path.py
@@ -1,5 +1,6 @@
-"""Mac specific module for conversion between pathnames and URLs.
-Do not import directly, use urllib instead."""
+"""Macintosh-specific module for conversion between pathnames and URLs.
+
+Do not import directly; use urllib instead."""
import string
import urllib
diff --git a/Lib/mimify.py b/Lib/mimify.py
index 354cdb7..20b4d6c 100755
--- a/Lib/mimify.py
+++ b/Lib/mimify.py
@@ -1,6 +1,6 @@
#! /usr/bin/env python
-'''Mimification and unmimification of mail messages.
+"""Mimification and unmimification of mail messages.
Decode quoted-printable parts of a mail message or encode using
quoted-printable.
@@ -19,7 +19,7 @@
mimify.py -d [infile [outfile]]
to encode and decode respectively. Infile defaults to standard
input and outfile to standard output.
-'''
+"""
# Configure
MAXLEN = 200 # if lines longer than this, encode as quoted-printable
diff --git a/Lib/os.py b/Lib/os.py
index 129d4b2..118b619 100644
--- a/Lib/os.py
+++ b/Lib/os.py
@@ -1,14 +1,15 @@
-"""os.py -- either mac, dos or posix depending on what system we're on.
+"""OS routines for Mac, DOS, NT, 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'
+ - all functions from posix, nt, dos, os2, mac, or ce, e.g. unlink, stat, etc.
+ - os.path is one of the modules posixpath, ntpath, macpath, or dospath
+ - os.name is 'posix', 'nt', 'dos', 'os2', 'mac', or 'ce'
- 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.altsep is the alternate pathname separator (None or '/')
- os.pathsep is the component separator used in $PATH etc
+ - os.linesep is the line separator in text files ('\r' or '\n' or '\r\n')
- os.defpath is the default search path for executables
Programs that import and use 'os' stand a better chance of being
diff --git a/Lib/pdb.py b/Lib/pdb.py
index 3835f03..2e45098 100755
--- a/Lib/pdb.py
+++ b/Lib/pdb.py
@@ -1,6 +1,6 @@
#! /usr/bin/env python
-"""pdb.py -- finally, a Python debugger!"""
+"""A Python debugger."""
# (See pdb.doc for documentation.)
diff --git a/Lib/pyclbr.py b/Lib/pyclbr.py
index de3fedc..74b7ff7 100644
--- a/Lib/pyclbr.py
+++ b/Lib/pyclbr.py
@@ -1,4 +1,4 @@
-'''Parse a Python file and retrieve classes and methods.
+"""Parse a Python file and retrieve classes and methods.
Parse enough of a Python file to recognize class and method
definitions and to find out the superclasses of a class.
@@ -51,7 +51,7 @@
It can't locate the parent. It probably needs to have the same
hairy logic that the import locator already does. (This logic
exists coded in Python in the freeze package.)
-''' # ' <-- bow to font lock
+"""
import os
import sys
diff --git a/Lib/sched.py b/Lib/sched.py
index 147977c..f51d835 100644
--- a/Lib/sched.py
+++ b/Lib/sched.py
@@ -1,4 +1,4 @@
-"""Module sched -- a generally useful event scheduler class
+"""A generally useful event scheduler class.
Each instance of this class manages its own queue.
No multi-threading is implied; you are supposed to hack that
diff --git a/Lib/smtplib.py b/Lib/smtplib.py
index 1c42233..df8907d 100755
--- a/Lib/smtplib.py
+++ b/Lib/smtplib.py
@@ -1,6 +1,6 @@
#! /usr/bin/env python
-'''SMTP/ESMTP client class.
+"""SMTP/ESMTP client class.
Author: The Dragon De Monsyne <dragondm@integral.org>
ESMTP support, test code and doc fixes added by
@@ -37,7 +37,7 @@
>>> s.getreply()
(250, "Somebody OverHere <somebody@here.my.org>")
>>> s.quit()
-'''
+"""
import socket
import string
diff --git a/Lib/statcache.py b/Lib/statcache.py
index 0d88a9a..b5147c2 100644
--- a/Lib/statcache.py
+++ b/Lib/statcache.py
@@ -1,4 +1,5 @@
-"""Maintain a cache of file stats.
+"""Maintain a cache of stat() information on files.
+
There are functions to reset the cache or to selectively remove items.
"""
diff --git a/Lib/xmllib.py b/Lib/xmllib.py
index dcfe872..16a56b0 100644
--- a/Lib/xmllib.py
+++ b/Lib/xmllib.py
@@ -1,4 +1,5 @@
-# A parser for XML, using the derived class as static DTD.
+"""A parser for XML, using the derived class as static DTD."""
+
# Author: Sjoerd Mullender.
import re