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 e725a2b12a..8b2f59fa32 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 07b9fc3aa8..8e11d764a4 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 3fc72348b9..db6a7ef9f5 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 2d9de3cad3..e4679deca2 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 b0a366539c..a35e16d1bc 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 2ad21f0650..4e4be56518 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 4b340d52ba..4d6a1292ef 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 eee8e5a826..94ae880142 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 @@ drwxr-xr-x 3 root wheel 1024 Jan 3 1994 usr 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 b5fdaedc43..692b8b9648 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 ee39169d07..25278bef3b 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 d85cabfca5..9be729d7d6 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 4c43d2110f..c971edaa22 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 354cdb7477..20b4d6c087 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 @@ Interactive usage: 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 129d4b2998..118b6198bf 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 3835f038c8..2e450989b7 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 de3fedce11..74b7ff73c2 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 @@ PACKAGE RELATED BUGS 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 147977cfe9..f51d835d77 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 1c42233f26..df8907da0f 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 @@ Example: >>> s.getreply() (250, "Somebody OverHere ") >>> s.quit() -''' +""" import socket import string diff --git a/Lib/statcache.py b/Lib/statcache.py index 0d88a9a584..b5147c233d 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 dcfe872687..16a56b04fb 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 -- 2.40.0