]> granicus.if.org Git - python/commitdiff
Actually, the previous batch's comment should have been different;
authorGuido van Rossum <guido@python.org>
Fri, 4 Feb 2000 15:39:30 +0000 (15:39 +0000)
committerGuido van Rossum <guido@python.org>
Fri, 4 Feb 2000 15:39:30 +0000 (15:39 +0000)
*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.

20 files changed:
Lib/asynchat.py
Lib/asyncore.py
Lib/binhex.py
Lib/copy.py
Lib/dircache.py
Lib/dospath.py
Lib/formatter.py
Lib/ftplib.py
Lib/getopt.py
Lib/gzip.py
Lib/locale.py
Lib/macurl2path.py
Lib/mimify.py
Lib/os.py
Lib/pdb.py
Lib/pyclbr.py
Lib/sched.py
Lib/smtplib.py
Lib/statcache.py
Lib/xmllib.py

index e725a2b12ad856fe8a357465b555421c30994d5a..8b2f59fa32615931a4eb1ff6ba35f1b6634980db 100644 (file)
 # 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()"""
index 07b9fc3aa83c733a9dbf444e43d50f7ab0eb60f4..8e11d764a42afaddc29304eefdbc4688ca286e85 100644 (file)
 # 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
index 3fc72348b9cb3f7d38da0214ac76fa5b26a2a0ec..db6a7ef9f54598e4a293e56bbdec09f2fe5f406e 100644 (file)
@@ -1,4 +1,4 @@
-"""binhex - Macintosh binhex compression/decompression
+"""Macintosh binhex compression/decompression.
 
 easy interface:
 binhex(inputfilename, outputfilename)
index 2d9de3cad35ebf581d8e63df06ffb42ea23dd04b..e4679deca2abf428a07da3416cb9559a036182d9 100644 (file)
@@ -1,6 +1,4 @@
-"""\
-Generic (shallow and deep) copying operations
-=============================================
+"""Generic (shallow and deep) copying operations.
 
 Interface summary:
 
index b0a366539c7dd12f596a99044597b338896de003..a35e16d1bc6ad5366e9c84c04fb47c1f0ca98f3c 100644 (file)
@@ -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
 
index 2ad21f06505de51923ae4443d46316b4f5aaeef1..4e4be5651889b626a7891726f708a575d70ee4c7 100644 (file)
@@ -1,4 +1,4 @@
-"""Module 'dospath' -- common operations on DOS pathnames"""
+"""Common operations on DOS pathnames."""
 
 import os
 import stat
index 4b340d52ba3c6168964c75028cc8fbbd2799b6c5..4d6a1292effbc427e6eece42900f7f74dbd69e68 100644 (file)
@@ -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
index eee8e5a82650b47614edcefdfed25a5d1f24d367..94ae880142c951b469fcaa4bfecd3a596c953917 100644 (file)
@@ -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
index b5fdaedc43588dd38d3bcf43db0ed6aa3a4d8359..692b8b96483c2578b08b17143ad95b93cf15debf 100644 (file)
@@ -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()
index ee39169d07e455bf47676c0ccff298e5db2b98a6..25278bef3b7c1c4234ef6b863ba06ddb860ecacd 100644 (file)
@@ -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."""
 
index d85cabfca5898287a0f27a5eaa9b3d55516b93c1..9be729d7d6c91b5dcbf86bddd38a673a4fdaf62c 100644 (file)
@@ -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 *
index 4c43d2110f54cd6ad8dd60e3744ba9e1b138cc8e..c971edaa22dad13a1ffe4b57cff15255334ef45a 100644 (file)
@@ -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
index 354cdb7477ee091d55eea171696056e2c9984777..20b4d6c0873718d695b264b8ec3d928785ec4b8c 100755 (executable)
@@ -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
index 129d4b29980b019766eb03367e6d14f36bccc456..118b6198bfa201089c234ff1c74a41ca4cec2f35 100644 (file)
--- 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
index 3835f038c84841bb7a93d1d9c4e026548d5c672a..2e450989b722d8f71fa223920bb76f1953374f21 100755 (executable)
@@ -1,6 +1,6 @@
 #! /usr/bin/env python
 
-"""pdb.py -- finally, a Python debugger!"""
+"""A Python debugger."""
 
 # (See pdb.doc for documentation.)
 
index de3fedce114d90b253c36b763c63d3363be72d20..74b7ff73c2ec172babb1958e0d59c92251c149b2 100644 (file)
@@ -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
index 147977cfe9bc4cd8c93fd86271c3f51d3377c5fb..f51d835d772dd69d0669276e201885a08fd83a33 100644 (file)
@@ -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
index 1c42233f2627687612b09bec1f1e9fd036502b55..df8907da0f48e7496ba4a23bb3e1e365d2097aea 100755 (executable)
@@ -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 @@ Example:
   >>> s.getreply()
   (250, "Somebody OverHere <somebody@here.my.org>")
   >>> s.quit()
-'''
+"""
 
 import socket
 import string
index 0d88a9a584830f7f2c5e2386dc4e110bd696dae8..b5147c233dc545952790a88e3f014d6427565c01 100644 (file)
@@ -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.
 """
 
index dcfe87268735ea351c6788ceeccebaa7c7a062f5..16a56b04fbaf6c307132c242629738605e772605 100644 (file)
@@ -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