# 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()"""
# 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
-"""binhex - Macintosh binhex compression/decompression
+"""Macintosh binhex compression/decompression.
easy interface:
binhex(inputfilename, outputfilename)
-"""\
-Generic (shallow and deep) copying operations
-=============================================
+"""Generic (shallow and deep) copying operations.
Interface summary:
-"""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
-"""Module 'dospath' -- common operations on DOS pathnames"""
+"""Common operations on DOS pathnames."""
import os
import stat
+"""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
-'''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
A nice test that reveals some of the network dialogue would be:
python ftplib.py -d localhost -l -p -l
-'''
+"""
import os
-"""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()
-"""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."""
-"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 *
-"""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
#! /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.
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
-"""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
#! /usr/bin/env python
-"""pdb.py -- finally, a Python debugger!"""
+"""A Python debugger."""
# (See pdb.doc for documentation.)
-'''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.
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
-"""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
#! /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
>>> s.getreply()
(250, "Somebody OverHere <somebody@here.my.org>")
>>> s.quit()
-'''
+"""
import socket
import string
-"""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.
"""
-# 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
projects / python / commitdiff