From 4b8c6eaf8b287a27e0054cf6c751448b2077e83b Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Fri, 4 Feb 2000 15:39:30 +0000 Subject: [PATCH] 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. --- Lib/asynchat.py | 39 +++++++++++++++++++++------------------ Lib/asyncore.py | 21 +++++++++++++++++++++ Lib/binhex.py | 2 +- Lib/copy.py | 4 +--- Lib/dircache.py | 8 +++++--- Lib/dospath.py | 2 +- Lib/formatter.py | 20 ++++++++++++++++++++ Lib/ftplib.py | 5 +++-- Lib/getopt.py | 2 +- Lib/gzip.py | 3 ++- Lib/locale.py | 3 ++- Lib/macurl2path.py | 5 +++-- Lib/mimify.py | 4 ++-- Lib/os.py | 11 ++++++----- Lib/pdb.py | 2 +- Lib/pyclbr.py | 4 ++-- Lib/sched.py | 2 +- Lib/smtplib.py | 4 ++-- Lib/statcache.py | 3 ++- Lib/xmllib.py | 3 ++- 20 files changed, 99 insertions(+), 48 deletions(-) diff --git a/Lib/asynchat.py b/Lib/asynchat.py index e725a2b12ad856..8b2f59fa326159 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 07b9fc3aa83c73..8e11d764a42afa 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 3fc72348b9cb3f..db6a7ef9f54598 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 2d9de3cad35ebf..e4679deca2abf4 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 b0a366539c7dd1..a35e16d1bc6ad5 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 2ad21f06505de5..4e4be5651889b6 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 4b340d52ba3c61..4d6a1292effbc4 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 eee8e5a82650b4..94ae880142c951 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 b5fdaedc43588d..692b8b96483c25 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 ee39169d07e455..25278bef3b7c1c 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 d85cabfca58982..9be729d7d6c91b 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 4c43d2110f54cd..c971edaa22dad1 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 354cdb7477ee09..20b4d6c0873718 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 129d4b29980b01..118b6198bfa201 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 3835f038c84841..2e450989b722d8 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 de3fedce114d90..74b7ff73c2ec17 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 @@ class MyClass(subpackage.SuperClass): 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 147977cfe9bc4c..f51d835d772dd6 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 1c42233f262768..df8907da0f48e7 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 ESMTP support, test code and doc fixes added by @@ -37,7 +37,7 @@ >>> s.getreply() (250, "Somebody OverHere ") >>> s.quit() -''' +""" import socket import string diff --git a/Lib/statcache.py b/Lib/statcache.py index 0d88a9a584830f..b5147c233dc545 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 dcfe87268735ea..16a56b04fbaf6c 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