Move the 3k reST doc tree in place.

Doc/library/__builtin__.rst

@@ -0,0 +1,41 @@
+
+:mod:`__builtin__` --- Built-in objects
+=======================================
+
+.. module:: __builtin__
+   :synopsis: The module that provides the built-in namespace.
+
+
+This module provides direct access to all 'built-in' identifiers of Python; for
+example, ``__builtin__.open`` is the full name for the built-in function
+:func:`open`.  See chapter :ref:`builtin`.
+
+This module is not normally accessed explicitly by most applications, but can be
+useful in modules that provide objects with the same name as a built-in value,
+but in which the built-in of that name is also needed.  For example, in a module
+that wants to implement an :func:`open` function that wraps the built-in
+:func:`open`, this module can be used directly::
+
+   import __builtin__
+
+   def open(path):
+       f = __builtin__.open(path, 'r')
+       return UpperCaser(f)
+
+   class UpperCaser:
+       '''Wrapper around a file that converts output to upper-case.'''
+
+       def __init__(self, f):
+           self._f = f
+
+       def read(self, count=-1):
+           return self._f.read(count).upper()
+
+       # ...
+
+As an implementation detail, most modules have the name ``__builtins__`` (note
+the ``'s'``) made available as part of their globals.  The value of
+``__builtins__`` is normally either this module or the value of this modules's
+:attr:`__dict__` attribute.  Since this is an implementation detail, it may not
+be used by alternate implementations of Python.
+

Doc/library/__future__.rst

@@ -0,0 +1,61 @@
+
+:mod:`__future__` --- Future statement definitions
+==================================================
+
+.. module:: __future__
+   :synopsis: Future statement definitions
+
+
+:mod:`__future__` is a real module, and serves three purposes:
+
+* To avoid confusing existing tools that analyze import statements and expect to
+  find the modules they're importing.
+
+* To ensure that future_statements run under releases prior to 2.1 at least
+  yield runtime exceptions (the import of :mod:`__future__` will fail, because
+  there was no module of that name prior to 2.1).
+
+* To document when incompatible changes were introduced, and when they will be
+  --- or were --- made mandatory.  This is a form of executable documentation, and
+  can be inspected programatically via importing :mod:`__future__` and examining
+  its contents.
+
+Each statement in :file:`__future__.py` is of the form::
+
+   FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ","
+                           CompilerFlag ")"
+
+
+where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are
+5-tuples of the same form as ``sys.version_info``::
+
+   (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
+    PY_MINOR_VERSION, # the 1; an int
+    PY_MICRO_VERSION, # the 0; an int
+    PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
+    PY_RELEASE_SERIAL # the 3; an int
+   )
+
+*OptionalRelease* records the first release in which the feature was accepted.
+
+In the case of a *MandatoryRelease* that has not yet occurred,
+*MandatoryRelease* predicts the release in which the feature will become part of
+the language.
+
+Else *MandatoryRelease* records when the feature became part of the language; in
+releases at or after that, modules no longer need a future statement to use the
+feature in question, but may continue to use such imports.
+
+*MandatoryRelease* may also be ``None``, meaning that a planned feature got
+dropped.
+
+Instances of class :class:`_Feature` have two corresponding methods,
+:meth:`getOptionalRelease` and :meth:`getMandatoryRelease`.
+
+*CompilerFlag* is the (bitfield) flag that should be passed in the fourth
+argument to the builtin function :func:`compile` to enable the feature in
+dynamically compiled code.  This flag is stored in the :attr:`compiler_flag`
+attribute on :class:`_Feature` instances.
+
+No feature description will ever be deleted from :mod:`__future__`.
+

Doc/library/__main__.rst

@@ -0,0 +1,17 @@
+
+:mod:`__main__` --- Top-level script environment
+================================================
+
+.. module:: __main__
+   :synopsis: The environment where the top-level script is run.
+
+
+This module represents the (otherwise anonymous) scope in which the
+interpreter's main program executes --- commands read either from standard
+input, from a script file, or from an interactive prompt.  It is this
+environment in which the idiomatic "conditional script" stanza causes a script
+to run::
+
+   if __name__ == "__main__":
+       main()
+

Doc/library/_ast.rst

@@ -0,0 +1,59 @@
+.. _ast:
+
+Abstract Syntax Trees
+=====================
+
+.. module:: _ast
+   :synopsis: Abstract Syntax Tree classes.
+
+.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
+
+
+.. versionadded:: 2.5
+
+The ``_ast`` module helps Python applications to process trees of the Python
+abstract syntax grammar. The Python compiler currently provides read-only access
+to such trees, meaning that applications can only create a tree for a given
+piece of Python source code; generating byte code from a (potentially modified)
+tree is not supported. The abstract syntax itself might change with each Python
+release; this module helps to find out programmatically what the current grammar
+looks like.
+
+An abstract syntax tree can be generated by passing ``_ast.PyCF_ONLY_AST`` as a
+flag to the :func:`compile` builtin function. The result will be a tree of
+objects whose classes all inherit from ``_ast.AST``.
+
+The actual classes are derived from the ``Parser/Python.asdl`` file, which is
+reproduced below. There is one class defined for each left-hand side symbol in
+the abstract grammar (for example, ``_ast.stmt`` or ``_ast.expr``). In addition,
+there is one class defined for each constructor on the right-hand side; these
+classes inherit from the classes for the left-hand side trees. For example,
+``_ast.BinOp`` inherits from ``_ast.expr``. For production rules with
+alternatives (aka "sums"), the left-hand side class is abstract: only instances
+of specific constructor nodes are ever created.
+
+Each concrete class has an attribute ``_fields`` which gives the names of all
+child nodes.
+
+Each instance of a concrete class has one attribute for each child node, of the
+type as defined in the grammar. For example, ``_ast.BinOp`` instances have an
+attribute ``left`` of type ``_ast.expr``.   Instances of ``_ast.expr`` and
+``_ast.stmt`` subclasses also have lineno and col_offset attributes.  The lineno
+is the line number of source text (1 indexed so the first line is line 1) and
+the col_offset is the utf8 byte offset of the first token that generated the
+node.  The utf8 offset is recorded because the parser uses utf8  internally.
+
+If these attributes are marked as optional in the grammar (using a question
+mark), the value might be ``None``. If the attributes can have zero-or-more
+values (marked with an asterisk), the values are represented as Python lists.
+
+
+Abstract Grammar
+----------------
+
+The module defines a string constant ``__version__`` which is the decimal
+subversion revision number of the file shown below.
+
+The abstract grammar is currently defined as follows:
+
+.. literalinclude:: ../../Parser/Python.asdl

Doc/library/_winreg.rst

@@ -0,0 +1,420 @@
+
+:mod:`_winreg` -- Windows registry access
+=========================================
+
+.. module:: _winreg
+   :platform: Windows
+   :synopsis: Routines and objects for manipulating the Windows registry.
+.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
+
+
+.. versionadded:: 2.0
+
+These functions expose the Windows registry API to Python.  Instead of using an
+integer as the registry handle, a handle object is used to ensure that the
+handles are closed correctly, even if the programmer neglects to explicitly
+close them.
+
+This module exposes a very low-level interface to the Windows registry; it is
+expected that in the future a new ``winreg``  module will be created offering a
+higher-level interface to the registry API.
+
+This module offers the following functions:
+
+
+.. function:: CloseKey(hkey)
+
+   Closes a previously opened registry key. The hkey argument specifies a
+   previously opened key.
+
+   Note that if *hkey* is not closed using this method (or via
+   :meth:`handle.Close`), it is closed when the *hkey* object is destroyed by
+   Python.
+
+
+.. function:: ConnectRegistry(computer_name, key)
+
+   Establishes a connection to a predefined registry handle on  another computer,
+   and returns a :dfn:`handle object`
+
+   *computer_name* is the name of the remote computer, of the  form
+   ``r"\\computername"``.  If ``None``, the local computer is used.
+
+   *key* is the predefined handle to connect to.
+
+   The return value is the handle of the opened key. If the function fails, an
+   :exc:`EnvironmentError` exception is  raised.
+
+
+.. function:: CreateKey(key, sub_key)
+
+   Creates or opens the specified key, returning a :dfn:`handle object`
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *sub_key* is a string that names the key this method opens  or creates.
+
+   If *key* is one of the predefined keys, *sub_key* may  be ``None``. In that
+   case, the handle returned is the same key handle  passed in to the function.
+
+   If the key already exists, this function opens the existing key.
+
+   The return value is the handle of the opened key. If the function fails, an
+   :exc:`EnvironmentError` exception is  raised.
+
+
+.. function:: DeleteKey(key, sub_key)
+
+   Deletes the specified key.
+
+   *key* is an already open key, or any one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *sub_key* is a string that must be a subkey of the key  identified by the *key*
+   parameter.  This value must not be  ``None``, and the key may not have subkeys.
+
+   *This method can not delete keys with subkeys.*
+
+   If the method succeeds, the entire key, including all of its values, is removed.
+   If the method fails, an :exc:`EnvironmentError`  exception is raised.
+
+
+.. function:: DeleteValue(key, value)
+
+   Removes a named value from a registry key.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *value* is a string that identifies the value to remove.
+
+
+.. function:: EnumKey(key, index)
+
+   Enumerates subkeys of an open registry key, returning a string.
+
+   *key* is an already open key, or any one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *index* is an integer that identifies the index of the key to  retrieve.
+
+   The function retrieves the name of one subkey each time it  is called.  It is
+   typically called repeatedly until an  :exc:`EnvironmentError` exception  is
+   raised, indicating, no more values are available.
+
+
+.. function:: EnumValue(key, index)
+
+   Enumerates values of an open registry key, returning a tuple.
+
+   *key* is an already open key, or any one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *index* is an integer that identifies the index of the value  to retrieve.
+
+   The function retrieves the name of one subkey each time it is  called. It is
+   typically called repeatedly, until an  :exc:`EnvironmentError` exception is
+   raised, indicating  no more values.
+
+   The result is a tuple of 3 items:
+
+   +-------+--------------------------------------------+
+   | Index | Meaning                                    |
+   +=======+============================================+
+   | ``0`` | A string that identifies the value name    |
+   +-------+--------------------------------------------+
+   | ``1`` | An object that holds the value data, and   |
+   |       | whose type depends on the underlying       |
+   |       | registry type                              |
+   +-------+--------------------------------------------+
+   | ``2`` | An integer that identifies the type of the |
+   |       | value data                                 |
+   +-------+--------------------------------------------+
+
+
+.. function:: FlushKey(key)
+
+   Writes all the attributes of a key to the registry.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   It is not necessary to call RegFlushKey to change a key. Registry changes are
+   flushed to disk by the registry using its lazy  flusher.  Registry changes are
+   also flushed to disk at system  shutdown.  Unlike :func:`CloseKey`, the
+   :func:`FlushKey` method  returns only when all the data has been written to the
+   registry. An application should only call :func:`FlushKey` if it requires
+   absolute  certainty that registry changes are on disk.
+
+   .. note::
+
+      If you don't know whether a :func:`FlushKey` call is required, it  probably
+      isn't.
+
+
+.. function:: RegLoadKey(key, sub_key, file_name)
+
+   Creates a subkey under the specified key and stores registration  information
+   from a specified file into that subkey.
+
+   *key* is an already open key, or any of the predefined :const:`HKEY_\*`
+   constants.
+
+   *sub_key* is a string that identifies the sub_key to load.
+
+   *file_name* is the name of the file to load registry data from. This file must
+   have been created with the :func:`SaveKey` function. Under the file allocation
+   table (FAT) file system, the filename may not have an extension.
+
+   A call to LoadKey() fails if the calling process does not have the
+   :const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different than
+   permissions - see the Win32 documentation for more details.
+
+   If *key* is a handle returned by :func:`ConnectRegistry`,  then the path
+   specified in *fileName* is relative to the  remote computer.
+
+   The Win32 documentation implies *key* must be in the  :const:`HKEY_USER` or
+   :const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true.
+
+
+.. function:: OpenKey(key, sub_key[, res=0][, sam=KEY_READ])
+
+   Opens the specified key, returning a :dfn:`handle object`
+
+   *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
+   constants.
+
+   *sub_key* is a string that identifies the sub_key to open.
+
+   *res* is a reserved integer, and must be zero.  The default is zero.
+
+   *sam* is an integer that specifies an access mask that describes  the desired
+   security access for the key.  Default is :const:`KEY_READ`
+
+   The result is a new handle to the specified key.
+
+   If the function fails, :exc:`EnvironmentError` is raised.
+
+
+.. function:: OpenKeyEx()
+
+   The functionality of :func:`OpenKeyEx` is provided via :func:`OpenKey`, by the
+   use of default arguments.
+
+
+.. function:: QueryInfoKey(key)
+
+   Returns information about a key, as a tuple.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   The result is a tuple of 3 items:
+
+   +-------+---------------------------------------------+
+   | Index | Meaning                                     |
+   +=======+=============================================+
+   | ``0`` | An integer giving the number of sub keys    |
+   |       | this key has.                               |
+   +-------+---------------------------------------------+
+   | ``1`` | An integer giving the number of values this |
+   |       | key has.                                    |
+   +-------+---------------------------------------------+
+   | ``2`` | A long integer giving when the key was last |
+   |       | modified (if available) as 100's of         |
+   |       | nanoseconds since Jan 1, 1600.              |
+   +-------+---------------------------------------------+
+
+
+.. function:: QueryValue(key, sub_key)
+
+   Retrieves the unnamed value for a key, as a string
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *sub_key* is a string that holds the name of the subkey with which  the value is
+   associated.  If this parameter is ``None`` or empty, the  function retrieves the
+   value set by the :func:`SetValue` method  for the key identified by *key*.
+
+   Values in the registry have name, type, and data components. This  method
+   retrieves the data for a key's first value that has a NULL name. But the
+   underlying API call doesn't return the type, Lame Lame Lame, DO NOT USE THIS!!!
+
+
+.. function:: QueryValueEx(key, value_name)
+
+   Retrieves the type and data for a specified value name associated with  an open
+   registry key.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *value_name* is a string indicating the value to query.
+
+   The result is a tuple of 2 items:
+
+   +-------+-----------------------------------------+
+   | Index | Meaning                                 |
+   +=======+=========================================+
+   | ``0`` | The value of the registry item.         |
+   +-------+-----------------------------------------+
+   | ``1`` | An integer giving the registry type for |
+   |       | this value.                             |
+   +-------+-----------------------------------------+
+
+
+.. function:: SaveKey(key, file_name)
+
+   Saves the specified key, and all its subkeys to the specified file.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *file_name* is the name of the file to save registry data to. This file cannot
+   already exist. If this filename includes an extension, it cannot be used on file
+   allocation table (FAT) file systems by the :meth:`LoadKey`, :meth:`ReplaceKey`
+   or  :meth:`RestoreKey` methods.
+
+   If *key* represents a key on a remote computer, the path  described by
+   *file_name* is relative to the remote computer. The caller of this method must
+   possess the :const:`SeBackupPrivilege`  security privilege.  Note that
+   privileges are different than permissions  - see the Win32 documentation for
+   more details.
+
+   This function passes NULL for *security_attributes* to the API.
+
+
+.. function:: SetValue(key, sub_key, type, value)
+
+   Associates a value with a specified key.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *sub_key* is a string that names the subkey with which the value  is associated.
+
+   *type* is an integer that specifies the type of the data. Currently this must be
+   :const:`REG_SZ`, meaning only strings are supported.  Use the :func:`SetValueEx`
+   function for support for other data types.
+
+   *value* is a string that specifies the new value.
+
+   If the key specified by the *sub_key* parameter does not exist, the SetValue
+   function creates it.
+
+   Value lengths are limited by available memory. Long values (more than 2048
+   bytes) should be stored as files with the filenames stored in the configuration
+   registry.  This helps the registry perform efficiently.
+
+   The key identified by the *key* parameter must have been  opened with
+   :const:`KEY_SET_VALUE` access.
+
+
+.. function:: SetValueEx(key, value_name, reserved, type, value)
+
+   Stores data in the value field of an open registry key.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *value_name* is a string that names the subkey with which the  value is
+   associated.
+
+   *type* is an integer that specifies the type of the data.   This should be one
+   of the following constants defined in this module:
+
+   +----------------------------------+---------------------------------------------+
+   | Constant                         | Meaning                                     |
+   +==================================+=============================================+
+   | :const:`REG_BINARY`              | Binary data in any form.                    |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_DWORD`               | A 32-bit number.                            |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_DWORD_LITTLE_ENDIAN` | A 32-bit number in little-endian format.    |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_DWORD_BIG_ENDIAN`    | A 32-bit number in big-endian format.       |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_EXPAND_SZ`           | Null-terminated string containing           |
+   |                                  | references to environment variables         |
+   |                                  | (``%PATH%``).                               |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_LINK`                | A Unicode symbolic link.                    |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_MULTI_SZ`            | A sequence of null-terminated strings,      |
+   |                                  | terminated by two null characters.  (Python |
+   |                                  | handles  this termination automatically.)   |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_NONE`                | No defined value type.                      |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_RESOURCE_LIST`       | A device-driver resource list.              |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_SZ`                  | A null-terminated string.                   |
+   +----------------------------------+---------------------------------------------+
+
+   *reserved* can be anything - zero is always passed to the  API.
+
+   *value* is a string that specifies the new value.
+
+   This method can also set additional value and type information for the specified
+   key.  The key identified by the key parameter must have been opened with
+   :const:`KEY_SET_VALUE` access.
+
+   To open the key, use the :func:`CreateKeyEx` or  :func:`OpenKey` methods.
+
+   Value lengths are limited by available memory. Long values (more than 2048
+   bytes) should be stored as files with the filenames stored in the configuration
+   registry.  This helps the registry perform efficiently.
+
+
+.. _handle-object:
+
+Registry Handle Objects
+-----------------------
+
+This object wraps a Windows HKEY object, automatically closing it when the
+object is destroyed.  To guarantee cleanup, you can call either the
+:meth:`Close` method on the object, or the  :func:`CloseKey` function.
+
+All registry functions in this module return one of these objects.
+
+All registry functions in this module which accept a handle object  also accept
+an integer, however, use of the handle object is  encouraged.
+
+Handle objects provide semantics for :meth:`__bool__` - thus  ::
+
+   if handle:
+       print "Yes"
+
+will print ``Yes`` if the handle is currently valid (has not been closed or
+detached).
+
+The object also support comparison semantics, so handle objects will compare
+true if they both reference the same underlying Windows handle value.
+
+Handle objects can be converted to an integer (e.g., using the builtin
+:func:`int` function), in which case the underlying Windows handle value is
+returned.  You can also use the  :meth:`Detach` method to return the integer
+handle, and also disconnect the Windows handle from the handle object.
+
+
+.. method:: PyHKEY.Close()
+
+   Closes the underlying Windows handle.
+
+   If the handle is already closed, no error is raised.
+
+
+.. method:: PyHKEY.Detach()
+
+   Detaches the Windows handle from the handle object.
+
+   The result is an integer (or long on 64 bit Windows) that holds the value of the
+   handle before it is detached.  If the handle is already detached or closed, this
+   will return zero.
+
+   After calling this function, the handle is effectively invalidated, but the
+   handle is not closed.  You would call this function when  you need the
+   underlying Win32 handle to exist beyond the lifetime  of the handle object.
+

Doc/library/aepack.rst

@@ -0,0 +1,92 @@
+
+:mod:`aepack` --- Conversion between Python variables and AppleEvent data containers
+====================================================================================
+
+.. module:: aepack
+   :platform: Mac
+   :synopsis: Conversion between Python variables and AppleEvent data containers.
+.. sectionauthor:: Vincent Marchetti <vincem@en.com>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aepack` module defines functions for converting (packing) Python
+variables to AppleEvent descriptors and back (unpacking). Within Python the
+AppleEvent descriptor is handled by Python objects of built-in type
+:class:`AEDesc`, defined in module :mod:`Carbon.AE`.
+
+The :mod:`aepack` module defines the following functions:
+
+
+.. function:: pack(x[, forcetype])
+
+   Returns an :class:`AEDesc` object  containing a conversion of Python value x. If
+   *forcetype* is provided it specifies the descriptor type of the result.
+   Otherwise, a default mapping of Python types to Apple Event descriptor types is
+   used, as follows:
+
+   +-----------------+-----------------------------------+
+   | Python type     | descriptor type                   |
+   +=================+===================================+
+   | :class:`FSSpec` | typeFSS                           |
+   +-----------------+-----------------------------------+
+   | :class:`FSRef`  | typeFSRef                         |
+   +-----------------+-----------------------------------+
+   | :class:`Alias`  | typeAlias                         |
+   +-----------------+-----------------------------------+
+   | integer         | typeLong (32 bit integer)         |
+   +-----------------+-----------------------------------+
+   | float           | typeFloat (64 bit floating point) |
+   +-----------------+-----------------------------------+
+   | string          | typeText                          |
+   +-----------------+-----------------------------------+
+   | unicode         | typeUnicodeText                   |
+   +-----------------+-----------------------------------+
+   | list            | typeAEList                        |
+   +-----------------+-----------------------------------+
+   | dictionary      | typeAERecord                      |
+   +-----------------+-----------------------------------+
+   | instance        | *see below*                       |
+   +-----------------+-----------------------------------+
+
+   If *x* is a Python instance then this function attempts to call an
+   :meth:`__aepack__` method.  This method should return an :class:`AEDesc` object.
+
+   If the conversion *x* is not defined above, this function returns the Python
+   string representation of a value (the repr() function) encoded as a text
+   descriptor.
+
+
+.. function:: unpack(x[, formodulename])
+
+   *x* must be an object of type :class:`AEDesc`. This function returns a Python
+   object representation of the data in the Apple Event descriptor *x*. Simple
+   AppleEvent data types (integer, text, float) are returned as their obvious
+   Python counterparts. Apple Event lists are returned as Python lists, and the
+   list elements are recursively unpacked.  Object references (ex. ``line 3 of
+   document 1``) are returned as instances of :class:`aetypes.ObjectSpecifier`,
+   unless ``formodulename`` is specified.  AppleEvent descriptors with descriptor
+   type typeFSS are returned as :class:`FSSpec` objects.  AppleEvent record
+   descriptors are returned as Python dictionaries, with 4-character string keys
+   and elements recursively unpacked.
+
+   The optional ``formodulename`` argument is used by the stub packages generated
+   by :mod:`gensuitemodule`, and ensures that the OSA classes for object specifiers
+   are looked up in the correct module. This ensures that if, say, the Finder
+   returns an object specifier for a window you get an instance of
+   ``Finder.Window`` and not a generic ``aetypes.Window``. The former knows about
+   all the properties and elements a window has in the Finder, while the latter
+   knows no such things.
+
+
+.. seealso::
+
+   Module :mod:`Carbon.AE`
+      Built-in access to Apple Event Manager routines.
+
+   Module :mod:`aetypes`
+      Python definitions of codes for Apple Event descriptor types.
+
+   ` Inside Macintosh: Interapplication Communication <http://developer.apple.com/techpubs/mac/IAC/IAC-2.html>`_
+      Information about inter-process communications on the Macintosh.
+

Doc/library/aetools.rst

@@ -0,0 +1,86 @@
+
+:mod:`aetools` --- OSA client support
+=====================================
+
+.. module:: aetools
+   :platform: Mac
+   :synopsis: Basic support for sending Apple Events
+.. sectionauthor:: Jack Jansen <Jack.Jansen@cwi.nl>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aetools` module contains the basic functionality on which Python
+AppleScript client support is built. It also imports and re-exports the core
+functionality of the :mod:`aetypes` and :mod:`aepack` modules. The stub packages
+generated by :mod:`gensuitemodule` import the relevant portions of
+:mod:`aetools`, so usually you do not need to import it yourself. The exception
+to this is when you cannot use a generated suite package and need lower-level
+access to scripting.
+
+The :mod:`aetools` module itself uses the AppleEvent support provided by the
+:mod:`Carbon.AE` module. This has one drawback: you need access to the window
+manager, see section :ref:`osx-gui-scripts` for details. This restriction may be
+lifted in future releases.
+
+The :mod:`aetools` module defines the following functions:
+
+
+.. function:: packevent(ae, parameters, attributes)
+
+   Stores parameters and attributes in a pre-created ``Carbon.AE.AEDesc`` object.
+   ``parameters`` and ``attributes`` are  dictionaries mapping 4-character OSA
+   parameter keys to Python objects. The objects are packed using
+   ``aepack.pack()``.
+
+
+.. function:: unpackevent(ae[, formodulename])
+
+   Recursively unpacks a ``Carbon.AE.AEDesc`` event to Python objects. The function
+   returns the parameter dictionary and the attribute dictionary. The
+   ``formodulename`` argument is used by generated stub packages to control where
+   AppleScript classes are looked up.
+
+
+.. function:: keysubst(arguments, keydict)
+
+   Converts a Python keyword argument dictionary ``arguments`` to the format
+   required by ``packevent`` by replacing the keys, which are Python identifiers,
+   by the four-character OSA keys according to the mapping specified in
+   ``keydict``. Used by the generated suite packages.
+
+
+.. function:: enumsubst(arguments, key, edict)
+
+   If the ``arguments`` dictionary contains an entry for ``key`` convert the value
+   for that entry according to dictionary ``edict``. This converts human-readable
+   Python enumeration names to the OSA 4-character codes. Used by the generated
+   suite packages.
+
+The :mod:`aetools` module defines the following class:
+
+
+.. class:: TalkTo([signature=None, start=0, timeout=0])
+
+   Base class for the proxy used to talk to an application. ``signature`` overrides
+   the class attribute ``_signature`` (which is usually set by subclasses) and is
+   the 4-char creator code defining the application to talk to. ``start`` can be
+   set to true to enable running the application on class instantiation.
+   ``timeout`` can be specified to change the default timeout used while waiting
+   for an AppleEvent reply.
+
+
+.. method:: TalkTo._start()
+
+   Test whether the application is running, and attempt to start it if not.
+
+
+.. method:: TalkTo.send(code, subcode[, parameters, attributes])
+
+   Create the AppleEvent ``Carbon.AE.AEDesc`` for the verb with the OSA designation
+   ``code, subcode`` (which are the usual 4-character strings), pack the
+   ``parameters`` and ``attributes`` into it, send it to the target application,
+   wait for the reply, unpack the reply with ``unpackevent`` and return the reply
+   appleevent, the unpacked return values as a dictionary and the return
+   attributes.
+

Doc/library/aetypes.rst

@@ -0,0 +1,150 @@
+
+:mod:`aetypes` --- AppleEvent objects
+=====================================
+
+.. module:: aetypes
+   :platform: Mac
+   :synopsis: Python representation of the Apple Event Object Model.
+.. sectionauthor:: Vincent Marchetti <vincem@en.com>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aetypes` defines classes used to represent Apple Event data
+descriptors and Apple Event object specifiers.
+
+Apple Event data is contained in descriptors, and these descriptors are typed.
+For many descriptors the Python representation is simply the corresponding
+Python type: ``typeText`` in OSA is a Python string, ``typeFloat`` is a float,
+etc. For OSA types that have no direct Python counterpart this module declares
+classes. Packing and unpacking instances of these classes is handled
+automatically by :mod:`aepack`.
+
+An object specifier is essentially an address of an object implemented in a
+Apple Event server. An Apple Event specifier is used as the direct object for an
+Apple Event or as the argument of an optional parameter. The :mod:`aetypes`
+module contains the base classes for OSA classes and properties, which are used
+by the packages generated by :mod:`gensuitemodule` to populate the classes and
+properties in a given suite.
+
+For reasons of backward compatibility, and for cases where you need to script an
+application for which you have not generated the stub package this module also
+contains object specifiers for a number of common OSA classes such as
+``Document``, ``Window``, ``Character``, etc.
+
+The :mod:`AEObjects` module defines the following classes to represent Apple
+Event descriptor data:
+
+
+.. class:: Unknown(type, data)
+
+   The representation of OSA descriptor data for which the :mod:`aepack` and
+   :mod:`aetypes` modules have no support, i.e. anything that is not represented by
+   the other classes here and that is not equivalent to a simple Python value.
+
+
+.. class:: Enum(enum)
+
+   An enumeration value with the given 4-character string value.
+
+
+.. class:: InsertionLoc(of, pos)
+
+   Position ``pos`` in object ``of``.
+
+
+.. class:: Boolean(bool)
+
+   A boolean.
+
+
+.. class:: StyledText(style, text)
+
+   Text with style information (font, face, etc) included.
+
+
+.. class:: AEText(script, style, text)
+
+   Text with script system and style information included.
+
+
+.. class:: IntlText(script, language, text)
+
+   Text with script system and language information included.
+
+
+.. class:: IntlWritingCode(script, language)
+
+   Script system and language information.
+
+
+.. class:: QDPoint(v, h)
+
+   A quickdraw point.
+
+
+.. class:: QDRectangle(v0, h0, v1, h1)
+
+   A quickdraw rectangle.
+
+
+.. class:: RGBColor(r, g, b)
+
+   A color.
+
+
+.. class:: Type(type)
+
+   An OSA type value with the given 4-character name.
+
+
+.. class:: Keyword(name)
+
+   An OSA keyword with the given 4-character name.
+
+
+.. class:: Range(start, stop)
+
+   A range.
+
+
+.. class:: Ordinal(abso)
+
+   Non-numeric absolute positions, such as ``"firs"``, first, or ``"midd"``,
+   middle.
+
+
+.. class:: Logical(logc, term)
+
+   The logical expression of applying operator ``logc`` to ``term``.
+
+
+.. class:: Comparison(obj1, relo, obj2)
+
+   The comparison ``relo`` of ``obj1`` to ``obj2``.
+
+The following classes are used as base classes by the generated stub packages to
+represent AppleScript classes and properties in Python:
+
+
+.. class:: ComponentItem(which[, fr])
+
+   Abstract baseclass for an OSA class. The subclass should set the class attribute
+   ``want`` to the 4-character OSA class code. Instances of subclasses of this
+   class are equivalent to AppleScript Object Specifiers. Upon instantiation you
+   should pass a selector in ``which``, and optionally a parent object in ``fr``.
+
+
+.. class:: NProperty(fr)
+
+   Abstract baseclass for an OSA property. The subclass should set the class
+   attributes ``want`` and ``which`` to designate which property we are talking
+   about. Instances of subclasses of this class are Object Specifiers.
+
+
+.. class:: ObjectSpecifier(want, form, seld[, fr])
+
+   Base class of ``ComponentItem`` and ``NProperty``, a general OSA Object
+   Specifier. See the Apple Open Scripting Architecture documentation for the
+   parameters. Note that this class is not abstract.
+

Doc/library/aifc.rst

@@ -0,0 +1,225 @@
+
+:mod:`aifc` --- Read and write AIFF and AIFC files
+==================================================
+
+.. module:: aifc
+   :synopsis: Read and write audio files in AIFF or AIFC format.
+
+
+.. index::
+   single: Audio Interchange File Format
+   single: AIFF
+   single: AIFF-C
+
+This module provides support for reading and writing AIFF and AIFF-C files.
+AIFF is Audio Interchange File Format, a format for storing digital audio
+samples in a file.  AIFF-C is a newer version of the format that includes the
+ability to compress the audio data.
+
+**Caveat:**  Some operations may only work under IRIX; these will raise
+:exc:`ImportError` when attempting to import the :mod:`cl` module, which is only
+available on IRIX.
+
+Audio files have a number of parameters that describe the audio data. The
+sampling rate or frame rate is the number of times per second the sound is
+sampled.  The number of channels indicate if the audio is mono, stereo, or
+quadro.  Each frame consists of one sample per channel.  The sample size is the
+size in bytes of each sample.  Thus a frame consists of
+*nchannels*\**samplesize* bytes, and a second's worth of audio consists of
+*nchannels*\**samplesize*\**framerate* bytes.
+
+For example, CD quality audio has a sample size of two bytes (16 bits), uses two
+channels (stereo) and has a frame rate of 44,100 frames/second.  This gives a
+frame size of 4 bytes (2\*2), and a second's worth occupies 2\*2\*44100 bytes
+(176,400 bytes).
+
+Module :mod:`aifc` defines the following function:
+
+
+.. function:: open(file[, mode])
+
+   Open an AIFF or AIFF-C file and return an object instance with methods that are
+   described below.  The argument *file* is either a string naming a file or a file
+   object.  *mode* must be ``'r'`` or ``'rb'`` when the file must be opened for
+   reading, or ``'w'``  or ``'wb'`` when the file must be opened for writing.  If
+   omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used.  When
+   used for writing, the file object should be seekable, unless you know ahead of
+   time how many samples you are going to write in total and use
+   :meth:`writeframesraw` and :meth:`setnframes`.
+
+Objects returned by :func:`open` when a file is opened for reading have the
+following methods:
+
+
+.. method:: aifc.getnchannels()
+
+   Return the number of audio channels (1 for mono, 2 for stereo).
+
+
+.. method:: aifc.getsampwidth()
+
+   Return the size in bytes of individual samples.
+
+
+.. method:: aifc.getframerate()
+
+   Return the sampling rate (number of audio frames per second).
+
+
+.. method:: aifc.getnframes()
+
+   Return the number of audio frames in the file.
+
+
+.. method:: aifc.getcomptype()
+
+   Return a four-character string describing the type of compression used in the
+   audio file.  For AIFF files, the returned value is ``'NONE'``.
+
+
+.. method:: aifc.getcompname()
+
+   Return a human-readable description of the type of compression used in the audio
+   file.  For AIFF files, the returned value is ``'not compressed'``.
+
+
+.. method:: aifc.getparams()
+
+   Return a tuple consisting of all of the above values in the above order.
+
+
+.. method:: aifc.getmarkers()
+
+   Return a list of markers in the audio file.  A marker consists of a tuple of
+   three elements.  The first is the mark ID (an integer), the second is the mark
+   position in frames from the beginning of the data (an integer), the third is the
+   name of the mark (a string).
+
+
+.. method:: aifc.getmark(id)
+
+   Return the tuple as described in :meth:`getmarkers` for the mark with the given
+   *id*.
+
+
+.. method:: aifc.readframes(nframes)
+
+   Read and return the next *nframes* frames from the audio file.  The returned
+   data is a string containing for each frame the uncompressed samples of all
+   channels.
+
+
+.. method:: aifc.rewind()
+
+   Rewind the read pointer.  The next :meth:`readframes` will start from the
+   beginning.
+
+
+.. method:: aifc.setpos(pos)
+
+   Seek to the specified frame number.
+
+
+.. method:: aifc.tell()
+
+   Return the current frame number.
+
+
+.. method:: aifc.close()
+
+   Close the AIFF file.  After calling this method, the object can no longer be
+   used.
+
+Objects returned by :func:`open` when a file is opened for writing have all the
+above methods, except for :meth:`readframes` and :meth:`setpos`.  In addition
+the following methods exist.  The :meth:`get\*` methods can only be called after
+the corresponding :meth:`set\*` methods have been called.  Before the first
+:meth:`writeframes` or :meth:`writeframesraw`, all parameters except for the
+number of frames must be filled in.
+
+
+.. method:: aifc.aiff()
+
+   Create an AIFF file.  The default is that an AIFF-C file is created, unless the
+   name of the file ends in ``'.aiff'`` in which case the default is an AIFF file.
+
+
+.. method:: aifc.aifc()
+
+   Create an AIFF-C file.  The default is that an AIFF-C file is created, unless
+   the name of the file ends in ``'.aiff'`` in which case the default is an AIFF
+   file.
+
+
+.. method:: aifc.setnchannels(nchannels)
+
+   Specify the number of channels in the audio file.
+
+
+.. method:: aifc.setsampwidth(width)
+
+   Specify the size in bytes of audio samples.
+
+
+.. method:: aifc.setframerate(rate)
+
+   Specify the sampling frequency in frames per second.
+
+
+.. method:: aifc.setnframes(nframes)
+
+   Specify the number of frames that are to be written to the audio file. If this
+   parameter is not set, or not set correctly, the file needs to support seeking.
+
+
+.. method:: aifc.setcomptype(type, name)
+
+   .. index::
+      single: u-LAW
+      single: A-LAW
+      single: G.722
+
+   Specify the compression type.  If not specified, the audio data will not be
+   compressed.  In AIFF files, compression is not possible.  The name parameter
+   should be a human-readable description of the compression type, the type
+   parameter should be a four-character string.  Currently the following
+   compression types are supported: NONE, ULAW, ALAW, G722.
+
+
+.. method:: aifc.setparams(nchannels, sampwidth, framerate, comptype, compname)
+
+   Set all the above parameters at once.  The argument is a tuple consisting of the
+   various parameters.  This means that it is possible to use the result of a
+   :meth:`getparams` call as argument to :meth:`setparams`.
+
+
+.. method:: aifc.setmark(id, pos, name)
+
+   Add a mark with the given id (larger than 0), and the given name at the given
+   position.  This method can be called at any time before :meth:`close`.
+
+
+.. method:: aifc.tell()
+
+   Return the current write position in the output file.  Useful in combination
+   with :meth:`setmark`.
+
+
+.. method:: aifc.writeframes(data)
+
+   Write data to the output file.  This method can only be called after the audio
+   file parameters have been set.
+
+
+.. method:: aifc.writeframesraw(data)
+
+   Like :meth:`writeframes`, except that the header of the audio file is not
+   updated.
+
+
+.. method:: aifc.close()
+
+   Close the AIFF file.  The header of the file is updated to reflect the actual
+   size of the audio data. After calling this method, the object can no longer be
+   used.
+

Doc/library/allos.rst

@@ -0,0 +1,27 @@
+
+.. _allos:
+
+*********************************
+Generic Operating System Services
+*********************************
+
+The modules described in this chapter provide interfaces to operating system
+features that are available on (almost) all operating systems, such as files and
+a clock.  The interfaces are generally modeled after the Unix or C interfaces,
+but they are available on most other systems as well.  Here's an overview:
+
+
+.. toctree::
+
+   os.rst
+   time.rst
+   optparse.rst
+   getopt.rst
+   logging.rst
+   getpass.rst
+   curses.rst
+   curses.ascii.rst
+   curses.panel.rst
+   platform.rst
+   errno.rst
+   ctypes.rst

Doc/library/anydbm.rst

@@ -0,0 +1,96 @@
+
+:mod:`anydbm` --- Generic access to DBM-style databases
+=======================================================
+
+.. module:: anydbm
+   :synopsis: Generic interface to DBM-style database modules.
+
+
+.. index::
+   module: dbhash
+   module: bsddb
+   module: gdbm
+   module: dbm
+   module: dumbdbm
+
+:mod:`anydbm` is a generic interface to variants of the DBM database ---
+:mod:`dbhash` (requires :mod:`bsddb`), :mod:`gdbm`, or :mod:`dbm`.  If none of
+these modules is installed, the slow-but-simple implementation in module
+:mod:`dumbdbm` will be used.
+
+
+.. function:: open(filename[, flag[, mode]])
+
+   Open the database file *filename* and return a corresponding object.
+
+   If the database file already exists, the :mod:`whichdb` module is  used to
+   determine its type and the appropriate module is used; if it does not exist, the
+   first module listed above that can be imported is used.
+
+   The optional *flag* argument can be ``'r'`` to open an existing database for
+   reading only, ``'w'`` to open an existing database for reading and writing,
+   ``'c'`` to create the database if it doesn't exist, or ``'n'``, which will
+   always create a new empty database.  If not specified, the default value is
+   ``'r'``.
+
+   The optional *mode* argument is the Unix mode of the file, used only when the
+   database has to be created.  It defaults to octal ``0666`` (and will be modified
+   by the prevailing umask).
+
+
+.. exception:: error
+
+   A tuple containing the exceptions that can be raised by each of the supported
+   modules, with a unique exception also named :exc:`anydbm.error` as the first
+   item --- the latter is used when :exc:`anydbm.error` is raised.
+
+The object returned by :func:`open` supports most of the same functionality as
+dictionaries; keys and their corresponding values can be stored, retrieved, and
+deleted, and the :meth:`has_key` and :meth:`keys` methods are available.  Keys
+and values must always be strings.
+
+The following example records some hostnames and a corresponding title,  and
+then prints out the contents of the database::
+
+   import anydbm
+
+   # Open database, creating it if necessary.
+   db = anydbm.open('cache', 'c')
+
+   # Record some values
+   db['www.python.org'] = 'Python Website'
+   db['www.cnn.com'] = 'Cable News Network'
+
+   # Loop through contents.  Other dictionary methods
+   # such as .keys(), .values() also work.
+   for k, v in db.iteritems():
+       print k, '\t', v
+
+   # Storing a non-string key or value will raise an exception (most
+   # likely a TypeError).
+   db['www.yahoo.com'] = 4
+
+   # Close when done.
+   db.close()
+
+
+.. seealso::
+
+   Module :mod:`dbhash`
+      BSD ``db`` database interface.
+
+   Module :mod:`dbm`
+      Standard Unix database interface.
+
+   Module :mod:`dumbdbm`
+      Portable implementation of the ``dbm`` interface.
+
+   Module :mod:`gdbm`
+      GNU database interface, based on the ``dbm`` interface.
+
+   Module :mod:`shelve`
+      General object persistence built on top of  the Python ``dbm`` interface.
+
+   Module :mod:`whichdb`
+      Utility module used to determine the type of an existing database.
+

Doc/library/archiving.rst

@@ -0,0 +1,18 @@
+
+.. _archiving:
+
+******************************
+Data Compression and Archiving
+******************************
+
+The modules described in this chapter support data compression with the zlib,
+gzip, and bzip2 algorithms, and  the creation of ZIP- and tar-format archives.
+
+
+.. toctree::
+
+   zlib.rst
+   gzip.rst
+   bz2.rst
+   zipfile.rst
+   tarfile.rst

Doc/library/array.rst

@@ -0,0 +1,272 @@
+
+:mod:`array` --- Efficient arrays of numeric values
+===================================================
+
+.. module:: array
+   :synopsis: Efficient arrays of uniformly typed numeric values.
+
+
+.. index:: single: arrays
+
+This module defines an object type which can efficiently represent an array of
+basic values: characters, integers, floating point numbers.  Arrays are sequence
+types and behave very much like lists, except that the type of objects stored in
+them is constrained.  The type is specified at object creation time by using a
+:dfn:`type code`, which is a single character.  The following type codes are
+defined:
+
++-----------+----------------+-------------------+-----------------------+
+| Type code | C Type         | Python Type       | Minimum size in bytes |
++===========+================+===================+=======================+
+| ``'c'``   | char           | character         | 1                     |
++-----------+----------------+-------------------+-----------------------+
+| ``'b'``   | signed char    | int               | 1                     |
++-----------+----------------+-------------------+-----------------------+
+| ``'B'``   | unsigned char  | int               | 1                     |
++-----------+----------------+-------------------+-----------------------+
+| ``'u'``   | Py_UNICODE     | Unicode character | 2                     |
++-----------+----------------+-------------------+-----------------------+
+| ``'h'``   | signed short   | int               | 2                     |
++-----------+----------------+-------------------+-----------------------+
+| ``'H'``   | unsigned short | int               | 2                     |
++-----------+----------------+-------------------+-----------------------+
+| ``'i'``   | signed int     | int               | 2                     |
++-----------+----------------+-------------------+-----------------------+
+| ``'I'``   | unsigned int   | long              | 2                     |
++-----------+----------------+-------------------+-----------------------+
+| ``'l'``   | signed long    | int               | 4                     |
++-----------+----------------+-------------------+-----------------------+
+| ``'L'``   | unsigned long  | long              | 4                     |
++-----------+----------------+-------------------+-----------------------+
+| ``'f'``   | float          | float             | 4                     |
++-----------+----------------+-------------------+-----------------------+
+| ``'d'``   | double         | float             | 8                     |
++-----------+----------------+-------------------+-----------------------+
+
+The actual representation of values is determined by the machine architecture
+(strictly speaking, by the C implementation).  The actual size can be accessed
+through the :attr:`itemsize` attribute.  The values stored  for ``'L'`` and
+``'I'`` items will be represented as Python long integers when retrieved,
+because Python's plain integer type cannot represent the full range of C's
+unsigned (long) integers.
+
+The module defines the following type:
+
+
+.. function:: array(typecode[, initializer])
+
+   Return a new array whose items are restricted by *typecode*, and initialized
+   from the optional *initializer* value, which must be a list, string, or iterable
+   over elements of the appropriate type.
+
+   .. versionchanged:: 2.4
+      Formerly, only lists or strings were accepted.
+
+   If given a list or string, the initializer is passed to the new array's
+   :meth:`fromlist`, :meth:`fromstring`, or :meth:`fromunicode` method (see below)
+   to add initial items to the array.  Otherwise, the iterable initializer is
+   passed to the :meth:`extend` method.
+
+
+.. data:: ArrayType
+
+   Obsolete alias for :func:`array`.
+
+Array objects support the ordinary sequence operations of indexing, slicing,
+concatenation, and multiplication.  When using slice assignment, the assigned
+value must be an array object with the same type code; in all other cases,
+:exc:`TypeError` is raised. Array objects also implement the buffer interface,
+and may be used wherever buffer objects are supported.
+
+The following data items and methods are also supported:
+
+
+.. attribute:: array.typecode
+
+   The typecode character used to create the array.
+
+
+.. attribute:: array.itemsize
+
+   The length in bytes of one array item in the internal representation.
+
+
+.. method:: array.append(x)
+
+   Append a new item with value *x* to the end of the array.
+
+
+.. method:: array.buffer_info()
+
+   Return a tuple ``(address, length)`` giving the current memory address and the
+   length in elements of the buffer used to hold array's contents.  The size of the
+   memory buffer in bytes can be computed as ``array.buffer_info()[1] *
+   array.itemsize``.  This is occasionally useful when working with low-level (and
+   inherently unsafe) I/O interfaces that require memory addresses, such as certain
+   :cfunc:`ioctl` operations.  The returned numbers are valid as long as the array
+   exists and no length-changing operations are applied to it.
+
+   .. note::
+
+      When using array objects from code written in C or C++ (the only way to
+      effectively make use of this information), it makes more sense to use the buffer
+      interface supported by array objects.  This method is maintained for backward
+      compatibility and should be avoided in new code.  The buffer interface is
+      documented in :ref:`bufferobjects`.
+
+
+.. method:: array.byteswap()
+
+   "Byteswap" all items of the array.  This is only supported for values which are
+   1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
+   raised.  It is useful when reading data from a file written on a machine with a
+   different byte order.
+
+
+.. method:: array.count(x)
+
+   Return the number of occurrences of *x* in the array.
+
+
+.. method:: array.extend(iterable)
+
+   Append items from *iterable* to the end of the array.  If *iterable* is another
+   array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
+   be raised.  If *iterable* is not an array, it must be iterable and its elements
+   must be the right type to be appended to the array.
+
+   .. versionchanged:: 2.4
+      Formerly, the argument could only be another array.
+
+
+.. method:: array.fromfile(f, n)
+
+   Read *n* items (as machine values) from the file object *f* and append them to
+   the end of the array.  If less than *n* items are available, :exc:`EOFError` is
+   raised, but the items that were available are still inserted into the array.
+   *f* must be a real built-in file object; something else with a :meth:`read`
+   method won't do.
+
+
+.. method:: array.fromlist(list)
+
+   Append items from the list.  This is equivalent to ``for x in list:
+   a.append(x)`` except that if there is a type error, the array is unchanged.
+
+
+.. method:: array.fromstring(s)
+
+   Appends items from the string, interpreting the string as an array of machine
+   values (as if it had been read from a file using the :meth:`fromfile` method).
+
+
+.. method:: array.fromunicode(s)
+
+   Extends this array with data from the given unicode string.  The array must
+   be a type ``'u'`` array; otherwise a :exc:`ValueError` is raised.  Use
+   ``array.fromstring(unicodestring.encode(enc))`` to append Unicode data to an
+   array of some other type.
+
+
+.. method:: array.index(x)
+
+   Return the smallest *i* such that *i* is the index of the first occurrence of
+   *x* in the array.
+
+
+.. method:: array.insert(i, x)
+
+   Insert a new item with value *x* in the array before position *i*. Negative
+   values are treated as being relative to the end of the array.
+
+
+.. method:: array.pop([i])
+
+   Removes the item with the index *i* from the array and returns it. The optional
+   argument defaults to ``-1``, so that by default the last item is removed and
+   returned.
+
+
+.. method:: array.read(f, n)
+
+   .. deprecated:: 1.5.1
+      Use the :meth:`fromfile` method.
+
+   Read *n* items (as machine values) from the file object *f* and append them to
+   the end of the array.  If less than *n* items are available, :exc:`EOFError` is
+   raised, but the items that were available are still inserted into the array.
+   *f* must be a real built-in file object; something else with a :meth:`read`
+   method won't do.
+
+
+.. method:: array.remove(x)
+
+   Remove the first occurrence of *x* from the array.
+
+
+.. method:: array.reverse()
+
+   Reverse the order of the items in the array.
+
+
+.. method:: array.tofile(f)
+
+   Write all items (as machine values) to the file object *f*.
+
+
+.. method:: array.tolist()
+
+   Convert the array to an ordinary list with the same items.
+
+
+.. method:: array.tostring()
+
+   Convert the array to an array of machine values and return the string
+   representation (the same sequence of bytes that would be written to a file by
+   the :meth:`tofile` method.)
+
+
+.. method:: array.tounicode()
+
+   Convert the array to a unicode string.  The array must be a type ``'u'`` array;
+   otherwise a :exc:`ValueError` is raised. Use ``array.tostring().decode(enc)`` to
+   obtain a unicode string from an array of some other type.
+
+
+.. method:: array.write(f)
+
+   .. deprecated:: 1.5.1
+      Use the :meth:`tofile` method.
+
+   Write all items (as machine values) to the file object *f*.
+
+When an array object is printed or converted to a string, it is represented as
+``array(typecode, initializer)``.  The *initializer* is omitted if the array is
+empty, otherwise it is a string if the *typecode* is ``'c'``, otherwise it is a
+list of numbers.  The string is guaranteed to be able to be converted back to an
+array with the same type and value using :func:`eval`, so long as the
+:func:`array` function has been imported using ``from array import array``.
+Examples::
+
+   array('l')
+   array('c', 'hello world')
+   array('u', u'hello \u2641')
+   array('l', [1, 2, 3, 4, 5])
+   array('d', [1.0, 2.0, 3.14])
+
+
+.. seealso::
+
+   Module :mod:`struct`
+      Packing and unpacking of heterogeneous binary data.
+
+   Module :mod:`xdrlib`
+      Packing and unpacking of External Data Representation (XDR) data as used in some
+      remote procedure call systems.
+
+   `The Numerical Python Manual <http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm>`_
+      The Numeric Python extension (NumPy) defines another array type; see
+      http://numpy.sourceforge.net/ for further information about Numerical Python.
+      (A PDF version of the NumPy manual is available at
+      http://numpy.sourceforge.net/numdoc/numdoc.pdf).
+

Doc/library/asynchat.rst

@@ -0,0 +1,284 @@
+
+:mod:`asynchat` --- Asynchronous socket command/response handler
+================================================================
+
+.. module:: asynchat
+   :synopsis: Support for asynchronous command/response protocols.
+.. moduleauthor:: Sam Rushing <rushing@nightmare.com>
+.. sectionauthor:: Steve Holden <sholden@holdenweb.com>
+
+
+This module builds on the :mod:`asyncore` infrastructure, simplifying
+asynchronous clients and servers and making it easier to handle protocols whose
+elements are terminated by arbitrary strings, or are of variable length.
+:mod:`asynchat` defines the abstract class :class:`async_chat` that you
+subclass, providing implementations of the :meth:`collect_incoming_data` and
+:meth:`found_terminator` methods. It uses the same asynchronous loop as
+:mod:`asyncore`, and the two types of channel, :class:`asyncore.dispatcher` and
+:class:`asynchat.async_chat`, can freely be mixed in the channel map. Typically
+an :class:`asyncore.dispatcher` server channel generates new
+:class:`asynchat.async_chat` channel objects as it receives incoming connection
+requests.
+
+
+.. class:: async_chat()
+
+   This class is an abstract subclass of :class:`asyncore.dispatcher`. To make
+   practical use of the code you must subclass :class:`async_chat`, providing
+   meaningful :meth:`collect_incoming_data` and :meth:`found_terminator` methods.
+   The :class:`asyncore.dispatcher` methods can be used, although not all make
+   sense in a message/response context.
+
+   Like :class:`asyncore.dispatcher`, :class:`async_chat` defines a set of events
+   that are generated by an analysis of socket conditions after a :cfunc:`select`
+   call. Once the polling loop has been started the :class:`async_chat` object's
+   methods are called by the event-processing framework with no action on the part
+   of the programmer.
+
+   Unlike :class:`asyncore.dispatcher`, :class:`async_chat` allows you to define a
+   first-in-first-out queue (fifo) of *producers*. A producer need have only one
+   method, :meth:`more`, which should return data to be transmitted on the channel.
+   The producer indicates exhaustion (*i.e.* that it contains no more data) by
+   having its :meth:`more` method return the empty string. At this point the
+   :class:`async_chat` object removes the producer from the fifo and starts using
+   the next producer, if any. When the producer fifo is empty the
+   :meth:`handle_write` method does nothing. You use the channel object's
+   :meth:`set_terminator` method to describe how to recognize the end of, or an
+   important breakpoint in, an incoming transmission from the remote endpoint.
+
+   To build a functioning :class:`async_chat` subclass your  input methods
+   :meth:`collect_incoming_data` and :meth:`found_terminator` must handle the data
+   that the channel receives asynchronously. The methods are described below.
+
+
+.. method:: async_chat.close_when_done()
+
+   Pushes a ``None`` on to the producer fifo. When this producer is popped off the
+   fifo it causes the channel to be closed.
+
+
+.. method:: async_chat.collect_incoming_data(data)
+
+   Called with *data* holding an arbitrary amount of received data. The default
+   method, which must be overridden, raises a :exc:`NotImplementedError` exception.
+
+
+.. method:: async_chat.discard_buffers()
+
+   In emergencies this method will discard any data held in the input and/or output
+   buffers and the producer fifo.
+
+
+.. method:: async_chat.found_terminator()
+
+   Called when the incoming data stream  matches the termination condition set by
+   :meth:`set_terminator`. The default method, which must be overridden, raises a
+   :exc:`NotImplementedError` exception. The buffered input data should be
+   available via an instance attribute.
+
+
+.. method:: async_chat.get_terminator()
+
+   Returns the current terminator for the channel.
+
+
+.. method:: async_chat.handle_close()
+
+   Called when the channel is closed. The default method silently closes the
+   channel's socket.
+
+
+.. method:: async_chat.handle_read()
+
+   Called when a read event fires on the channel's socket in the asynchronous loop.
+   The default method checks for the termination condition established by
+   :meth:`set_terminator`, which can be either the appearance of a particular
+   string in the input stream or the receipt of a particular number of characters.
+   When the terminator is found, :meth:`handle_read` calls the
+   :meth:`found_terminator` method after calling :meth:`collect_incoming_data` with
+   any data preceding the terminating condition.
+
+
+.. method:: async_chat.handle_write()
+
+   Called when the application may write data to the channel.   The default method
+   calls the :meth:`initiate_send` method, which in turn will call
+   :meth:`refill_buffer` to collect data from the producer fifo associated with the
+   channel.
+
+
+.. method:: async_chat.push(data)
+
+   Creates a :class:`simple_producer` object (*see below*) containing the data and
+   pushes it on to the channel's ``producer_fifo`` to ensure its transmission. This
+   is all you need to do to have the channel write the data out to the network,
+   although it is possible to use your own producers in more complex schemes to
+   implement encryption and chunking, for example.
+
+
+.. method:: async_chat.push_with_producer(producer)
+
+   Takes a producer object and adds it to the producer fifo associated with the
+   channel. When all currently-pushed producers have been exhausted the channel
+   will consume this producer's data by calling its :meth:`more` method and send
+   the data to the remote endpoint.
+
+
+.. method:: async_chat.readable()
+
+   Should return ``True`` for the channel to be included in the set of channels
+   tested by the :cfunc:`select` loop for readability.
+
+
+.. method:: async_chat.refill_buffer()
+
+   Refills the output buffer by calling the :meth:`more` method of the producer at
+   the head of the fifo. If it is exhausted then the producer is popped off the
+   fifo and the next producer is activated. If the current producer is, or becomes,
+   ``None`` then the channel is closed.
+
+
+.. method:: async_chat.set_terminator(term)
+
+   Sets the terminating condition to be recognised on the channel. ``term`` may be
+   any of three types of value, corresponding to three different ways to handle
+   incoming protocol data.
+
+   +-----------+---------------------------------------------+
+   | term      | Description                                 |
+   +===========+=============================================+
+   | *string*  | Will call :meth:`found_terminator` when the |
+   |           | string is found in the input stream         |
+   +-----------+---------------------------------------------+
+   | *integer* | Will call :meth:`found_terminator` when the |
+   |           | indicated number of characters have been    |
+   |           | received                                    |
+   +-----------+---------------------------------------------+
+   | ``None``  | The channel continues to collect data       |
+   |           | forever                                     |
+   +-----------+---------------------------------------------+
+
+   Note that any data following the terminator will be available for reading by the
+   channel after :meth:`found_terminator` is called.
+
+
+.. method:: async_chat.writable()
+
+   Should return ``True`` as long as items remain on the producer fifo, or the
+   channel is connected and the channel's output buffer is non-empty.
+
+
+asynchat - Auxiliary Classes and Functions
+------------------------------------------
+
+
+.. class:: simple_producer(data[, buffer_size=512])
+
+   A :class:`simple_producer` takes a chunk of data and an optional buffer size.
+   Repeated calls to its :meth:`more` method yield successive chunks of the data no
+   larger than *buffer_size*.
+
+
+.. method:: simple_producer.more()
+
+   Produces the next chunk of information from the producer, or returns the empty
+   string.
+
+
+.. class:: fifo([list=None])
+
+   Each channel maintains a :class:`fifo` holding data which has been pushed by the
+   application but not yet popped for writing to the channel. A :class:`fifo` is a
+   list used to hold data and/or producers until they are required. If the *list*
+   argument is provided then it should contain producers or data items to be
+   written to the channel.
+
+
+.. method:: fifo.is_empty()
+
+   Returns ``True`` iff the fifo is empty.
+
+
+.. method:: fifo.first()
+
+   Returns the least-recently :meth:`push`\ ed item from the fifo.
+
+
+.. method:: fifo.push(data)
+
+   Adds the given data (which may be a string or a producer object) to the producer
+   fifo.
+
+
+.. method:: fifo.pop()
+
+   If the fifo is not empty, returns ``True, first()``, deleting the popped item.
+   Returns ``False, None`` for an empty fifo.
+
+The :mod:`asynchat` module also defines one utility function, which may be of
+use in network and textual analysis operations.
+
+
+.. function:: find_prefix_at_end(haystack, needle)
+
+   Returns ``True`` if string *haystack* ends with any non-empty prefix of string
+   *needle*.
+
+
+.. _asynchat-example:
+
+asynchat Example
+----------------
+
+The following partial example shows how HTTP requests can be read with
+:class:`async_chat`. A web server might create an :class:`http_request_handler`
+object for each incoming client connection. Notice that initially the channel
+terminator is set to match the blank line at the end of the HTTP headers, and a
+flag indicates that the headers are being read.
+
+Once the headers have been read, if the request is of type POST (indicating that
+further data are present in the input stream) then the ``Content-Length:``
+header is used to set a numeric terminator to read the right amount of data from
+the channel.
+
+The :meth:`handle_request` method is called once all relevant input has been
+marshalled, after setting the channel terminator to ``None`` to ensure that any
+extraneous data sent by the web client are ignored. ::
+
+   class http_request_handler(asynchat.async_chat):
+
+       def __init__(self, conn, addr, sessions, log):
+           asynchat.async_chat.__init__(self, conn=conn)
+           self.addr = addr
+           self.sessions = sessions
+           self.ibuffer = []
+           self.obuffer = ""
+           self.set_terminator("\r\n\r\n")
+           self.reading_headers = True
+           self.handling = False
+           self.cgi_data = None
+           self.log = log
+
+       def collect_incoming_data(self, data):
+           """Buffer the data"""
+           self.ibuffer.append(data)
+
+       def found_terminator(self):
+           if self.reading_headers:
+               self.reading_headers = False
+               self.parse_headers("".join(self.ibuffer))
+               self.ibuffer = []
+               if self.op.upper() == "POST":
+                   clen = self.headers.getheader("content-length")
+                   self.set_terminator(int(clen))
+               else:
+                   self.handling = True
+                   self.set_terminator(None)
+                   self.handle_request()
+           elif not self.handling:
+               self.set_terminator(None) # browsers sometimes over-send
+               self.cgi_data = parse(self.headers, "".join(self.ibuffer))
+               self.handling = True
+               self.ibuffer = []
+               self.handle_request()
+

Doc/library/asyncore.rst

@@ -0,0 +1,269 @@
+
+:mod:`asyncore` --- Asynchronous socket handler
+===============================================
+
+.. module:: asyncore
+   :synopsis: A base class for developing asynchronous socket  handling services.
+.. moduleauthor:: Sam Rushing <rushing@nightmare.com>
+.. sectionauthor:: Christopher Petrilli <petrilli@amber.org>
+.. sectionauthor:: Steve Holden <sholden@holdenweb.com>
+
+
+This module provides the basic infrastructure for writing asynchronous  socket
+service clients and servers.
+
+.. % Heavily adapted from original documentation by Sam Rushing.
+
+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 processor bound, then pre-emptive scheduled threads
+are probably what  you really need. Network servers are rarely processor bound,
+however.
+
+If your operating system supports the :cfunc:`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 :mod:`asyncore` module solves many of the
+difficult problems for you, making the task of building sophisticated
+high-performance network servers and clients a snap. For "conversational"
+applications and protocols the companion :mod:`asynchat` module is invaluable.
+
+The basic idea behind both modules is to create one or more network *channels*,
+instances of class :class:`asyncore.dispatcher` and
+:class:`asynchat.async_chat`. Creating the channels adds them to a global map,
+used by the :func:`loop` function if you do not provide it with your own *map*.
+
+Once the initial channel(s) is(are) created, calling the :func:`loop` function
+activates channel service, which continues until the last channel (including any
+that have been added to the map during asynchronous service) is closed.
+
+
+.. function:: loop([timeout[, use_poll[, map[,count]]]])
+
+   Enter a polling loop that terminates after count passes or all open channels
+   have been closed.  All arguments are optional.  The *count* parameter defaults
+   to None, resulting in the loop terminating only when all channels have been
+   closed.  The *timeout* argument sets the timeout parameter for the appropriate
+   :func:`select` or :func:`poll` call, measured in seconds; the default is 30
+   seconds. The *use_poll* parameter, if true, indicates that :func:`poll` should
+   be used in preference to :func:`select` (the default is ``False``).
+
+   The *map* parameter is a dictionary whose items are the channels to watch.  As
+   channels are closed they are deleted from their map.  If *map* is omitted, a
+   global map is used. Channels (instances of :class:`asyncore.dispatcher`,
+   :class:`asynchat.async_chat` and subclasses thereof) can freely be mixed in the
+   map.
+
+
+.. class:: dispatcher()
+
+   The :class:`dispatcher` class is a thin wrapper around a low-level socket
+   object. To make it more useful, it has a few methods for event-handling  which
+   are called from the asynchronous loop.   Otherwise, it can be treated as a
+   normal non-blocking socket object.
+
+   Two class attributes can be modified, to improve performance, or possibly even
+   to conserve memory.
+
+
+   .. data:: ac_in_buffer_size
+
+      The asynchronous input buffer size (default ``4096``).
+
+
+   .. data:: ac_out_buffer_size
+
+      The asynchronous output buffer size (default ``4096``).
+
+   The firing of low-level events at certain times or in certain connection states
+   tells the asynchronous loop that certain higher-level events have taken place.
+   For example, if we have asked for a socket to connect to another host, we know
+   that the connection has been made when the socket becomes writable for the first
+   time (at this point you know that you may write to it with the expectation of
+   success). The implied higher-level events are:
+
+   +----------------------+----------------------------------------+
+   | Event                | Description                            |
+   +======================+========================================+
+   | ``handle_connect()`` | Implied by the first write event       |
+   +----------------------+----------------------------------------+
+   | ``handle_close()``   | Implied by a read event with no data   |
+   |                      | available                              |
+   +----------------------+----------------------------------------+
+   | ``handle_accept()``  | Implied by a read event on a listening |
+   |                      | socket                                 |
+   +----------------------+----------------------------------------+
+
+   During asynchronous processing, each mapped channel's :meth:`readable` and
+   :meth:`writable` methods are used to determine whether the channel's socket
+   should be added to the list of channels :cfunc:`select`\ ed or :cfunc:`poll`\ ed
+   for read and write events.
+
+Thus, the set of channel events is larger than the basic socket events. The full
+set of methods that can be overridden in your subclass follows:
+
+
+.. method:: dispatcher.handle_read()
+
+   Called when the asynchronous loop detects that a :meth:`read` call on the
+   channel's socket will succeed.
+
+
+.. method:: dispatcher.handle_write()
+
+   Called when the asynchronous loop detects that a writable socket can be written.
+   Often this method will implement the necessary buffering for  performance.  For
+   example::
+
+      def handle_write(self):
+          sent = self.send(self.buffer)
+          self.buffer = self.buffer[sent:]
+
+
+.. method:: dispatcher.handle_expt()
+
+   Called when there is out of band (OOB) data for a socket  connection.  This will
+   almost never happen, as OOB is  tenuously supported and rarely used.
+
+
+.. method:: dispatcher.handle_connect()
+
+   Called when the active opener's socket actually makes a connection. Might send a
+   "welcome" banner, or initiate a protocol negotiation with the remote endpoint,
+   for example.
+
+
+.. method:: dispatcher.handle_close()
+
+   Called when the socket is closed.
+
+
+.. method:: dispatcher.handle_error()
+
+   Called when an exception is raised and not otherwise handled.  The default
+   version prints a condensed traceback.
+
+
+.. method:: dispatcher.handle_accept()
+
+   Called on listening channels (passive openers) when a   connection can be
+   established with a new remote endpoint that has issued a :meth:`connect` call
+   for the local endpoint.
+
+
+.. method:: dispatcher.readable()
+
+   Called each time around the asynchronous loop to determine whether a channel's
+   socket should be added to the list on which read events can occur.  The default
+   method simply returns ``True``,  indicating that by default, all channels will
+   be interested in read events.
+
+
+.. method:: dispatcher.writable()
+
+   Called each time around the asynchronous loop to determine whether a channel's
+   socket should be added to the list on which write events can occur.  The default
+   method simply returns ``True``,  indicating that by default, all channels will
+   be interested in write events.
+
+In addition, each channel delegates or extends many of the socket methods. Most
+of these are nearly identical to their socket partners.
+
+
+.. method:: dispatcher.create_socket(family, type)
+
+   This is identical to the creation of a normal socket, and  will use the same
+   options for creation.  Refer to the :mod:`socket` documentation for information
+   on creating sockets.
+
+
+.. method:: dispatcher.connect(address)
+
+   As with the normal socket object, *address* is a  tuple with the first element
+   the host to connect to, and the  second the port number.
+
+
+.. method:: dispatcher.send(data)
+
+   Send *data* to the remote end-point of the socket.
+
+
+.. method:: dispatcher.recv(buffer_size)
+
+   Read at most *buffer_size* bytes from the socket's remote end-point. An empty
+   string implies that the channel has been closed from the other end.
+
+
+.. method:: dispatcher.listen(backlog)
+
+   Listen for connections made to the socket.  The *backlog* argument specifies the
+   maximum number of queued connections and should be at least 1; the maximum value
+   is system-dependent (usually 5).
+
+
+.. method:: dispatcher.bind(address)
+
+   Bind the socket to *address*.  The socket must not already be bound.  (The
+   format of *address* depends on the address family --- see above.)  To mark the
+   socket as re-usable (setting the :const:`SO_REUSEADDR` option), call the
+   :class:`dispatcher` object's :meth:`set_reuse_addr` method.
+
+
+.. method:: dispatcher.accept()
+
+   Accept a connection.  The socket must be bound to an address and listening for
+   connections.  The return value is a pair ``(conn, address)`` where *conn* is a
+   *new* socket object usable to send and receive data on the connection, and
+   *address* is the address bound to the socket on the other end of the connection.
+
+
+.. method:: dispatcher.close()
+
+   Close the socket.  All future operations on the socket object will fail.  The
+   remote end-point will receive no more data (after queued data is flushed).
+   Sockets are automatically closed when they are garbage-collected.
+
+
+.. _asyncore-example:
+
+asyncore Example basic HTTP client
+----------------------------------
+
+Here is a very basic HTTP client that uses the :class:`dispatcher` class to
+implement its socket handling::
+
+   import asyncore, socket
+
+   class http_client(asyncore.dispatcher):
+
+       def __init__(self, host, path):
+           asyncore.dispatcher.__init__(self)
+           self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
+           self.connect( (host, 80) )
+           self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % path
+
+       def handle_connect(self):
+           pass
+
+       def handle_close(self):
+           self.close()
+
+       def handle_read(self):
+           print self.recv(8192)
+
+       def writable(self):
+           return (len(self.buffer) > 0)
+
+       def handle_write(self):
+           sent = self.send(self.buffer)
+           self.buffer = self.buffer[sent:]
+
+   c = http_client('www.python.org', '/')
+
+   asyncore.loop()
+

Doc/library/atexit.rst

@@ -0,0 +1,105 @@
+
+:mod:`atexit` --- Exit handlers
+===============================
+
+.. module:: atexit
+   :synopsis: Register and execute cleanup functions.
+.. moduleauthor:: Skip Montanaro <skip@mojam.com>
+.. sectionauthor:: Skip Montanaro <skip@mojam.com>
+
+
+.. versionadded:: 2.0
+
+The :mod:`atexit` module defines functions to register and unregister cleanup
+functions.  Functions thus registered are automatically executed upon normal
+interpreter termination.
+
+Note: the functions registered via this module are not called when the program
+is killed by a signal, when a Python fatal internal error is detected, or when
+:func:`os._exit` is called.
+
+
+.. function:: register(func[, *args[, **kargs]])
+
+   Register *func* as a function to be executed at termination.  Any optional
+   arguments that are to be passed to *func* must be passed as arguments to
+   :func:`register`.
+
+   At normal program termination (for instance, if :func:`sys.exit` is called or
+   the main module's execution completes), all functions registered are called in
+   last in, first out order.  The assumption is that lower level modules will
+   normally be imported before higher level modules and thus must be cleaned up
+   later.
+
+   If an exception is raised during execution of the exit handlers, a traceback is
+   printed (unless :exc:`SystemExit` is raised) and the exception information is
+   saved.  After all exit handlers have had a chance to run the last exception to
+   be raised is re-raised.
+
+   .. versionchanged:: 2.6
+      This function now returns *func* which makes it possible to use it as a
+      decorator without binding the original name to ``None``.
+
+
+.. function:: unregister(func)
+
+   Remove a function *func* from the list of functions to be run at interpreter-
+   shutdown.  After calling :func:`unregister`, *func* is guaranteed not to be
+   called when the interpreter shuts down.
+
+   .. versionadded:: 3.0
+
+
+.. seealso::
+
+   Module :mod:`readline`
+      Useful example of :mod:`atexit` to read and write :mod:`readline` history files.
+
+
+.. _atexit-example:
+
+:mod:`atexit` Example
+---------------------
+
+The following simple example demonstrates how a module can initialize a counter
+from a file when it is imported and save the counter's updated value
+automatically when the program terminates without relying on the application
+making an explicit call into this module at termination. ::
+
+   try:
+       _count = int(open("/tmp/counter").read())
+   except IOError:
+       _count = 0
+
+   def incrcounter(n):
+       global _count
+       _count = _count + n
+
+   def savecounter():
+       open("/tmp/counter", "w").write("%d" % _count)
+
+   import atexit
+   atexit.register(savecounter)
+
+Positional and keyword arguments may also be passed to :func:`register` to be
+passed along to the registered function when it is called::
+
+   def goodbye(name, adjective):
+       print 'Goodbye, %s, it was %s to meet you.' % (name, adjective)
+
+   import atexit
+   atexit.register(goodbye, 'Donny', 'nice')
+
+   # or:
+   atexit.register(goodbye, adjective='nice', name='Donny')
+
+Usage as a decorator::
+
+   import atexit
+
+   @atexit.register
+   def goodbye():
+       print "You are now leaving the Python sector."
+
+This obviously only works with functions that don't take arguments.
+

Doc/library/audioop.rst

@@ -0,0 +1,261 @@
+
+:mod:`audioop` --- Manipulate raw audio data
+============================================
+
+.. module:: audioop
+   :synopsis: Manipulate raw audio data.
+
+
+The :mod:`audioop` module contains some useful operations on sound fragments.
+It operates on sound fragments consisting of signed integer samples 8, 16 or 32
+bits wide, stored in Python strings.  All scalar items are integers, unless
+specified otherwise.
+
+.. index::
+   single: Intel/DVI ADPCM
+   single: ADPCM, Intel/DVI
+   single: a-LAW
+   single: u-LAW
+
+This module provides support for a-LAW, u-LAW and Intel/DVI ADPCM encodings.
+
+.. % This para is mostly here to provide an excuse for the index entries...
+
+A few of the more complicated operations only take 16-bit samples, otherwise the
+sample size (in bytes) is always a parameter of the operation.
+
+The module defines the following variables and functions:
+
+
+.. exception:: error
+
+   This exception is raised on all errors, such as unknown number of bytes per
+   sample, etc.
+
+
+.. function:: add(fragment1, fragment2, width)
+
+   Return a fragment which is the addition of the two samples passed as parameters.
+   *width* is the sample width in bytes, either ``1``, ``2`` or ``4``.  Both
+   fragments should have the same length.
+
+
+.. function:: adpcm2lin(adpcmfragment, width, state)
+
+   Decode an Intel/DVI ADPCM coded fragment to a linear fragment.  See the
+   description of :func:`lin2adpcm` for details on ADPCM coding. Return a tuple
+   ``(sample, newstate)`` where the sample has the width specified in *width*.
+
+
+.. function:: alaw2lin(fragment, width)
+
+   Convert sound fragments in a-LAW encoding to linearly encoded sound fragments.
+   a-LAW encoding always uses 8 bits samples, so *width* refers only to the sample
+   width of the output fragment here.
+
+   .. versionadded:: 2.5
+
+
+.. function:: avg(fragment, width)
+
+   Return the average over all samples in the fragment.
+
+
+.. function:: avgpp(fragment, width)
+
+   Return the average peak-peak value over all samples in the fragment. No
+   filtering is done, so the usefulness of this routine is questionable.
+
+
+.. function:: bias(fragment, width, bias)
+
+   Return a fragment that is the original fragment with a bias added to each
+   sample.
+
+
+.. function:: cross(fragment, width)
+
+   Return the number of zero crossings in the fragment passed as an argument.
+
+
+.. function:: findfactor(fragment, reference)
+
+   Return a factor *F* such that ``rms(add(fragment, mul(reference, -F)))`` is
+   minimal, i.e., return the factor with which you should multiply *reference* to
+   make it match as well as possible to *fragment*.  The fragments should both
+   contain 2-byte samples.
+
+   The time taken by this routine is proportional to ``len(fragment)``.
+
+
+.. function:: findfit(fragment, reference)
+
+   Try to match *reference* as well as possible to a portion of *fragment* (which
+   should be the longer fragment).  This is (conceptually) done by taking slices
+   out of *fragment*, using :func:`findfactor` to compute the best match, and
+   minimizing the result.  The fragments should both contain 2-byte samples.
+   Return a tuple ``(offset, factor)`` where *offset* is the (integer) offset into
+   *fragment* where the optimal match started and *factor* is the (floating-point)
+   factor as per :func:`findfactor`.
+
+
+.. function:: findmax(fragment, length)
+
+   Search *fragment* for a slice of length *length* samples (not bytes!) with
+   maximum energy, i.e., return *i* for which ``rms(fragment[i*2:(i+length)*2])``
+   is maximal.  The fragments should both contain 2-byte samples.
+
+   The routine takes time proportional to ``len(fragment)``.
+
+
+.. function:: getsample(fragment, width, index)
+
+   Return the value of sample *index* from the fragment.
+
+
+.. function:: lin2adpcm(fragment, width, state)
+
+   Convert samples to 4 bit Intel/DVI ADPCM encoding.  ADPCM coding is an adaptive
+   coding scheme, whereby each 4 bit number is the difference between one sample
+   and the next, divided by a (varying) step.  The Intel/DVI ADPCM algorithm has
+   been selected for use by the IMA, so it may well become a standard.
+
+   *state* is a tuple containing the state of the coder.  The coder returns a tuple
+   ``(adpcmfrag, newstate)``, and the *newstate* should be passed to the next call
+   of :func:`lin2adpcm`.  In the initial call, ``None`` can be passed as the state.
+   *adpcmfrag* is the ADPCM coded fragment packed 2 4-bit values per byte.
+
+
+.. function:: lin2alaw(fragment, width)
+
+   Convert samples in the audio fragment to a-LAW encoding and return this as a
+   Python string.  a-LAW is an audio encoding format whereby you get a dynamic
+   range of about 13 bits using only 8 bit samples.  It is used by the Sun audio
+   hardware, among others.
+
+   .. versionadded:: 2.5
+
+
+.. function:: lin2lin(fragment, width, newwidth)
+
+   Convert samples between 1-, 2- and 4-byte formats.
+
+
+.. function:: lin2ulaw(fragment, width)
+
+   Convert samples in the audio fragment to u-LAW encoding and return this as a
+   Python string.  u-LAW is an audio encoding format whereby you get a dynamic
+   range of about 14 bits using only 8 bit samples.  It is used by the Sun audio
+   hardware, among others.
+
+
+.. function:: minmax(fragment, width)
+
+   Return a tuple consisting of the minimum and maximum values of all samples in
+   the sound fragment.
+
+
+.. function:: max(fragment, width)
+
+   Return the maximum of the *absolute value* of all samples in a fragment.
+
+
+.. function:: maxpp(fragment, width)
+
+   Return the maximum peak-peak value in the sound fragment.
+
+
+.. function:: mul(fragment, width, factor)
+
+   Return a fragment that has all samples in the original fragment multiplied by
+   the floating-point value *factor*.  Overflow is silently ignored.
+
+
+.. function:: ratecv(fragment, width, nchannels, inrate, outrate, state[, weightA[, weightB]])
+
+   Convert the frame rate of the input fragment.
+
+   *state* is a tuple containing the state of the converter.  The converter returns
+   a tuple ``(newfragment, newstate)``, and *newstate* should be passed to the next
+   call of :func:`ratecv`.  The initial call should pass ``None`` as the state.
+
+   The *weightA* and *weightB* arguments are parameters for a simple digital filter
+   and default to ``1`` and ``0`` respectively.
+
+
+.. function:: reverse(fragment, width)
+
+   Reverse the samples in a fragment and returns the modified fragment.
+
+
+.. function:: rms(fragment, width)
+
+   Return the root-mean-square of the fragment, i.e. ``sqrt(sum(S_i^2)/n)``.
+
+   This is a measure of the power in an audio signal.
+
+
+.. function:: tomono(fragment, width, lfactor, rfactor)
+
+   Convert a stereo fragment to a mono fragment.  The left channel is multiplied by
+   *lfactor* and the right channel by *rfactor* before adding the two channels to
+   give a mono signal.
+
+
+.. function:: tostereo(fragment, width, lfactor, rfactor)
+
+   Generate a stereo fragment from a mono fragment.  Each pair of samples in the
+   stereo fragment are computed from the mono sample, whereby left channel samples
+   are multiplied by *lfactor* and right channel samples by *rfactor*.
+
+
+.. function:: ulaw2lin(fragment, width)
+
+   Convert sound fragments in u-LAW encoding to linearly encoded sound fragments.
+   u-LAW encoding always uses 8 bits samples, so *width* refers only to the sample
+   width of the output fragment here.
+
+Note that operations such as :func:`mul` or :func:`max` make no distinction
+between mono and stereo fragments, i.e. all samples are treated equal.  If this
+is a problem the stereo fragment should be split into two mono fragments first
+and recombined later.  Here is an example of how to do that::
+
+   def mul_stereo(sample, width, lfactor, rfactor):
+       lsample = audioop.tomono(sample, width, 1, 0)
+       rsample = audioop.tomono(sample, width, 0, 1)
+       lsample = audioop.mul(sample, width, lfactor)
+       rsample = audioop.mul(sample, width, rfactor)
+       lsample = audioop.tostereo(lsample, width, 1, 0)
+       rsample = audioop.tostereo(rsample, width, 0, 1)
+       return audioop.add(lsample, rsample, width)
+
+If you use the ADPCM coder to build network packets and you want your protocol
+to be stateless (i.e. to be able to tolerate packet loss) you should not only
+transmit the data but also the state.  Note that you should send the *initial*
+state (the one you passed to :func:`lin2adpcm`) along to the decoder, not the
+final state (as returned by the coder).  If you want to use
+:func:`struct.struct` to store the state in binary you can code the first
+element (the predicted value) in 16 bits and the second (the delta index) in 8.
+
+The ADPCM coders have never been tried against other ADPCM coders, only against
+themselves.  It could well be that I misinterpreted the standards in which case
+they will not be interoperable with the respective standards.
+
+The :func:`find\*` routines might look a bit funny at first sight. They are
+primarily meant to do echo cancellation.  A reasonably fast way to do this is to
+pick the most energetic piece of the output sample, locate that in the input
+sample and subtract the whole output sample from the input sample::
+
+   def echocancel(outputdata, inputdata):
+       pos = audioop.findmax(outputdata, 800)    # one tenth second
+       out_test = outputdata[pos*2:]
+       in_test = inputdata[pos*2:]
+       ipos, factor = audioop.findfit(in_test, out_test)
+       # Optional (for better cancellation):
+       # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)], 
+       #              out_test)
+       prefill = '\0'*(pos+ipos)*2
+       postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
+       outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
+       return audioop.add(inputdata, outputdata, 2)
+

Doc/library/autogil.rst

@@ -0,0 +1,30 @@
+
+:mod:`autoGIL` --- Global Interpreter Lock handling in event loops
+==================================================================
+
+.. module:: autoGIL
+   :platform: Mac
+   :synopsis: Global Interpreter Lock handling in event loops.
+.. moduleauthor:: Just van Rossum <just@letterror.com>
+
+
+The :mod:`autoGIL` module provides a function :func:`installAutoGIL` that
+automatically locks and unlocks Python's Global Interpreter Lock when running an
+event loop.
+
+
+.. exception:: AutoGILError
+
+   Raised if the observer callback cannot be installed, for example because the
+   current thread does not have a run loop.
+
+
+.. function:: installAutoGIL()
+
+   Install an observer callback in the event loop (CFRunLoop) for the current
+   thread, that will lock and unlock the Global Interpreter Lock (GIL) at
+   appropriate times, allowing other Python threads to run while the event loop is
+   idle.
+
+   Availability: OSX 10.1 or later.
+

Doc/library/base64.rst

@@ -0,0 +1,172 @@
+
+:mod:`base64` --- RFC 3548: Base16, Base32, Base64 Data Encodings
+=================================================================
+
+.. module:: base64
+   :synopsis: RFC 3548: Base16, Base32, Base64 Data Encodings
+
+
+.. index::
+   pair: base64; encoding
+   single: MIME; base64 encoding
+
+This module provides data encoding and decoding as specified in :rfc:`3548`.
+This standard defines the Base16, Base32, and Base64 algorithms for encoding and
+decoding arbitrary binary strings into text strings that can be safely sent by
+email, used as parts of URLs, or included as part of an HTTP POST request.  The
+encoding algorithm is not the same as the :program:`uuencode` program.
+
+There are two interfaces provided by this module.  The modern interface supports
+encoding and decoding string objects using all three alphabets.  The legacy
+interface provides for encoding and decoding to and from file-like objects as
+well as strings, but only using the Base64 standard alphabet.
+
+The modern interface, which was introduced in Python 2.4, provides:
+
+
+.. function:: b64encode(s[, altchars])
+
+   Encode a string use Base64.
+
+   *s* is the string to encode.  Optional *altchars* must be a string of at least
+   length 2 (additional characters are ignored) which specifies an alternative
+   alphabet for the ``+`` and ``/`` characters.  This allows an application to e.g.
+   generate URL or filesystem safe Base64 strings.  The default is ``None``, for
+   which the standard Base64 alphabet is used.
+
+   The encoded string is returned.
+
+
+.. function:: b64decode(s[, altchars])
+
+   Decode a Base64 encoded string.
+
+   *s* is the string to decode.  Optional *altchars* must be a string of at least
+   length 2 (additional characters are ignored) which specifies the alternative
+   alphabet used instead of the ``+`` and ``/`` characters.
+
+   The decoded string is returned.  A :exc:`TypeError` is raised if *s* were
+   incorrectly padded or if there are non-alphabet characters present in the
+   string.
+
+
+.. function:: standard_b64encode(s)
+
+   Encode string *s* using the standard Base64 alphabet.
+
+
+.. function:: standard_b64decode(s)
+
+   Decode string *s* using the standard Base64 alphabet.
+
+
+.. function:: urlsafe_b64encode(s)
+
+   Encode string *s* using a URL-safe alphabet, which substitutes ``-`` instead of
+   ``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet.
+
+
+.. function:: urlsafe_b64decode(s)
+
+   Decode string *s* using a URL-safe alphabet, which substitutes ``-`` instead of
+   ``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet.
+
+
+.. function:: b32encode(s)
+
+   Encode a string using Base32.  *s* is the string to encode.  The encoded string
+   is returned.
+
+
+.. function:: b32decode(s[, casefold[, map01]])
+
+   Decode a Base32 encoded string.
+
+   *s* is the string to decode.  Optional *casefold* is a flag specifying whether a
+   lowercase alphabet is acceptable as input.  For security purposes, the default
+   is ``False``.
+
+   :rfc:`3548` allows for optional mapping of the digit 0 (zero) to the letter O
+   (oh), and for optional mapping of the digit 1 (one) to either the letter I (eye)
+   or letter L (el).  The optional argument *map01* when not ``None``, specifies
+   which letter the digit 1 should be mapped to (when *map01* is not ``None``, the
+   digit 0 is always mapped to the letter O).  For security purposes the default is
+   ``None``, so that 0 and 1 are not allowed in the input.
+
+   The decoded string is returned.  A :exc:`TypeError` is raised if *s* were
+   incorrectly padded or if there are non-alphabet characters present in the
+   string.
+
+
+.. function:: b16encode(s)
+
+   Encode a string using Base16.
+
+   *s* is the string to encode.  The encoded string is returned.
+
+
+.. function:: b16decode(s[, casefold])
+
+   Decode a Base16 encoded string.
+
+   *s* is the string to decode.  Optional *casefold* is a flag specifying whether a
+   lowercase alphabet is acceptable as input.  For security purposes, the default
+   is ``False``.
+
+   The decoded string is returned.  A :exc:`TypeError` is raised if *s* were
+   incorrectly padded or if there are non-alphabet characters present in the
+   string.
+
+The legacy interface:
+
+
+.. function:: decode(input, output)
+
+   Decode the contents of the *input* file and write the resulting binary data to
+   the *output* file. *input* and *output* must either be file objects or objects
+   that mimic the file object interface. *input* will be read until
+   ``input.read()`` returns an empty string.
+
+
+.. function:: decodestring(s)
+
+   Decode the string *s*, which must contain one or more lines of base64 encoded
+   data, and return a string containing the resulting binary data.
+
+
+.. function:: encode(input, output)
+
+   Encode the contents of the *input* file and write the resulting base64 encoded
+   data to the *output* file. *input* and *output* must either be file objects or
+   objects that mimic the file object interface. *input* will be read until
+   ``input.read()`` returns an empty string.  :func:`encode` returns the encoded
+   data plus a trailing newline character (``'\n'``).
+
+
+.. function:: encodestring(s)
+
+   Encode the string *s*, which can contain arbitrary binary data, and return a
+   string containing one or more lines of base64-encoded data.
+   :func:`encodestring` returns a string containing one or more lines of
+   base64-encoded data always including an extra trailing newline (``'\n'``).
+
+An example usage of the module::
+
+   >>> import base64
+   >>> encoded = base64.b64encode('data to be encoded')
+   >>> encoded
+   'ZGF0YSB0byBiZSBlbmNvZGVk'
+   >>> data = base64.b64decode(encoded)
+   >>> data
+   'data to be encoded'
+
+
+.. seealso::
+
+   Module :mod:`binascii`
+      Support module containing ASCII-to-binary and binary-to-ASCII conversions.
+
+   :rfc:`1521` - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies
+      Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the
+      base64 encoding.
+

Doc/library/basehttpserver.rst

@@ -0,0 +1,254 @@
+
+:mod:`BaseHTTPServer` --- Basic HTTP server
+===========================================
+
+.. module:: BaseHTTPServer
+   :synopsis: Basic HTTP server (base class for SimpleHTTPServer and CGIHTTPServer).
+
+
+.. index::
+   pair: WWW; server
+   pair: HTTP; protocol
+   single: URL
+   single: httpd
+
+.. index::
+   module: SimpleHTTPServer
+   module: CGIHTTPServer
+
+This module defines two classes for implementing HTTP servers (Web servers).
+Usually, this module isn't used directly, but is used as a basis for building
+functioning Web servers. See the :mod:`SimpleHTTPServer` and
+:mod:`CGIHTTPServer` modules.
+
+The first class, :class:`HTTPServer`, is a :class:`SocketServer.TCPServer`
+subclass.  It creates and listens at the HTTP socket, dispatching the requests
+to a handler.  Code to create and run the server looks like this::
+
+   def run(server_class=BaseHTTPServer.HTTPServer,
+           handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
+       server_address = ('', 8000)
+       httpd = server_class(server_address, handler_class)
+       httpd.serve_forever()
+
+
+.. class:: HTTPServer(server_address, RequestHandlerClass)
+
+   This class builds on the :class:`TCPServer` class by storing the server address
+   as instance variables named :attr:`server_name` and :attr:`server_port`. The
+   server is accessible by the handler, typically through the handler's
+   :attr:`server` instance variable.
+
+
+.. class:: BaseHTTPRequestHandler(request, client_address, server)
+
+   This class is used to handle the HTTP requests that arrive at the server. By
+   itself, it cannot respond to any actual HTTP requests; it must be subclassed to
+   handle each request method (e.g. GET or POST). :class:`BaseHTTPRequestHandler`
+   provides a number of class and instance variables, and methods for use by
+   subclasses.
+
+   The handler will parse the request and the headers, then call a method specific
+   to the request type. The method name is constructed from the request. For
+   example, for the request method ``SPAM``, the :meth:`do_SPAM` method will be
+   called with no arguments. All of the relevant information is stored in instance
+   variables of the handler.  Subclasses should not need to override or extend the
+   :meth:`__init__` method.
+
+:class:`BaseHTTPRequestHandler` has the following instance variables:
+
+
+.. attribute:: BaseHTTPRequestHandler.client_address
+
+   Contains a tuple of the form ``(host, port)`` referring to the client's address.
+
+
+.. attribute:: BaseHTTPRequestHandler.command
+
+   Contains the command (request type). For example, ``'GET'``.
+
+
+.. attribute:: BaseHTTPRequestHandler.path
+
+   Contains the request path.
+
+
+.. attribute:: BaseHTTPRequestHandler.request_version
+
+   Contains the version string from the request. For example, ``'HTTP/1.0'``.
+
+
+.. attribute:: BaseHTTPRequestHandler.headers
+
+   Holds an instance of the class specified by the :attr:`MessageClass` class
+   variable. This instance parses and manages the headers in the HTTP request.
+
+
+.. attribute:: BaseHTTPRequestHandler.rfile
+
+   Contains an input stream, positioned at the start of the optional input data.
+
+
+.. attribute:: BaseHTTPRequestHandler.wfile
+
+   Contains the output stream for writing a response back to the client. Proper
+   adherence to the HTTP protocol must be used when writing to this stream.
+
+:class:`BaseHTTPRequestHandler` has the following class variables:
+
+
+.. attribute:: BaseHTTPRequestHandler.server_version
+
+   Specifies the server software version.  You may want to override this. The
+   format is multiple whitespace-separated strings, where each string is of the
+   form name[/version]. For example, ``'BaseHTTP/0.2'``.
+
+
+.. attribute:: BaseHTTPRequestHandler.sys_version
+
+   Contains the Python system version, in a form usable by the
+   :attr:`version_string` method and the :attr:`server_version` class variable. For
+   example, ``'Python/1.4'``.
+
+
+.. attribute:: BaseHTTPRequestHandler.error_message_format
+
+   Specifies a format string for building an error response to the client. It uses
+   parenthesized, keyed format specifiers, so the format operand must be a
+   dictionary. The *code* key should be an integer, specifying the numeric HTTP
+   error code value. *message* should be a string containing a (detailed) error
+   message of what occurred, and *explain* should be an explanation of the error
+   code number. Default *message* and *explain* values can found in the *responses*
+   class variable.
+
+
+.. attribute:: BaseHTTPRequestHandler.protocol_version
+
+   This specifies the HTTP protocol version used in responses.  If set to
+   ``'HTTP/1.1'``, the server will permit HTTP persistent connections; however,
+   your server *must* then include an accurate ``Content-Length`` header (using
+   :meth:`send_header`) in all of its responses to clients.  For backwards
+   compatibility, the setting defaults to ``'HTTP/1.0'``.
+
+
+.. attribute:: BaseHTTPRequestHandler.MessageClass
+
+   .. index:: single: Message (in module mimetools)
+
+   Specifies a :class:`rfc822.Message`\ -like class to parse HTTP headers.
+   Typically, this is not overridden, and it defaults to
+   :class:`mimetools.Message`.
+
+
+.. attribute:: BaseHTTPRequestHandler.responses
+
+   This variable contains a mapping of error code integers to two-element tuples
+   containing a short and long message. For example, ``{code: (shortmessage,
+   longmessage)}``. The *shortmessage* is usually used as the *message* key in an
+   error response, and *longmessage* as the *explain* key (see the
+   :attr:`error_message_format` class variable).
+
+A :class:`BaseHTTPRequestHandler` instance has the following methods:
+
+
+.. method:: BaseHTTPRequestHandler.handle()
+
+   Calls :meth:`handle_one_request` once (or, if persistent connections are
+   enabled, multiple times) to handle incoming HTTP requests. You should never need
+   to override it; instead, implement appropriate :meth:`do_\*` methods.
+
+
+.. method:: BaseHTTPRequestHandler.handle_one_request()
+
+   This method will parse and dispatch the request to the appropriate :meth:`do_\*`
+   method.  You should never need to override it.
+
+
+.. method:: BaseHTTPRequestHandler.send_error(code[, message])
+
+   Sends and logs a complete error reply to the client. The numeric *code*
+   specifies the HTTP error code, with *message* as optional, more specific text. A
+   complete set of headers is sent, followed by text composed using the
+   :attr:`error_message_format` class variable.
+
+
+.. method:: BaseHTTPRequestHandler.send_response(code[, message])
+
+   Sends a response header and logs the accepted request. The HTTP response line is
+   sent, followed by *Server* and *Date* headers. The values for these two headers
+   are picked up from the :meth:`version_string` and :meth:`date_time_string`
+   methods, respectively.
+
+
+.. method:: BaseHTTPRequestHandler.send_header(keyword, value)
+
+   Writes a specific HTTP header to the output stream. *keyword* should specify the
+   header keyword, with *value* specifying its value.
+
+
+.. method:: BaseHTTPRequestHandler.end_headers()
+
+   Sends a blank line, indicating the end of the HTTP headers in the response.
+
+
+.. method:: BaseHTTPRequestHandler.log_request([code[, size]])
+
+   Logs an accepted (successful) request. *code* should specify the numeric HTTP
+   code associated with the response. If a size of the response is available, then
+   it should be passed as the *size* parameter.
+
+
+.. method:: BaseHTTPRequestHandler.log_error(...)
+
+   Logs an error when a request cannot be fulfilled. By default, it passes the
+   message to :meth:`log_message`, so it takes the same arguments (*format* and
+   additional values).
+
+
+.. method:: BaseHTTPRequestHandler.log_message(format, ...)
+
+   Logs an arbitrary message to ``sys.stderr``. This is typically overridden to
+   create custom error logging mechanisms. The *format* argument is a standard
+   printf-style format string, where the additional arguments to
+   :meth:`log_message` are applied as inputs to the formatting. The client address
+   and current date and time are prefixed to every message logged.
+
+
+.. method:: BaseHTTPRequestHandler.version_string()
+
+   Returns the server software's version string. This is a combination of the
+   :attr:`server_version` and :attr:`sys_version` class variables.
+
+
+.. method:: BaseHTTPRequestHandler.date_time_string([timestamp])
+
+   Returns the date and time given by *timestamp* (which must be in the format
+   returned by :func:`time.time`), formatted for a message header. If *timestamp*
+   is omitted, it uses the current date and time.
+
+   The result looks like ``'Sun, 06 Nov 1994 08:49:37 GMT'``.
+
+   .. versionadded:: 2.5
+      The *timestamp* parameter.
+
+
+.. method:: BaseHTTPRequestHandler.log_date_time_string()
+
+   Returns the current date and time, formatted for logging.
+
+
+.. method:: BaseHTTPRequestHandler.address_string()
+
+   Returns the client address, formatted for logging. A name lookup is performed on
+   the client's IP address.
+
+
+.. seealso::
+
+   Module :mod:`CGIHTTPServer`
+      Extended request handler that supports CGI scripts.
+
+   Module :mod:`SimpleHTTPServer`
+      Basic request handler that limits response to files actually under the document
+      root.
+

Doc/library/binascii.rst

@@ -0,0 +1,161 @@
+
+:mod:`binascii` --- Convert between binary and ASCII
+====================================================
+
+.. module:: binascii
+   :synopsis: Tools for converting between binary and various ASCII-encoded binary
+              representations.
+
+
+.. index::
+   module: uu
+   module: base64
+   module: binhex
+
+The :mod:`binascii` module contains a number of methods to convert between
+binary and various ASCII-encoded binary representations. Normally, you will not
+use these functions directly but use wrapper modules like :mod:`uu`,
+:mod:`base64`, or :mod:`binhex` instead. The :mod:`binascii` module contains
+low-level functions written in C for greater speed that are used by the
+higher-level modules.
+
+The :mod:`binascii` module defines the following functions:
+
+
+.. function:: a2b_uu(string)
+
+   Convert a single line of uuencoded data back to binary and return the binary
+   data. Lines normally contain 45 (binary) bytes, except for the last line. Line
+   data may be followed by whitespace.
+
+
+.. function:: b2a_uu(data)
+
+   Convert binary data to a line of ASCII characters, the return value is the
+   converted line, including a newline char. The length of *data* should be at most
+   45.
+
+
+.. function:: a2b_base64(string)
+
+   Convert a block of base64 data back to binary and return the binary data. More
+   than one line may be passed at a time.
+
+
+.. function:: b2a_base64(data)
+
+   Convert binary data to a line of ASCII characters in base64 coding. The return
+   value is the converted line, including a newline char. The length of *data*
+   should be at most 57 to adhere to the base64 standard.
+
+
+.. function:: a2b_qp(string[, header])
+
+   Convert a block of quoted-printable data back to binary and return the binary
+   data. More than one line may be passed at a time. If the optional argument
+   *header* is present and true, underscores will be decoded as spaces.
+
+
+.. function:: b2a_qp(data[, quotetabs, istext, header])
+
+   Convert binary data to a line(s) of ASCII characters in quoted-printable
+   encoding.  The return value is the converted line(s). If the optional argument
+   *quotetabs* is present and true, all tabs and spaces will be encoded.   If the
+   optional argument *istext* is present and true, newlines are not encoded but
+   trailing whitespace will be encoded. If the optional argument *header* is
+   present and true, spaces will be encoded as underscores per RFC1522. If the
+   optional argument *header* is present and false, newline characters will be
+   encoded as well; otherwise linefeed conversion might corrupt the binary data
+   stream.
+
+
+.. function:: a2b_hqx(string)
+
+   Convert binhex4 formatted ASCII data to binary, without doing RLE-decompression.
+   The string should contain a complete number of binary bytes, or (in case of the
+   last portion of the binhex4 data) have the remaining bits zero.
+
+
+.. function:: rledecode_hqx(data)
+
+   Perform RLE-decompression on the data, as per the binhex4 standard. The
+   algorithm uses ``0x90`` after a byte as a repeat indicator, followed by a count.
+   A count of ``0`` specifies a byte value of ``0x90``. The routine returns the
+   decompressed data, unless data input data ends in an orphaned repeat indicator,
+   in which case the :exc:`Incomplete` exception is raised.
+
+
+.. function:: rlecode_hqx(data)
+
+   Perform binhex4 style RLE-compression on *data* and return the result.
+
+
+.. function:: b2a_hqx(data)
+
+   Perform hexbin4 binary-to-ASCII translation and return the resulting string. The
+   argument should already be RLE-coded, and have a length divisible by 3 (except
+   possibly the last fragment).
+
+
+.. function:: crc_hqx(data, crc)
+
+   Compute the binhex4 crc value of *data*, starting with an initial *crc* and
+   returning the result.
+
+
+.. function:: crc32(data[, crc])
+
+   Compute CRC-32, the 32-bit checksum of data, starting with an initial crc.  This
+   is consistent with the ZIP file checksum.  Since the algorithm is designed for
+   use as a checksum algorithm, it is not suitable for use as a general hash
+   algorithm.  Use as follows::
+
+      print binascii.crc32("hello world")
+      # Or, in two pieces:
+      crc = binascii.crc32("hello")
+      crc = binascii.crc32(" world", crc)
+      print crc
+
+
+.. function:: b2a_hex(data)
+              hexlify(data)
+
+   Return the hexadecimal representation of the binary *data*.  Every byte of
+   *data* is converted into the corresponding 2-digit hex representation.  The
+   resulting string is therefore twice as long as the length of *data*.
+
+
+.. function:: a2b_hex(hexstr)
+              unhexlify(hexstr)
+
+   Return the binary data represented by the hexadecimal string *hexstr*.  This
+   function is the inverse of :func:`b2a_hex`. *hexstr* must contain an even number
+   of hexadecimal digits (which can be upper or lower case), otherwise a
+   :exc:`TypeError` is raised.
+
+
+.. exception:: Error
+
+   Exception raised on errors. These are usually programming errors.
+
+
+.. exception:: Incomplete
+
+   Exception raised on incomplete data. These are usually not programming errors,
+   but may be handled by reading a little more data and trying again.
+
+
+.. seealso::
+
+   Module :mod:`base64`
+      Support for base64 encoding used in MIME email messages.
+
+   Module :mod:`binhex`
+      Support for the binhex format used on the Macintosh.
+
+   Module :mod:`uu`
+      Support for UU encoding used on Unix.
+
+   Module :mod:`quopri`
+      Support for quoted-printable encoding used in MIME email messages.
+

Doc/library/binhex.rst

@@ -0,0 +1,59 @@
+
+:mod:`binhex` --- Encode and decode binhex4 files
+=================================================
+
+.. module:: binhex
+   :synopsis: Encode and decode files in binhex4 format.
+
+
+This module encodes and decodes files in binhex4 format, a format allowing
+representation of Macintosh files in ASCII.  On the Macintosh, both forks of a
+file and the finder information are encoded (or decoded), on other platforms
+only the data fork is handled.
+
+The :mod:`binhex` module defines the following functions:
+
+
+.. function:: binhex(input, output)
+
+   Convert a binary file with filename *input* to binhex file *output*. The
+   *output* parameter can either be a filename or a file-like object (any object
+   supporting a :meth:`write` and :meth:`close` method).
+
+
+.. function:: hexbin(input[, output])
+
+   Decode a binhex file *input*. *input* may be a filename or a file-like object
+   supporting :meth:`read` and :meth:`close` methods. The resulting file is written
+   to a file named *output*, unless the argument is omitted in which case the
+   output filename is read from the binhex file.
+
+The following exception is also defined:
+
+
+.. exception:: Error
+
+   Exception raised when something can't be encoded using the binhex format (for
+   example, a filename is too long to fit in the filename field), or when input is
+   not properly encoded binhex data.
+
+
+.. seealso::
+
+   Module :mod:`binascii`
+      Support module containing ASCII-to-binary and binary-to-ASCII conversions.
+
+
+.. _binhex-notes:
+
+Notes
+-----
+
+There is an alternative, more powerful interface to the coder and decoder, see
+the source for details.
+
+If you code or decode textfiles on non-Macintosh platforms they will still use
+the Macintosh newline convention (carriage-return as end of line).
+
+As of this writing, :func:`hexbin` appears to not work in all cases.
+

Doc/library/bisect.rst

@@ -0,0 +1,92 @@
+
+:mod:`bisect` --- Array bisection algorithm
+===========================================
+
+.. module:: bisect
+   :synopsis: Array bisection algorithms for binary searching.
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+.. % LaTeX produced by Fred L. Drake, Jr. <fdrake@acm.org>, with an
+.. % example based on the PyModules FAQ entry by Aaron Watters
+.. % <arw@pythonpros.com>.
+
+This module provides support for maintaining a list in sorted order without
+having to sort the list after each insertion.  For long lists of items with
+expensive comparison operations, this can be an improvement over the more common
+approach.  The module is called :mod:`bisect` because it uses a basic bisection
+algorithm to do its work.  The source code may be most useful as a working
+example of the algorithm (the boundary conditions are already right!).
+
+The following functions are provided:
+
+
+.. function:: bisect_left(list, item[, lo[, hi]])
+
+   Locate the proper insertion point for *item* in *list* to maintain sorted order.
+   The parameters *lo* and *hi* may be used to specify a subset of the list which
+   should be considered; by default the entire list is used.  If *item* is already
+   present in *list*, the insertion point will be before (to the left of) any
+   existing entries.  The return value is suitable for use as the first parameter
+   to ``list.insert()``.  This assumes that *list* is already sorted.
+
+   .. versionadded:: 2.1
+
+
+.. function:: bisect_right(list, item[, lo[, hi]])
+
+   Similar to :func:`bisect_left`, but returns an insertion point which comes after
+   (to the right of) any existing entries of *item* in *list*.
+
+   .. versionadded:: 2.1
+
+
+.. function:: bisect(...)
+
+   Alias for :func:`bisect_right`.
+
+
+.. function:: insort_left(list, item[, lo[, hi]])
+
+   Insert *item* in *list* in sorted order.  This is equivalent to
+   ``list.insert(bisect.bisect_left(list, item, lo, hi), item)``.  This assumes
+   that *list* is already sorted.
+
+   .. versionadded:: 2.1
+
+
+.. function:: insort_right(list, item[, lo[, hi]])
+
+   Similar to :func:`insort_left`, but inserting *item* in *list* after any
+   existing entries of *item*.
+
+   .. versionadded:: 2.1
+
+
+.. function:: insort(...)
+
+   Alias for :func:`insort_right`.
+
+
+Examples
+--------
+
+.. _bisect-example:
+
+The :func:`bisect` function is generally useful for categorizing numeric data.
+This example uses :func:`bisect` to look up a letter grade for an exam total
+(say) based on a set of ordered numeric breakpoints: 85 and up is an 'A', 75..84
+is a 'B', etc. ::
+
+   >>> grades = "FEDCBA"
+   >>> breakpoints = [30, 44, 66, 75, 85]
+   >>> from bisect import bisect
+   >>> def grade(total):
+   ...           return grades[bisect(breakpoints, total)]
+   ...
+   >>> grade(66)
+   'C'
+   >>> map(grade, [33, 99, 77, 44, 12, 88])
+   ['E', 'A', 'B', 'D', 'F', 'A']
+
+

Doc/library/bsddb.rst

@@ -0,0 +1,211 @@
+
+:mod:`bsddb` --- Interface to Berkeley DB library
+=================================================
+
+.. module:: bsddb
+   :synopsis: Interface to Berkeley DB database library
+.. sectionauthor:: Skip Montanaro <skip@mojam.com>
+
+
+The :mod:`bsddb` module provides an interface to the Berkeley DB library.  Users
+can create hash, btree or record based library files using the appropriate open
+call. Bsddb objects behave generally like dictionaries.  Keys and values must be
+strings, however, so to use other objects as keys or to store other kinds of
+objects the user must serialize them somehow, typically using
+:func:`marshal.dumps` or  :func:`pickle.dumps`.
+
+The :mod:`bsddb` module requires a Berkeley DB library version from 3.3 thru
+4.5.
+
+
+.. seealso::
+
+   http://pybsddb.sourceforge.net/
+      The website with documentation for the :mod:`bsddb.db` Python Berkeley DB
+      interface that closely mirrors the object oriented interface provided in
+      Berkeley DB 3 and 4.
+
+   http://www.oracle.com/database/berkeley-db/
+      The Berkeley DB library.
+
+A more modern DB, DBEnv and DBSequence object interface is available in the
+:mod:`bsddb.db` module which closely matches the Berkeley DB C API documented at
+the above URLs.  Additional features provided by the :mod:`bsddb.db` API include
+fine tuning, transactions, logging, and multiprocess concurrent database access.
+
+The following is a description of the legacy :mod:`bsddb` interface compatible
+with the old Python bsddb module.  Starting in Python 2.5 this interface should
+be safe for multithreaded access.  The :mod:`bsddb.db` API is recommended for
+threading users as it provides better control.
+
+The :mod:`bsddb` module defines the following functions that create objects that
+access the appropriate type of Berkeley DB file.  The first two arguments of
+each function are the same.  For ease of portability, only the first two
+arguments should be used in most instances.
+
+
+.. function:: hashopen(filename[, flag[, mode[, pgsize[, ffactor[, nelem[, cachesize[, lorder[, hflags]]]]]]]])
+
+   Open the hash format file named *filename*.  Files never intended to be
+   preserved on disk may be created by passing ``None`` as the  *filename*.  The
+   optional *flag* identifies the mode used to open the file.  It may be ``'r'``
+   (read only), ``'w'`` (read-write) , ``'c'`` (read-write - create if necessary;
+   the default) or ``'n'`` (read-write - truncate to zero length).  The other
+   arguments are rarely used and are just passed to the low-level :cfunc:`dbopen`
+   function.  Consult the Berkeley DB documentation for their use and
+   interpretation.
+
+
+.. function:: btopen(filename[, flag[, mode[, btflags[, cachesize[, maxkeypage[, minkeypage[, pgsize[, lorder]]]]]]]])
+
+   Open the btree format file named *filename*.  Files never intended  to be
+   preserved on disk may be created by passing ``None`` as the  *filename*.  The
+   optional *flag* identifies the mode used to open the file.  It may be ``'r'``
+   (read only), ``'w'`` (read-write), ``'c'`` (read-write - create if necessary;
+   the default) or ``'n'`` (read-write - truncate to zero length).  The other
+   arguments are rarely used and are just passed to the low-level dbopen function.
+   Consult the Berkeley DB documentation for their use and interpretation.
+
+
+.. function:: rnopen(filename[, flag[, mode[, rnflags[, cachesize[, pgsize[, lorder[, rlen[, delim[, source[, pad]]]]]]]]]])
+
+   Open a DB record format file named *filename*.  Files never intended  to be
+   preserved on disk may be created by passing ``None`` as the  *filename*.  The
+   optional *flag* identifies the mode used to open the file.  It may be ``'r'``
+   (read only), ``'w'`` (read-write), ``'c'`` (read-write - create if necessary;
+   the default) or ``'n'`` (read-write - truncate to zero length).  The other
+   arguments are rarely used and are just passed to the low-level dbopen function.
+   Consult the Berkeley DB documentation for their use and interpretation.
+
+
+.. class:: StringKeys(db)
+
+   Wrapper class around a DB object that supports string keys (rather than bytes).
+   All keys are encoded as UTF-8, then passed to the underlying object.
+   
+   .. versionadded:: 3.0
+
+
+.. class:: StringValues(db)
+
+   Wrapper class around a DB object that supports string values (rather than bytes).
+   All values are encoded as UTF-8, then passed to the underlying object.
+
+   .. versionadded:: 3.0
+
+
+.. seealso::
+
+   Module :mod:`dbhash`
+      DBM-style interface to the :mod:`bsddb`
+
+
+.. _bsddb-objects:
+
+Hash, BTree and Record Objects
+------------------------------
+
+Once instantiated, hash, btree and record objects support the same methods as
+dictionaries.  In addition, they support the methods listed below.
+
+.. versionchanged:: 2.3.1
+   Added dictionary methods.
+
+
+.. method:: bsddbobject.close()
+
+   Close the underlying file.  The object can no longer be accessed.  Since there
+   is no open :meth:`open` method for these objects, to open the file again a new
+   :mod:`bsddb` module open function must be called.
+
+
+.. method:: bsddbobject.keys()
+
+   Return the list of keys contained in the DB file.  The order of the list is
+   unspecified and should not be relied on.  In particular, the order of the list
+   returned is different for different file formats.
+
+
+.. method:: bsddbobject.has_key(key)
+
+   Return ``1`` if the DB file contains the argument as a key.
+
+
+.. method:: bsddbobject.set_location(key)
+
+   Set the cursor to the item indicated by *key* and return a tuple containing the
+   key and its value.  For binary tree databases (opened using :func:`btopen`), if
+   *key* does not actually exist in the database, the cursor will point to the next
+   item in sorted order and return that key and value.  For other databases,
+   :exc:`KeyError` will be raised if *key* is not found in the database.
+
+
+.. method:: bsddbobject.first()
+
+   Set the cursor to the first item in the DB file and return it.  The order of
+   keys in the file is unspecified, except in the case of B-Tree databases. This
+   method raises :exc:`bsddb.error` if the database is empty.
+
+
+.. method:: bsddbobject.next()
+
+   Set the cursor to the next item in the DB file and return it.  The order of
+   keys in the file is unspecified, except in the case of B-Tree databases.
+
+
+.. method:: bsddbobject.previous()
+
+   Set the cursor to the previous item in the DB file and return it.  The order of
+   keys in the file is unspecified, except in the case of B-Tree databases.  This
+   is not supported on hashtable databases (those opened with :func:`hashopen`).
+
+
+.. method:: bsddbobject.last()
+
+   Set the cursor to the last item in the DB file and return it.  The order of keys
+   in the file is unspecified.  This is not supported on hashtable databases (those
+   opened with :func:`hashopen`). This method raises :exc:`bsddb.error` if the
+   database is empty.
+
+
+.. method:: bsddbobject.sync()
+
+   Synchronize the database on disk.
+
+Example::
+
+   >>> import bsddb
+   >>> db = bsddb.btopen('/tmp/spam.db', 'c')
+   >>> for i in range(10): db['%d'%i] = '%d'% (i*i)
+   ... 
+   >>> db['3']
+   '9'
+   >>> db.keys()
+   ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
+   >>> db.first()
+   ('0', '0')
+   >>> db.next()
+   ('1', '1')
+   >>> db.last()
+   ('9', '81')
+   >>> db.set_location('2')
+   ('2', '4')
+   >>> db.previous() 
+   ('1', '1')
+   >>> for k, v in db.iteritems():
+   ...     print k, v
+   0 0
+   1 1
+   2 4
+   3 9
+   4 16
+   5 25
+   6 36
+   7 49
+   8 64
+   9 81
+   >>> '8' in db
+   True
+   >>> db.sync()
+   0
+

Doc/library/bz2.rst

@@ -0,0 +1,181 @@
+
+:mod:`bz2` --- Compression compatible with :program:`bzip2`
+===========================================================
+
+.. module:: bz2
+   :synopsis: Interface to compression and decompression routines compatible with bzip2.
+.. moduleauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
+.. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
+
+
+.. versionadded:: 2.3
+
+This module provides a comprehensive interface for the bz2 compression library.
+It implements a complete file interface, one-shot (de)compression functions, and
+types for sequential (de)compression.
+
+Here is a resume of the features offered by the bz2 module:
+
+* :class:`BZ2File` class implements a complete file interface, including
+  :meth:`readline`, :meth:`readlines`, :meth:`writelines`, :meth:`seek`, etc;
+
+* :class:`BZ2File` class implements emulated :meth:`seek` support;
+
+* :class:`BZ2File` class implements universal newline support;
+
+* :class:`BZ2File` class offers an optimized line iteration using the readahead
+  algorithm borrowed from file objects;
+
+* Sequential (de)compression supported by :class:`BZ2Compressor` and
+  :class:`BZ2Decompressor` classes;
+
+* One-shot (de)compression supported by :func:`compress` and :func:`decompress`
+  functions;
+
+* Thread safety uses individual locking mechanism;
+
+* Complete inline documentation;
+
+
+(De)compression of files
+------------------------
+
+Handling of compressed files is offered by the :class:`BZ2File` class.
+
+
+.. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]])
+
+   Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading  (default)
+   or writing. When opened for writing, the file will be created if it doesn't
+   exist, and truncated otherwise. If *buffering* is given, ``0`` means unbuffered,
+   and larger numbers specify the buffer size; the default is ``0``. If
+   *compresslevel* is given, it must be a number between ``1`` and ``9``; the
+   default is ``9``. Add a ``'U'`` to mode to open the file for input with
+   universal newline support. Any line ending in the input file will be seen as a
+   ``'\n'`` in Python.  Also, a file so opened gains the attribute
+   :attr:`newlines`; the value for this attribute is one of ``None`` (no newline
+   read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the newline
+   types seen. Universal newlines are available only when reading. Instances
+   support iteration in the same way as normal :class:`file` instances.
+
+
+.. method:: BZ2File.close()
+
+   Close the file. Sets data attribute :attr:`closed` to true. A closed file cannot
+   be used for further I/O operations. :meth:`close` may be called more than once
+   without error.
+
+
+.. method:: BZ2File.read([size])
+
+   Read at most *size* uncompressed bytes, returned as a string. If the *size*
+   argument is negative or omitted, read until EOF is reached.
+
+
+.. method:: BZ2File.readline([size])
+
+   Return the next line from the file, as a string, retaining newline. A
+   non-negative *size* argument limits the maximum number of bytes to return (an
+   incomplete line may be returned then). Return an empty string at EOF.
+
+
+.. method:: BZ2File.readlines([size])
+
+   Return a list of lines read. The optional *size* argument, if given, is an
+   approximate bound on the total number of bytes in the lines returned.
+
+
+.. method:: BZ2File.seek(offset[, whence])
+
+   Move to new file position. Argument *offset* is a byte count. Optional argument
+   *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start of file; offset
+   should be ``>= 0``); other values are ``os.SEEK_CUR`` or ``1`` (move relative to
+   current position; offset can be positive or negative), and ``os.SEEK_END`` or
+   ``2`` (move relative to end of file; offset is usually negative, although many
+   platforms allow seeking beyond the end of a file).
+
+   Note that seeking of bz2 files is emulated, and depending on the parameters the
+   operation may be extremely slow.
+
+
+.. method:: BZ2File.tell()
+
+   Return the current file position, an integer (may be a long integer).
+
+
+.. method:: BZ2File.write(data)
+
+   Write string *data* to file. Note that due to buffering, :meth:`close` may be
+   needed before the file on disk reflects the data written.
+
+
+.. method:: BZ2File.writelines(sequence_of_strings)
+
+   Write the sequence of strings to the file. Note that newlines are not added. The
+   sequence can be any iterable object producing strings. This is equivalent to
+   calling write() for each string.
+
+
+Sequential (de)compression
+--------------------------
+
+Sequential compression and decompression is done using the classes
+:class:`BZ2Compressor` and :class:`BZ2Decompressor`.
+
+
+.. class:: BZ2Compressor([compresslevel])
+
+   Create a new compressor object. This object may be used to compress data
+   sequentially. If you want to compress data in one shot, use the :func:`compress`
+   function instead. The *compresslevel* parameter, if given, must be a number
+   between ``1`` and ``9``; the default is ``9``.
+
+
+.. method:: BZ2Compressor.compress(data)
+
+   Provide more data to the compressor object. It will return chunks of compressed
+   data whenever possible. When you've finished providing data to compress, call
+   the :meth:`flush` method to finish the compression process, and return what is
+   left in internal buffers.
+
+
+.. method:: BZ2Compressor.flush()
+
+   Finish the compression process and return what is left in internal buffers. You
+   must not use the compressor object after calling this method.
+
+
+.. class:: BZ2Decompressor()
+
+   Create a new decompressor object. This object may be used to decompress data
+   sequentially. If you want to decompress data in one shot, use the
+   :func:`decompress` function instead.
+
+
+.. method:: BZ2Decompressor.decompress(data)
+
+   Provide more data to the decompressor object. It will return chunks of
+   decompressed data whenever possible. If you try to decompress data after the end
+   of stream is found, :exc:`EOFError` will be raised. If any data was found after
+   the end of stream, it'll be ignored and saved in :attr:`unused_data` attribute.
+
+
+One-shot (de)compression
+------------------------
+
+One-shot compression and decompression is provided through the :func:`compress`
+and :func:`decompress` functions.
+
+
+.. function:: compress(data[, compresslevel])
+
+   Compress *data* in one shot. If you want to compress data sequentially, use an
+   instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter, if
+   given, must be a number between ``1`` and ``9``; the default is ``9``.
+
+
+.. function:: decompress(data)
+
+   Decompress *data* in one shot. If you want to decompress data sequentially, use
+   an instance of :class:`BZ2Decompressor` instead.
+

Doc/library/calendar.rst

@@ -0,0 +1,326 @@
+
+:mod:`calendar` --- General calendar-related functions
+======================================================
+
+.. module:: calendar
+   :synopsis: Functions for working with calendars, including some emulation of the Unix cal
+              program.
+.. sectionauthor:: Drew Csillag <drew_csillag@geocities.com>
+
+
+This module allows you to output calendars like the Unix :program:`cal` program,
+and provides additional useful functions related to the calendar. By default,
+these calendars have Monday as the first day of the week, and Sunday as the last
+(the European convention). Use :func:`setfirstweekday` to set the first day of
+the week to Sunday (6) or to any other weekday.  Parameters that specify dates
+are given as integers. For related
+functionality, see also the :mod:`datetime` and :mod:`time` modules.
+
+Most of these functions and classses rely on the :mod:`datetime` module which
+uses an idealized calendar, the current Gregorian calendar indefinitely extended
+in both directions.  This matches the definition of the "proleptic Gregorian"
+calendar in Dershowitz and Reingold's book "Calendrical Calculations", where
+it's the base calendar for all computations.
+
+
+.. class:: Calendar([firstweekday])
+
+   Creates a :class:`Calendar` object. *firstweekday* is an integer specifying the
+   first day of the week. ``0`` is Monday (the default), ``6`` is Sunday.
+
+   A :class:`Calendar` object provides several methods that can be used for
+   preparing the calendar data for formatting. This class doesn't do any formatting
+   itself. This is the job of subclasses.
+
+   .. versionadded:: 2.5
+
+:class:`Calendar` instances have the following methods:
+
+
+.. method:: Calendar.iterweekdays(weekday)
+
+   Return an iterator for the week day numbers that will be used for one week. The
+   first number from the iterator will be the same as the number returned by
+   :meth:`firstweekday`.
+
+
+.. method:: Calendar.itermonthdates(year, month)
+
+   Return an iterator for the month *month* (1-12) in the year *year*. This
+   iterator will return all days (as :class:`datetime.date` objects) for the month
+   and all days before the start of the month or after the end of the month that
+   are required to get a complete week.
+
+
+.. method:: Calendar.itermonthdays2(year, month)
+
+   Return an iterator for the month *month* in the year *year* similar to
+   :meth:`itermonthdates`. Days returned will be tuples consisting of a day number
+   and a week day number.
+
+
+.. method:: Calendar.itermonthdays(year, month)
+
+   Return an iterator for the month *month* in the year *year* similar to
+   :meth:`itermonthdates`. Days returned will simply be day numbers.
+
+
+.. method:: Calendar.monthdatescalendar(year, month)
+
+   Return a list of the weeks in the month *month* of the *year* as full weeks.
+   Weeks are lists of seven :class:`datetime.date` objects.
+
+
+.. method:: Calendar.monthdays2calendar(year, month)
+
+   Return a list of the weeks in the month *month* of the *year* as full weeks.
+   Weeks are lists of seven tuples of day numbers and weekday numbers.
+
+
+.. method:: Calendar.monthdayscalendar(year, month)
+
+   Return a list of the weeks in the month *month* of the *year* as full weeks.
+   Weeks are lists of seven day numbers.
+
+
+.. method:: Calendar.yeardatescalendar(year, month[, width])
+
+   Return the data for the specified year ready for formatting. The return value is
+   a list of month rows. Each month row contains up to *width* months (defaulting
+   to 3). Each month contains between 4 and 6 weeks and each week contains 1--7
+   days. Days are :class:`datetime.date` objects.
+
+
+.. method:: Calendar.yeardays2calendar(year, month[, width])
+
+   Return the data for the specified year ready for formatting (similar to
+   :meth:`yeardatescalendar`). Entries in the week lists are tuples of day numbers
+   and weekday numbers. Day numbers outside this month are zero.
+
+
+.. method:: Calendar.yeardayscalendar(year, month[, width])
+
+   Return the data for the specified year ready for formatting (similar to
+   :meth:`yeardatescalendar`). Entries in the week lists are day numbers. Day
+   numbers outside this month are zero.
+
+
+.. class:: TextCalendar([firstweekday])
+
+   This class can be used to generate plain text calendars.
+
+   .. versionadded:: 2.5
+
+:class:`TextCalendar` instances have the following methods:
+
+
+.. method:: TextCalendar.formatmonth(theyear, themonth[, w[, l]])
+
+   Return a month's calendar in a multi-line string. If *w* is provided, it
+   specifies the width of the date columns, which are centered. If *l* is given, it
+   specifies the number of lines that each week will use. Depends on the first
+   weekday as set by :func:`setfirstweekday`.
+
+
+.. method:: TextCalendar.prmonth(theyear, themonth[, w[, l]])
+
+   Print a month's calendar as returned by :meth:`formatmonth`.
+
+
+.. method:: TextCalendar.formatyear(theyear, themonth[, w[, l[, c[, m]]]])
+
+   Return a *m*-column calendar for an entire year as a multi-line string. Optional
+   parameters *w*, *l*, and *c* are for date column width, lines per week, and
+   number of spaces between month columns, respectively. Depends on the first
+   weekday as set by :meth:`setfirstweekday`.  The earliest year for which a
+   calendar can be generated is platform-dependent.
+
+
+.. method:: TextCalendar.pryear(theyear[, w[, l[, c[, m]]]])
+
+   Print the calendar for an entire year as returned by :meth:`formatyear`.
+
+
+.. class:: HTMLCalendar([firstweekday])
+
+   This class can be used to generate HTML calendars.
+
+   .. versionadded:: 2.5
+
+:class:`HTMLCalendar` instances have the following methods:
+
+
+.. method:: HTMLCalendar.formatmonth(theyear, themonth[, withyear])
+
+   Return a month's calendar as an HTML table. If *withyear* is true the year will
+   be included in the header, otherwise just the month name will be used.
+
+
+.. method:: HTMLCalendar.formatyear(theyear, themonth[, width])
+
+   Return a year's calendar as an HTML table. *width* (defaulting to 3) specifies
+   the number of months per row.
+
+
+.. method:: HTMLCalendar.formatyearpage(theyear, themonth[, width[, css[, encoding]]])
+
+   Return a year's calendar as a complete HTML page. *width* (defaulting to 3)
+   specifies the number of months per row. *css* is the name for the cascading
+   style sheet to be used. :const:`None` can be passed if no style sheet should be
+   used. *encoding* specifies the encoding to be used for the output (defaulting to
+   the system default encoding).
+
+
+.. class:: LocaleTextCalendar([firstweekday[, locale]])
+
+   This subclass of :class:`TextCalendar` can be passed a locale name in the
+   constructor and will return month and weekday names in the specified locale. If
+   this locale includes an encoding all strings containing month and weekday names
+   will be returned as unicode.
+
+   .. versionadded:: 2.5
+
+
+.. class:: LocaleHTMLCalendar([firstweekday[, locale]])
+
+   This subclass of :class:`HTMLCalendar` can be passed a locale name in the
+   constructor and will return month and weekday names in the specified locale. If
+   this locale includes an encoding all strings containing month and weekday names
+   will be returned as unicode.
+
+   .. versionadded:: 2.5
+
+For simple text calendars this module provides the following functions.
+
+
+.. function:: setfirstweekday(weekday)
+
+   Sets the weekday (``0`` is Monday, ``6`` is Sunday) to start each week. The
+   values :const:`MONDAY`, :const:`TUESDAY`, :const:`WEDNESDAY`, :const:`THURSDAY`,
+   :const:`FRIDAY`, :const:`SATURDAY`, and :const:`SUNDAY` are provided for
+   convenience. For example, to set the first weekday to Sunday::
+
+      import calendar
+      calendar.setfirstweekday(calendar.SUNDAY)
+
+   .. versionadded:: 2.0
+
+
+.. function:: firstweekday()
+
+   Returns the current setting for the weekday to start each week.
+
+   .. versionadded:: 2.0
+
+
+.. function:: isleap(year)
+
+   Returns :const:`True` if *year* is a leap year, otherwise :const:`False`.
+
+
+.. function:: leapdays(y1, y2)
+
+   Returns the number of leap years in the range from *y1* to *y2* (exclusive),
+   where *y1* and *y2* are years.
+
+   .. versionchanged:: 2.0
+      This function didn't work for ranges spanning a century change in Python
+      1.5.2.
+
+
+.. function:: weekday(year, month, day)
+
+   Returns the day of the week (``0`` is Monday) for *year* (``1970``--...),
+   *month* (``1``--``12``), *day* (``1``--``31``).
+
+
+.. function:: weekheader(n)
+
+   Return a header containing abbreviated weekday names. *n* specifies the width in
+   characters for one weekday.
+
+
+.. function:: monthrange(year, month)
+
+   Returns weekday of first day of the month and number of days in month,  for the
+   specified *year* and *month*.
+
+
+.. function:: monthcalendar(year, month)
+
+   Returns a matrix representing a month's calendar.  Each row represents a week;
+   days outside of the month a represented by zeros. Each week begins with Monday
+   unless set by :func:`setfirstweekday`.
+
+
+.. function:: prmonth(theyear, themonth[, w[, l]])
+
+   Prints a month's calendar as returned by :func:`month`.
+
+
+.. function:: month(theyear, themonth[, w[, l]])
+
+   Returns a month's calendar in a multi-line string using the :meth:`formatmonth`
+   of the :class:`TextCalendar` class.
+
+   .. versionadded:: 2.0
+
+
+.. function:: prcal(year[, w[, l[c]]])
+
+   Prints the calendar for an entire year as returned by  :func:`calendar`.
+
+
+.. function:: calendar(year[, w[, l[c]]])
+
+   Returns a 3-column calendar for an entire year as a multi-line string using the
+   :meth:`formatyear` of the :class:`TextCalendar` class.
+
+   .. versionadded:: 2.0
+
+
+.. function:: timegm(tuple)
+
+   An unrelated but handy function that takes a time tuple such as returned by the
+   :func:`gmtime` function in the :mod:`time` module, and returns the corresponding
+   Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding.  In
+   fact, :func:`time.gmtime` and :func:`timegm` are each others' inverse.
+
+   .. versionadded:: 2.0
+
+The :mod:`calendar` module exports the following data attributes:
+
+
+.. data:: day_name
+
+   An array that represents the days of the week in the current locale.
+
+
+.. data:: day_abbr
+
+   An array that represents the abbreviated days of the week in the current locale.
+
+
+.. data:: month_name
+
+   An array that represents the months of the year in the current locale.  This
+   follows normal convention of January being month number 1, so it has a length of
+   13 and  ``month_name[0]`` is the empty string.
+
+
+.. data:: month_abbr
+
+   An array that represents the abbreviated months of the year in the current
+   locale.  This follows normal convention of January being month number 1, so it
+   has a length of 13 and  ``month_abbr[0]`` is the empty string.
+
+
+.. seealso::
+
+   Module :mod:`datetime`
+      Object-oriented interface to dates and times with similar functionality to the
+      :mod:`time` module.
+
+   Module :mod:`time`
+      Low-level time related functions.
+

Doc/library/carbon.rst

@@ -0,0 +1,288 @@
+
+.. _toolbox:
+
+*********************
+MacOS Toolbox Modules
+*********************
+
+There are a set of modules that provide interfaces to various MacOS toolboxes.
+If applicable the module will define a number of Python objects for the various
+structures declared by the toolbox, and operations will be implemented as
+methods of the object.  Other operations will be implemented as functions in the
+module.  Not all operations possible in C will also be possible in Python
+(callbacks are often a problem), and parameters will occasionally be different
+in Python (input and output buffers, especially).  All methods and functions
+have a :attr:`__doc__` string describing their arguments and return values, and
+for additional description you are referred to `Inside Macintosh
+<http://developer.apple.com/documentation/macos8/mac8.html>`_ or similar works.
+
+These modules all live in a package called :mod:`Carbon`. Despite that name they
+are not all part of the Carbon framework: CF is really in the CoreFoundation
+framework and Qt is in the QuickTime framework. The normal use pattern is ::
+
+   from Carbon import AE
+
+**Warning!**  These modules are not yet documented.  If you wish to contribute
+documentation of any of these modules, please get in touch with docs@python.org.
+
+
+:mod:`Carbon.AE` --- Apple Events
+=================================
+
+.. module:: Carbon.AE
+   :platform: Mac
+   :synopsis: Interface to the Apple Events toolbox.
+
+
+
+:mod:`Carbon.AH` --- Apple Help
+===============================
+
+.. module:: Carbon.AH
+   :platform: Mac
+   :synopsis: Interface to the Apple Help manager.
+
+
+
+:mod:`Carbon.App` --- Appearance Manager
+========================================
+
+.. module:: Carbon.App
+   :platform: Mac
+   :synopsis: Interface to the Appearance Manager.
+
+
+
+:mod:`Carbon.CF` --- Core Foundation
+====================================
+
+.. module:: Carbon.CF
+   :platform: Mac
+   :synopsis: Interface to the Core Foundation.
+
+
+The ``CFBase``, ``CFArray``, ``CFData``, ``CFDictionary``, ``CFString`` and
+``CFURL`` objects are supported, some only partially.
+
+
+:mod:`Carbon.CG` --- Core Graphics
+==================================
+
+.. module:: Carbon.CG
+   :platform: Mac
+   :synopsis: Interface to the Component Manager.
+
+
+
+:mod:`Carbon.CarbonEvt` --- Carbon Event Manager
+================================================
+
+.. module:: Carbon.CarbonEvt
+   :platform: Mac
+   :synopsis: Interface to the Carbon Event Manager.
+
+
+
+:mod:`Carbon.Cm` --- Component Manager
+======================================
+
+.. module:: Carbon.Cm
+   :platform: Mac
+   :synopsis: Interface to the Component Manager.
+
+
+
+:mod:`Carbon.Ctl` --- Control Manager
+=====================================
+
+.. module:: Carbon.Ctl
+   :platform: Mac
+   :synopsis: Interface to the Control Manager.
+
+
+
+:mod:`Carbon.Dlg` --- Dialog Manager
+====================================
+
+.. module:: Carbon.Dlg
+   :platform: Mac
+   :synopsis: Interface to the Dialog Manager.
+
+
+
+:mod:`Carbon.Evt` --- Event Manager
+===================================
+
+.. module:: Carbon.Evt
+   :platform: Mac
+   :synopsis: Interface to the classic Event Manager.
+
+
+
+:mod:`Carbon.Fm` --- Font Manager
+=================================
+
+.. module:: Carbon.Fm
+   :platform: Mac
+   :synopsis: Interface to the Font Manager.
+
+
+
+:mod:`Carbon.Folder` --- Folder Manager
+=======================================
+
+.. module:: Carbon.Folder
+   :platform: Mac
+   :synopsis: Interface to the Folder Manager.
+
+
+
+:mod:`Carbon.Help` --- Help Manager
+===================================
+
+.. module:: Carbon.Help
+   :platform: Mac
+   :synopsis: Interface to the Carbon Help Manager.
+
+
+
+:mod:`Carbon.List` --- List Manager
+===================================
+
+.. module:: Carbon.List
+   :platform: Mac
+   :synopsis: Interface to the List Manager.
+
+
+
+:mod:`Carbon.Menu` --- Menu Manager
+===================================
+
+.. module:: Carbon.Menu
+   :platform: Mac
+   :synopsis: Interface to the Menu Manager.
+
+
+
+:mod:`Carbon.Mlte` --- MultiLingual Text Editor
+===============================================
+
+.. module:: Carbon.Mlte
+   :platform: Mac
+   :synopsis: Interface to the MultiLingual Text Editor.
+
+
+
+:mod:`Carbon.Qd` --- QuickDraw
+==============================
+
+.. module:: Carbon.Qd
+   :platform: Mac
+   :synopsis: Interface to the QuickDraw toolbox.
+
+
+
+:mod:`Carbon.Qdoffs` --- QuickDraw Offscreen
+============================================
+
+.. module:: Carbon.Qdoffs
+   :platform: Mac
+   :synopsis: Interface to the QuickDraw Offscreen APIs.
+
+
+
+:mod:`Carbon.Qt` --- QuickTime
+==============================
+
+.. module:: Carbon.Qt
+   :platform: Mac
+   :synopsis: Interface to the QuickTime toolbox.
+
+
+
+:mod:`Carbon.Res` --- Resource Manager and Handles
+==================================================
+
+.. module:: Carbon.Res
+   :platform: Mac
+   :synopsis: Interface to the Resource Manager and Handles.
+
+
+
+:mod:`Carbon.Scrap` --- Scrap Manager
+=====================================
+
+.. module:: Carbon.Scrap
+   :platform: Mac
+   :synopsis: The Scrap Manager provides basic services for implementing cut & paste and
+              clipboard operations.
+
+
+This module is only fully available on MacOS9 and earlier under classic PPC
+MacPython.  Very limited functionality is available under Carbon MacPython.
+
+.. index:: single: Scrap Manager
+
+The Scrap Manager supports the simplest form of cut & paste operations on the
+Macintosh.  It can be use for both inter- and intra-application clipboard
+operations.
+
+The :mod:`Scrap` module provides low-level access to the functions of the Scrap
+Manager.  It contains the following functions:
+
+
+.. function:: InfoScrap()
+
+   Return current information about the scrap.  The information is encoded as a
+   tuple containing the fields ``(size, handle, count, state, path)``.
+
+   +----------+---------------------------------------------+
+   | Field    | Meaning                                     |
+   +==========+=============================================+
+   | *size*   | Size of the scrap in bytes.                 |
+   +----------+---------------------------------------------+
+   | *handle* | Resource object representing the scrap.     |
+   +----------+---------------------------------------------+
+   | *count*  | Serial number of the scrap contents.        |
+   +----------+---------------------------------------------+
+   | *state*  | Integer; positive if in memory, ``0`` if on |
+   |          | disk, negative if uninitialized.            |
+   +----------+---------------------------------------------+
+   | *path*   | Filename of the scrap when stored on disk.  |
+   +----------+---------------------------------------------+
+
+
+.. seealso::
+
+   `Scrap Manager <http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-109.html>`_
+      Apple's documentation for the Scrap Manager gives a lot of useful information
+      about using the Scrap Manager in applications.
+
+
+
+:mod:`Carbon.Snd` --- Sound Manager
+===================================
+
+.. module:: Carbon.Snd
+   :platform: Mac
+   :synopsis: Interface to the Sound Manager.
+
+
+
+:mod:`Carbon.TE` --- TextEdit
+=============================
+
+.. module:: Carbon.TE
+   :platform: Mac
+   :synopsis: Interface to TextEdit.
+
+
+
+:mod:`Carbon.Win` --- Window Manager
+====================================
+
+.. module:: Carbon.Win
+   :platform: Mac
+   :synopsis: Interface to the Window Manager.
+
+

Doc/library/cgi.rst

@@ -0,0 +1,558 @@
+
+:mod:`cgi` --- Common Gateway Interface support.
+================================================
+
+.. module:: cgi
+   :synopsis: Helpers for running Python scripts via the Common Gateway Interface.
+
+
+.. index::
+   pair: WWW; server
+   pair: CGI; protocol
+   pair: HTTP; protocol
+   pair: MIME; headers
+   single: URL
+   single: Common Gateway Interface
+
+Support module for Common Gateway Interface (CGI) scripts.
+
+This module defines a number of utilities for use by CGI scripts written in
+Python.
+
+
+Introduction
+------------
+
+.. _cgi-intro:
+
+A CGI script is invoked by an HTTP server, usually to process user input
+submitted through an HTML ``<FORM>`` or ``<ISINDEX>`` element.
+
+Most often, CGI scripts live in the server's special :file:`cgi-bin` directory.
+The HTTP server places all sorts of information about the request (such as the
+client's hostname, the requested URL, the query string, and lots of other
+goodies) in the script's shell environment, executes the script, and sends the
+script's output back to the client.
+
+The script's input is connected to the client too, and sometimes the form data
+is read this way; at other times the form data is passed via the "query string"
+part of the URL.  This module is intended to take care of the different cases
+and provide a simpler interface to the Python script.  It also provides a number
+of utilities that help in debugging scripts, and the latest addition is support
+for file uploads from a form (if your browser supports it).
+
+The output of a CGI script should consist of two sections, separated by a blank
+line.  The first section contains a number of headers, telling the client what
+kind of data is following.  Python code to generate a minimal header section
+looks like this::
+
+   print "Content-Type: text/html"     # HTML is following
+   print                               # blank line, end of headers
+
+The second section is usually HTML, which allows the client software to display
+nicely formatted text with header, in-line images, etc. Here's Python code that
+prints a simple piece of HTML::
+
+   print "<TITLE>CGI script output</TITLE>"
+   print "<H1>This is my first CGI script</H1>"
+   print "Hello, world!"
+
+
+.. _using-the-cgi-module:
+
+Using the cgi module
+--------------------
+
+Begin by writing ``import cgi``.  Do not use ``from cgi import *`` --- the
+module defines all sorts of names for its own use or for backward compatibility
+that you don't want in your namespace.
+
+When you write a new script, consider adding the line::
+
+   import cgitb; cgitb.enable()
+
+This activates a special exception handler that will display detailed reports in
+the Web browser if any errors occur.  If you'd rather not show the guts of your
+program to users of your script, you can have the reports saved to files
+instead, with a line like this::
+
+   import cgitb; cgitb.enable(display=0, logdir="/tmp")
+
+It's very helpful to use this feature during script development. The reports
+produced by :mod:`cgitb` provide information that can save you a lot of time in
+tracking down bugs.  You can always remove the ``cgitb`` line later when you
+have tested your script and are confident that it works correctly.
+
+To get at submitted form data, it's best to use the :class:`FieldStorage` class.
+The other classes defined in this module are provided mostly for backward
+compatibility. Instantiate it exactly once, without arguments.  This reads the
+form contents from standard input or the environment (depending on the value of
+various environment variables set according to the CGI standard).  Since it may
+consume standard input, it should be instantiated only once.
+
+The :class:`FieldStorage` instance can be indexed like a Python dictionary, and
+also supports the standard dictionary methods :meth:`has_key` and :meth:`keys`.
+The built-in :func:`len` is also supported.  Form fields containing empty
+strings are ignored and do not appear in the dictionary; to keep such values,
+provide a true value for the optional *keep_blank_values* keyword parameter when
+creating the :class:`FieldStorage` instance.
+
+For instance, the following code (which assumes that the
+:mailheader:`Content-Type` header and blank line have already been printed)
+checks that the fields ``name`` and ``addr`` are both set to a non-empty
+string::
+
+   form = cgi.FieldStorage()
+   if not (form.has_key("name") and form.has_key("addr")):
+       print "<H1>Error</H1>"
+       print "Please fill in the name and addr fields."
+       return
+   print "<p>name:", form["name"].value
+   print "<p>addr:", form["addr"].value
+   ...further form processing here...
+
+Here the fields, accessed through ``form[key]``, are themselves instances of
+:class:`FieldStorage` (or :class:`MiniFieldStorage`, depending on the form
+encoding). The :attr:`value` attribute of the instance yields the string value
+of the field.  The :meth:`getvalue` method returns this string value directly;
+it also accepts an optional second argument as a default to return if the
+requested key is not present.
+
+If the submitted form data contains more than one field with the same name, the
+object retrieved by ``form[key]`` is not a :class:`FieldStorage` or
+:class:`MiniFieldStorage` instance but a list of such instances.  Similarly, in
+this situation, ``form.getvalue(key)`` would return a list of strings. If you
+expect this possibility (when your HTML form contains multiple fields with the
+same name), use the :func:`getlist` function, which always returns a list of
+values (so that you do not need to special-case the single item case).  For
+example, this code concatenates any number of username fields, separated by
+commas::
+
+   value = form.getlist("username")
+   usernames = ",".join(value)
+
+If a field represents an uploaded file, accessing the value via the
+:attr:`value` attribute or the :func:`getvalue` method reads the entire file in
+memory as a string.  This may not be what you want. You can test for an uploaded
+file by testing either the :attr:`filename` attribute or the :attr:`file`
+attribute.  You can then read the data at leisure from the :attr:`file`
+attribute::
+
+   fileitem = form["userfile"]
+   if fileitem.file:
+       # It's an uploaded file; count lines
+       linecount = 0
+       while 1:
+           line = fileitem.file.readline()
+           if not line: break
+           linecount = linecount + 1
+
+The file upload draft standard entertains the possibility of uploading multiple
+files from one field (using a recursive :mimetype:`multipart/\*` encoding).
+When this occurs, the item will be a dictionary-like :class:`FieldStorage` item.
+This can be determined by testing its :attr:`type` attribute, which should be
+:mimetype:`multipart/form-data` (or perhaps another MIME type matching
+:mimetype:`multipart/\*`).  In this case, it can be iterated over recursively
+just like the top-level form object.
+
+When a form is submitted in the "old" format (as the query string or as a single
+data part of type :mimetype:`application/x-www-form-urlencoded`), the items will
+actually be instances of the class :class:`MiniFieldStorage`.  In this case, the
+:attr:`list`, :attr:`file`, and :attr:`filename` attributes are always ``None``.
+
+
+Higher Level Interface
+----------------------
+
+.. versionadded:: 2.2
+
+The previous section explains how to read CGI form data using the
+:class:`FieldStorage` class.  This section describes a higher level interface
+which was added to this class to allow one to do it in a more readable and
+intuitive way.  The interface doesn't make the techniques described in previous
+sections obsolete --- they are still useful to process file uploads efficiently,
+for example.
+
+.. % XXX: Is this true ?
+
+The interface consists of two simple methods. Using the methods you can process
+form data in a generic way, without the need to worry whether only one or more
+values were posted under one name.
+
+In the previous section, you learned to write following code anytime you
+expected a user to post more than one value under one name::
+
+   item = form.getvalue("item")
+   if isinstance(item, list):
+       # The user is requesting more than one item.
+   else:
+       # The user is requesting only one item.
+
+This situation is common for example when a form contains a group of multiple
+checkboxes with the same name::
+
+   <input type="checkbox" name="item" value="1" />
+   <input type="checkbox" name="item" value="2" />
+
+In most situations, however, there's only one form control with a particular
+name in a form and then you expect and need only one value associated with this
+name.  So you write a script containing for example this code::
+
+   user = form.getvalue("user").upper()
+
+The problem with the code is that you should never expect that a client will
+provide valid input to your scripts.  For example, if a curious user appends
+another ``user=foo`` pair to the query string, then the script would crash,
+because in this situation the ``getvalue("user")`` method call returns a list
+instead of a string.  Calling the :meth:`toupper` method on a list is not valid
+(since lists do not have a method of this name) and results in an
+:exc:`AttributeError` exception.
+
+Therefore, the appropriate way to read form data values was to always use the
+code which checks whether the obtained value is a single value or a list of
+values.  That's annoying and leads to less readable scripts.
+
+A more convenient approach is to use the methods :meth:`getfirst` and
+:meth:`getlist` provided by this higher level interface.
+
+
+.. method:: FieldStorage.getfirst(name[, default])
+
+   This method always returns only one value associated with form field *name*.
+   The method returns only the first value in case that more values were posted
+   under such name.  Please note that the order in which the values are received
+   may vary from browser to browser and should not be counted on. [#]_  If no such
+   form field or value exists then the method returns the value specified by the
+   optional parameter *default*.  This parameter defaults to ``None`` if not
+   specified.
+
+
+.. method:: FieldStorage.getlist(name)
+
+   This method always returns a list of values associated with form field *name*.
+   The method returns an empty list if no such form field or value exists for
+   *name*.  It returns a list consisting of one item if only one such value exists.
+
+Using these methods you can write nice compact code::
+
+   import cgi
+   form = cgi.FieldStorage()
+   user = form.getfirst("user", "").upper()    # This way it's safe.
+   for item in form.getlist("item"):
+       do_something(item)
+
+
+Old classes
+-----------
+
+These classes, present in earlier versions of the :mod:`cgi` module, are still
+supported for backward compatibility.  New applications should use the
+:class:`FieldStorage` class.
+
+:class:`SvFormContentDict` stores single value form content as dictionary; it
+assumes each field name occurs in the form only once.
+
+:class:`FormContentDict` stores multiple value form content as a dictionary (the
+form items are lists of values).  Useful if your form contains multiple fields
+with the same name.
+
+Other classes (:class:`FormContent`, :class:`InterpFormContentDict`) are present
+for backwards compatibility with really old applications only. If you still use
+these and would be inconvenienced when they disappeared from a next version of
+this module, drop me a note.
+
+
+.. _functions-in-cgi-module:
+
+Functions
+---------
+
+These are useful if you want more control, or if you want to employ some of the
+algorithms implemented in this module in other circumstances.
+
+
+.. function:: parse(fp[, keep_blank_values[, strict_parsing]])
+
+   Parse a query in the environment or from a file (the file defaults to
+   ``sys.stdin``).  The *keep_blank_values* and *strict_parsing* parameters are
+   passed to :func:`parse_qs` unchanged.
+
+
+.. function:: parse_qs(qs[, keep_blank_values[, strict_parsing]])
+
+   Parse a query string given as a string argument (data of type
+   :mimetype:`application/x-www-form-urlencoded`).  Data are returned as a
+   dictionary.  The dictionary keys are the unique query variable names and the
+   values are lists of values for each name.
+
+   The optional argument *keep_blank_values* is a flag indicating whether blank
+   values in URL encoded queries should be treated as blank strings.   A true value
+   indicates that blanks should be retained as  blank strings.  The default false
+   value indicates that blank values are to be ignored and treated as if they were
+   not included.
+
+   The optional argument *strict_parsing* is a flag indicating what to do with
+   parsing errors.  If false (the default), errors are silently ignored.  If true,
+   errors raise a :exc:`ValueError` exception.
+
+   Use the :func:`urllib.urlencode` function to convert such dictionaries into
+   query strings.
+
+
+.. function:: parse_qsl(qs[, keep_blank_values[, strict_parsing]])
+
+   Parse a query string given as a string argument (data of type
+   :mimetype:`application/x-www-form-urlencoded`).  Data are returned as a list of
+   name, value pairs.
+
+   The optional argument *keep_blank_values* is a flag indicating whether blank
+   values in URL encoded queries should be treated as blank strings.   A true value
+   indicates that blanks should be retained as  blank strings.  The default false
+   value indicates that blank values are to be ignored and treated as if they were
+   not included.
+
+   The optional argument *strict_parsing* is a flag indicating what to do with
+   parsing errors.  If false (the default), errors are silently ignored.  If true,
+   errors raise a :exc:`ValueError` exception.
+
+   Use the :func:`urllib.urlencode` function to convert such lists of pairs into
+   query strings.
+
+
+.. function:: parse_multipart(fp, pdict)
+
+   Parse input of type :mimetype:`multipart/form-data` (for  file uploads).
+   Arguments are *fp* for the input file and *pdict* for a dictionary containing
+   other parameters in the :mailheader:`Content-Type` header.
+
+   Returns a dictionary just like :func:`parse_qs` keys are the field names, each
+   value is a list of values for that field.  This is easy to use but not much good
+   if you are expecting megabytes to be uploaded --- in that case, use the
+   :class:`FieldStorage` class instead which is much more flexible.
+
+   Note that this does not parse nested multipart parts --- use
+   :class:`FieldStorage` for that.
+
+
+.. function:: parse_header(string)
+
+   Parse a MIME header (such as :mailheader:`Content-Type`) into a main value and a
+   dictionary of parameters.
+
+
+.. function:: test()
+
+   Robust test CGI script, usable as main program. Writes minimal HTTP headers and
+   formats all information provided to the script in HTML form.
+
+
+.. function:: print_environ()
+
+   Format the shell environment in HTML.
+
+
+.. function:: print_form(form)
+
+   Format a form in HTML.
+
+
+.. function:: print_directory()
+
+   Format the current directory in HTML.
+
+
+.. function:: print_environ_usage()
+
+   Print a list of useful (used by CGI) environment variables in HTML.
+
+
+.. function:: escape(s[, quote])
+
+   Convert the characters ``'&'``, ``'<'`` and ``'>'`` in string *s* to HTML-safe
+   sequences.  Use this if you need to display text that might contain such
+   characters in HTML.  If the optional flag *quote* is true, the quotation mark
+   character (``'"'``) is also translated; this helps for inclusion in an HTML
+   attribute value, as in ``<A HREF="...">``.  If the value to be quoted might
+   include single- or double-quote characters, or both, consider using the
+   :func:`quoteattr` function in the :mod:`xml.sax.saxutils` module instead.
+
+
+.. _cgi-security:
+
+Caring about security
+---------------------
+
+.. index:: pair: CGI; security
+
+There's one important rule: if you invoke an external program (via the
+:func:`os.system` or :func:`os.popen` functions. or others with similar
+functionality), make very sure you don't pass arbitrary strings received from
+the client to the shell.  This is a well-known security hole whereby clever
+hackers anywhere on the Web can exploit a gullible CGI script to invoke
+arbitrary shell commands.  Even parts of the URL or field names cannot be
+trusted, since the request doesn't have to come from your form!
+
+To be on the safe side, if you must pass a string gotten from a form to a shell
+command, you should make sure the string contains only alphanumeric characters,
+dashes, underscores, and periods.
+
+
+Installing your CGI script on a Unix system
+-------------------------------------------
+
+Read the documentation for your HTTP server and check with your local system
+administrator to find the directory where CGI scripts should be installed;
+usually this is in a directory :file:`cgi-bin` in the server tree.
+
+Make sure that your script is readable and executable by "others"; the Unix file
+mode should be ``0755`` octal (use ``chmod 0755 filename``).  Make sure that the
+first line of the script contains ``#!`` starting in column 1 followed by the
+pathname of the Python interpreter, for instance::
+
+   #!/usr/local/bin/python
+
+Make sure the Python interpreter exists and is executable by "others".
+
+Make sure that any files your script needs to read or write are readable or
+writable, respectively, by "others" --- their mode should be ``0644`` for
+readable and ``0666`` for writable.  This is because, for security reasons, the
+HTTP server executes your script as user "nobody", without any special
+privileges.  It can only read (write, execute) files that everybody can read
+(write, execute).  The current directory at execution time is also different (it
+is usually the server's cgi-bin directory) and the set of environment variables
+is also different from what you get when you log in.  In particular, don't count
+on the shell's search path for executables (:envvar:`PATH`) or the Python module
+search path (:envvar:`PYTHONPATH`) to be set to anything interesting.
+
+If you need to load modules from a directory which is not on Python's default
+module search path, you can change the path in your script, before importing
+other modules.  For example::
+
+   import sys
+   sys.path.insert(0, "/usr/home/joe/lib/python")
+   sys.path.insert(0, "/usr/local/lib/python")
+
+(This way, the directory inserted last will be searched first!)
+
+Instructions for non-Unix systems will vary; check your HTTP server's
+documentation (it will usually have a section on CGI scripts).
+
+
+Testing your CGI script
+-----------------------
+
+Unfortunately, a CGI script will generally not run when you try it from the
+command line, and a script that works perfectly from the command line may fail
+mysteriously when run from the server.  There's one reason why you should still
+test your script from the command line: if it contains a syntax error, the
+Python interpreter won't execute it at all, and the HTTP server will most likely
+send a cryptic error to the client.
+
+Assuming your script has no syntax errors, yet it does not work, you have no
+choice but to read the next section.
+
+
+Debugging CGI scripts
+---------------------
+
+.. index:: pair: CGI; debugging
+
+First of all, check for trivial installation errors --- reading the section
+above on installing your CGI script carefully can save you a lot of time.  If
+you wonder whether you have understood the installation procedure correctly, try
+installing a copy of this module file (:file:`cgi.py`) as a CGI script.  When
+invoked as a script, the file will dump its environment and the contents of the
+form in HTML form. Give it the right mode etc, and send it a request.  If it's
+installed in the standard :file:`cgi-bin` directory, it should be possible to
+send it a request by entering a URL into your browser of the form::
+
+   http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
+
+If this gives an error of type 404, the server cannot find the script -- perhaps
+you need to install it in a different directory.  If it gives another error,
+there's an installation problem that you should fix before trying to go any
+further.  If you get a nicely formatted listing of the environment and form
+content (in this example, the fields should be listed as "addr" with value "At
+Home" and "name" with value "Joe Blow"), the :file:`cgi.py` script has been
+installed correctly.  If you follow the same procedure for your own script, you
+should now be able to debug it.
+
+The next step could be to call the :mod:`cgi` module's :func:`test` function
+from your script: replace its main code with the single statement ::
+
+   cgi.test()
+
+This should produce the same results as those gotten from installing the
+:file:`cgi.py` file itself.
+
+When an ordinary Python script raises an unhandled exception (for whatever
+reason: of a typo in a module name, a file that can't be opened, etc.), the
+Python interpreter prints a nice traceback and exits.  While the Python
+interpreter will still do this when your CGI script raises an exception, most
+likely the traceback will end up in one of the HTTP server's log files, or be
+discarded altogether.
+
+Fortunately, once you have managed to get your script to execute *some* code,
+you can easily send tracebacks to the Web browser using the :mod:`cgitb` module.
+If you haven't done so already, just add the line::
+
+   import cgitb; cgitb.enable()
+
+to the top of your script.  Then try running it again; when a problem occurs,
+you should see a detailed report that will likely make apparent the cause of the
+crash.
+
+If you suspect that there may be a problem in importing the :mod:`cgitb` module,
+you can use an even more robust approach (which only uses built-in modules)::
+
+   import sys
+   sys.stderr = sys.stdout
+   print "Content-Type: text/plain"
+   print
+   ...your code here...
+
+This relies on the Python interpreter to print the traceback.  The content type
+of the output is set to plain text, which disables all HTML processing.  If your
+script works, the raw HTML will be displayed by your client.  If it raises an
+exception, most likely after the first two lines have been printed, a traceback
+will be displayed. Because no HTML interpretation is going on, the traceback
+will be readable.
+
+
+Common problems and solutions
+-----------------------------
+
+* Most HTTP servers buffer the output from CGI scripts until the script is
+  completed.  This means that it is not possible to display a progress report on
+  the client's display while the script is running.
+
+* Check the installation instructions above.
+
+* Check the HTTP server's log files.  (``tail -f logfile`` in a separate window
+  may be useful!)
+
+* Always check a script for syntax errors first, by doing something like
+  ``python script.py``.
+
+* If your script does not have any syntax errors, try adding ``import cgitb;
+  cgitb.enable()`` to the top of the script.
+
+* When invoking external programs, make sure they can be found. Usually, this
+  means using absolute path names --- :envvar:`PATH` is usually not set to a very
+  useful value in a CGI script.
+
+* When reading or writing external files, make sure they can be read or written
+  by the userid under which your CGI script will be running: this is typically the
+  userid under which the web server is running, or some explicitly specified
+  userid for a web server's ``suexec`` feature.
+
+* Don't try to give a CGI script a set-uid mode.  This doesn't work on most
+  systems, and is a security liability as well.
+
+.. rubric:: Footnotes
+
+.. [#] Note that some recent versions of the HTML specification do state what order the
+   field values should be supplied in, but knowing whether a request was
+   received from a conforming browser, or even from a browser at all, is tedious
+   and error-prone.
+

Doc/library/cgihttpserver.rst

@@ -0,0 +1,73 @@
+
+:mod:`CGIHTTPServer` --- CGI-capable HTTP request handler
+=========================================================
+
+.. module:: CGIHTTPServer
+   :synopsis: This module provides a request handler for HTTP servers which can run CGI
+              scripts.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+The :mod:`CGIHTTPServer` module defines a request-handler class, interface
+compatible with :class:`BaseHTTPServer.BaseHTTPRequestHandler` and inherits
+behavior from :class:`SimpleHTTPServer.SimpleHTTPRequestHandler` but can also
+run CGI scripts.
+
+.. note::
+
+   This module can run CGI scripts on Unix and Windows systems; on Mac OS it will
+   only be able to run Python scripts within the same process as itself.
+
+.. note::
+
+   CGI scripts run by the :class:`CGIHTTPRequestHandler` class cannot execute
+   redirects (HTTP code 302), because code 200 (script output follows) is sent
+   prior to execution of the CGI script.  This pre-empts the status code.
+
+The :mod:`CGIHTTPServer` module defines the following class:
+
+
+.. class:: CGIHTTPRequestHandler(request, client_address, server)
+
+   This class is used to serve either files or output of CGI scripts from  the
+   current directory and below. Note that mapping HTTP hierarchic structure to
+   local directory structure is exactly as in
+   :class:`SimpleHTTPServer.SimpleHTTPRequestHandler`.
+
+   The class will however, run the CGI script, instead of serving it as a file, if
+   it guesses it to be a CGI script. Only directory-based CGI are used --- the
+   other common server configuration is to treat special extensions as denoting CGI
+   scripts.
+
+   The :func:`do_GET` and :func:`do_HEAD` functions are modified to run CGI scripts
+   and serve the output, instead of serving files, if the request leads to
+   somewhere below the ``cgi_directories`` path.
+
+The :class:`CGIHTTPRequestHandler` defines the following data member:
+
+
+.. attribute:: CGIHTTPRequestHandler.cgi_directories
+
+   This defaults to ``['/cgi-bin', '/htbin']`` and describes directories to treat
+   as containing CGI scripts.
+
+The :class:`CGIHTTPRequestHandler` defines the following methods:
+
+
+.. method:: CGIHTTPRequestHandler.do_POST()
+
+   This method serves the ``'POST'`` request type, only allowed for CGI scripts.
+   Error 501, "Can only POST to CGI scripts", is output when trying to POST to a
+   non-CGI url.
+
+Note that CGI scripts will be run with UID of user nobody, for security reasons.
+Problems with the CGI script will be translated to error 403.
+
+For example usage, see the implementation of the :func:`test` function.
+
+
+.. seealso::
+
+   Module :mod:`BaseHTTPServer`
+      Base class implementation for Web server and request handler.
+

Doc/library/cgitb.rst

@@ -0,0 +1,64 @@
+
+:mod:`cgitb` --- Traceback manager for CGI scripts
+==================================================
+
+.. module:: cgitb
+   :synopsis: Configurable traceback handler for CGI scripts.
+.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+.. versionadded:: 2.2
+
+.. index::
+   single: CGI; exceptions
+   single: CGI; tracebacks
+   single: exceptions; in CGI scripts
+   single: tracebacks; in CGI scripts
+
+The :mod:`cgitb` module provides a special exception handler for Python scripts.
+(Its name is a bit misleading.  It was originally designed to display extensive
+traceback information in HTML for CGI scripts.  It was later generalized to also
+display this information in plain text.)  After this module is activated, if an
+uncaught exception occurs, a detailed, formatted report will be displayed.  The
+report includes a traceback showing excerpts of the source code for each level,
+as well as the values of the arguments and local variables to currently running
+functions, to help you debug the problem.  Optionally, you can save this
+information to a file instead of sending it to the browser.
+
+To enable this feature, simply add one line to the top of your CGI script::
+
+   import cgitb; cgitb.enable()
+
+The options to the :func:`enable` function control whether the report is
+displayed in the browser and whether the report is logged to a file for later
+analysis.
+
+
+.. function:: enable([display[, logdir[, context[, format]]]])
+
+   .. index:: single: excepthook() (in module sys)
+
+   This function causes the :mod:`cgitb` module to take over the interpreter's
+   default handling for exceptions by setting the value of :attr:`sys.excepthook`.
+
+   The optional argument *display* defaults to ``1`` and can be set to ``0`` to
+   suppress sending the traceback to the browser. If the argument *logdir* is
+   present, the traceback reports are written to files.  The value of *logdir*
+   should be a directory where these files will be placed. The optional argument
+   *context* is the number of lines of context to display around the current line
+   of source code in the traceback; this defaults to ``5``. If the optional
+   argument *format* is ``"html"``, the output is formatted as HTML.  Any other
+   value forces plain text output.  The default value is ``"html"``.
+
+
+.. function:: handler([info])
+
+   This function handles an exception using the default settings (that is, show a
+   report in the browser, but don't log to a file). This can be used when you've
+   caught an exception and want to report it using :mod:`cgitb`.  The optional
+   *info* argument should be a 3-tuple containing an exception type, exception
+   value, and traceback object, exactly like the tuple returned by
+   :func:`sys.exc_info`.  If the *info* argument is not supplied, the current
+   exception is obtained from :func:`sys.exc_info`.
+

Doc/library/chunk.rst

@@ -0,0 +1,130 @@
+
+:mod:`chunk` --- Read IFF chunked data
+======================================
+
+.. module:: chunk
+   :synopsis: Module to read IFF chunks.
+.. moduleauthor:: Sjoerd Mullender <sjoerd@acm.org>
+.. sectionauthor:: Sjoerd Mullender <sjoerd@acm.org>
+
+
+.. index::
+   single: Audio Interchange File Format
+   single: AIFF
+   single: AIFF-C
+   single: Real Media File Format
+   single: RMFF
+
+This module provides an interface for reading files that use EA IFF 85 chunks.
+[#]_  This format is used in at least the Audio Interchange File Format
+(AIFF/AIFF-C) and the Real Media File Format (RMFF).  The WAVE audio file format
+is closely related and can also be read using this module.
+
+A chunk has the following structure:
+
++---------+--------+-------------------------------+
+| Offset  | Length | Contents                      |
++=========+========+===============================+
+| 0       | 4      | Chunk ID                      |
++---------+--------+-------------------------------+
+| 4       | 4      | Size of chunk in big-endian   |
+|         |        | byte order, not including the |
+|         |        | header                        |
++---------+--------+-------------------------------+
+| 8       | *n*    | Data bytes, where *n* is the  |
+|         |        | size given in the preceding   |
+|         |        | field                         |
++---------+--------+-------------------------------+
+| 8 + *n* | 0 or 1 | Pad byte needed if *n* is odd |
+|         |        | and chunk alignment is used   |
++---------+--------+-------------------------------+
+
+The ID is a 4-byte string which identifies the type of chunk.
+
+The size field (a 32-bit value, encoded using big-endian byte order) gives the
+size of the chunk data, not including the 8-byte header.
+
+Usually an IFF-type file consists of one or more chunks.  The proposed usage of
+the :class:`Chunk` class defined here is to instantiate an instance at the start
+of each chunk and read from the instance until it reaches the end, after which a
+new instance can be instantiated. At the end of the file, creating a new
+instance will fail with a :exc:`EOFError` exception.
+
+
+.. class:: Chunk(file[, align, bigendian, inclheader])
+
+   Class which represents a chunk.  The *file* argument is expected to be a
+   file-like object.  An instance of this class is specifically allowed.  The
+   only method that is needed is :meth:`read`.  If the methods :meth:`seek` and
+   :meth:`tell` are present and don't raise an exception, they are also used.
+   If these methods are present and raise an exception, they are expected to not
+   have altered the object.  If the optional argument *align* is true, chunks
+   are assumed to be aligned on 2-byte boundaries.  If *align* is false, no
+   alignment is assumed.  The default value is true.  If the optional argument
+   *bigendian* is false, the chunk size is assumed to be in little-endian order.
+   This is needed for WAVE audio files. The default value is true.  If the
+   optional argument *inclheader* is true, the size given in the chunk header
+   includes the size of the header.  The default value is false.
+
+A :class:`Chunk` object supports the following methods:
+
+
+.. method:: Chunk.getname()
+
+   Returns the name (ID) of the chunk.  This is the first 4 bytes of the chunk.
+
+
+.. method:: Chunk.getsize()
+
+   Returns the size of the chunk.
+
+
+.. method:: Chunk.close()
+
+   Close and skip to the end of the chunk.  This does not close the underlying
+   file.
+
+The remaining methods will raise :exc:`IOError` if called after the
+:meth:`close` method has been called.
+
+
+.. method:: Chunk.isatty()
+
+   Returns ``False``.
+
+
+.. method:: Chunk.seek(pos[, whence])
+
+   Set the chunk's current position.  The *whence* argument is optional and
+   defaults to ``0`` (absolute file positioning); other values are ``1`` (seek
+   relative to the current position) and ``2`` (seek relative to the file's end).
+   There is no return value. If the underlying file does not allow seek, only
+   forward seeks are allowed.
+
+
+.. method:: Chunk.tell()
+
+   Return the current position into the chunk.
+
+
+.. method:: Chunk.read([size])
+
+   Read at most *size* bytes from the chunk (less if the read hits the end of the
+   chunk before obtaining *size* bytes).  If the *size* argument is negative or
+   omitted, read all data until the end of the chunk.  The bytes are returned as a
+   string object.  An empty string is returned when the end of the chunk is
+   encountered immediately.
+
+
+.. method:: Chunk.skip()
+
+   Skip to the end of the chunk.  All further calls to :meth:`read` for the chunk
+   will return ``''``.  If you are not interested in the contents of the chunk,
+   this method should be called so that the file points to the start of the next
+   chunk.
+
+.. rubric:: Footnotes
+
+.. [#] "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic
+   Arts, January 1985.
+

Doc/library/cmath.rst

@@ -0,0 +1,156 @@
+
+:mod:`cmath` --- Mathematical functions for complex numbers
+===========================================================
+
+.. module:: cmath
+   :synopsis: Mathematical functions for complex numbers.
+
+
+This module is always available.  It provides access to mathematical functions
+for complex numbers.  The functions in this module accept integers,
+floating-point numbers or complex numbers as arguments. They will also accept
+any Python object that has either a :meth:`__complex__` or a :meth:`__float__`
+method: these methods are used to convert the object to a complex or
+floating-point number, respectively, and the function is then applied to the
+result of the conversion.
+
+The functions are:
+
+
+.. function:: acos(x)
+
+   Return the arc cosine of *x*. There are two branch cuts: One extends right from
+   1 along the real axis to ∞, continuous from below. The other extends left from
+   -1 along the real axis to -∞, continuous from above.
+
+
+.. function:: acosh(x)
+
+   Return the hyperbolic arc cosine of *x*. There is one branch cut, extending left
+   from 1 along the real axis to -∞, continuous from above.
+
+
+.. function:: asin(x)
+
+   Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
+
+
+.. function:: asinh(x)
+
+   Return the hyperbolic arc sine of *x*. There are two branch cuts, extending
+   left from ``±1j`` to ``±∞j``, both continuous from above. These branch cuts
+   should be considered a bug to be corrected in a future release. The correct
+   branch cuts should extend along the imaginary axis, one from ``1j`` up to
+   ``∞j`` and continuous from the right, and one from ``-1j`` down to ``-∞j``
+   and continuous from the left.
+
+
+.. function:: atan(x)
+
+   Return the arc tangent of *x*. There are two branch cuts: One extends from
+   ``1j`` along the imaginary axis to ``∞j``, continuous from the left. The
+   other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous
+   from the left. (This should probably be changed so the upper cut becomes
+   continuous from the other side.)
+
+
+.. function:: atanh(x)
+
+   Return the hyperbolic arc tangent of *x*. There are two branch cuts: One
+   extends from ``1`` along the real axis to ``∞``, continuous from above. The
+   other extends from ``-1`` along the real axis to ``-∞``, continuous from
+   above. (This should probably be changed so the right cut becomes continuous
+   from the other side.)
+
+
+.. function:: cos(x)
+
+   Return the cosine of *x*.
+
+
+.. function:: cosh(x)
+
+   Return the hyperbolic cosine of *x*.
+
+
+.. function:: exp(x)
+
+   Return the exponential value ``e**x``.
+
+
+.. function:: log(x[, base])
+
+   Returns the logarithm of *x* to the given *base*. If the *base* is not
+   specified, returns the natural logarithm of *x*. There is one branch cut, from 0
+   along the negative real axis to -∞, continuous from above.
+
+   .. versionchanged:: 2.4
+      *base* argument added.
+
+
+.. function:: log10(x)
+
+   Return the base-10 logarithm of *x*. This has the same branch cut as
+   :func:`log`.
+
+
+.. function:: sin(x)
+
+   Return the sine of *x*.
+
+
+.. function:: sinh(x)
+
+   Return the hyperbolic sine of *x*.
+
+
+.. function:: sqrt(x)
+
+   Return the square root of *x*. This has the same branch cut as :func:`log`.
+
+
+.. function:: tan(x)
+
+   Return the tangent of *x*.
+
+
+.. function:: tanh(x)
+
+   Return the hyperbolic tangent of *x*.
+
+The module also defines two mathematical constants:
+
+
+.. data:: pi
+
+   The mathematical constant *pi*, as a float.
+
+
+.. data:: e
+
+   The mathematical constant *e*, as a float.
+
+.. index:: module: math
+
+Note that the selection of functions is similar, but not identical, to that in
+module :mod:`math`.  The reason for having two modules is that some users aren't
+interested in complex numbers, and perhaps don't even know what they are.  They
+would rather have ``math.sqrt(-1)`` raise an exception than return a complex
+number. Also note that the functions defined in :mod:`cmath` always return a
+complex number, even if the answer can be expressed as a real number (in which
+case the complex number has an imaginary part of zero).
+
+A note on branch cuts: They are curves along which the given function fails to
+be continuous.  They are a necessary feature of many complex functions.  It is
+assumed that if you need to compute with complex functions, you will understand
+about branch cuts.  Consult almost any (not too elementary) book on complex
+variables for enlightenment.  For information of the proper choice of branch
+cuts for numerical purposes, a good reference should be the following:
+
+
+.. seealso::
+
+   Kahan, W:  Branch cuts for complex elementary functions; or, Much ado about
+   nothing's sign bit.  In Iserles, A., and Powell, M. (eds.), The state of the art
+   in numerical analysis. Clarendon Press (1987) pp165-211.
+

Doc/library/cmd.rst

@@ -0,0 +1,202 @@
+
+:mod:`cmd` --- Support for line-oriented command interpreters
+=============================================================
+
+.. module:: cmd
+   :synopsis: Build line-oriented command interpreters.
+.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
+
+
+The :class:`Cmd` class provides a simple framework for writing line-oriented
+command interpreters.  These are often useful for test harnesses, administrative
+tools, and prototypes that will later be wrapped in a more sophisticated
+interface.
+
+
+.. class:: Cmd([completekey[, stdin[, stdout]]])
+
+   A :class:`Cmd` instance or subclass instance is a line-oriented interpreter
+   framework.  There is no good reason to instantiate :class:`Cmd` itself; rather,
+   it's useful as a superclass of an interpreter class you define yourself in order
+   to inherit :class:`Cmd`'s methods and encapsulate action methods.
+
+   The optional argument *completekey* is the :mod:`readline` name of a completion
+   key; it defaults to :kbd:`Tab`. If *completekey* is not :const:`None` and
+   :mod:`readline` is available, command completion is done automatically.
+
+   The optional arguments *stdin* and *stdout* specify the  input and output file
+   objects that the Cmd instance or subclass  instance will use for input and
+   output. If not specified, they will default to *sys.stdin* and *sys.stdout*.
+
+   .. versionchanged:: 2.3
+      The *stdin* and *stdout* parameters were added.
+
+
+.. _cmd-objects:
+
+Cmd Objects
+-----------
+
+A :class:`Cmd` instance has the following methods:
+
+
+.. method:: Cmd.cmdloop([intro])
+
+   Repeatedly issue a prompt, accept input, parse an initial prefix off the
+   received input, and dispatch to action methods, passing them the remainder of
+   the line as argument.
+
+   The optional argument is a banner or intro string to be issued before the first
+   prompt (this overrides the :attr:`intro` class member).
+
+   If the :mod:`readline` module is loaded, input will automatically inherit
+   :program:`bash`\ -like history-list editing (e.g. :kbd:`Control-P` scrolls back
+   to the last command, :kbd:`Control-N` forward to the next one, :kbd:`Control-F`
+   moves the cursor to the right non-destructively, :kbd:`Control-B` moves the
+   cursor to the left non-destructively, etc.).
+
+   An end-of-file on input is passed back as the string ``'EOF'``.
+
+   An interpreter instance will recognize a command name ``foo`` if and only if it
+   has a method :meth:`do_foo`.  As a special case, a line beginning with the
+   character ``'?'`` is dispatched to the method :meth:`do_help`.  As another
+   special case, a line beginning with the character ``'!'`` is dispatched to the
+   method :meth:`do_shell` (if such a method is defined).
+
+   This method will return when the :meth:`postcmd` method returns a true value.
+   The *stop* argument to :meth:`postcmd` is the return value from the command's
+   corresponding :meth:`do_\*` method.
+
+   If completion is enabled, completing commands will be done automatically, and
+   completing of commands args is done by calling :meth:`complete_foo` with
+   arguments *text*, *line*, *begidx*, and *endidx*.  *text* is the string prefix
+   we are attempting to match: all returned matches must begin with it. *line* is
+   the current input line with leading whitespace removed, *begidx* and *endidx*
+   are the beginning and ending indexes of the prefix text, which could be used to
+   provide different completion depending upon which position the argument is in.
+
+   All subclasses of :class:`Cmd` inherit a predefined :meth:`do_help`. This
+   method, called with an argument ``'bar'``, invokes the corresponding method
+   :meth:`help_bar`.  With no argument, :meth:`do_help` lists all available help
+   topics (that is, all commands with corresponding :meth:`help_\*` methods), and
+   also lists any undocumented commands.
+
+
+.. method:: Cmd.onecmd(str)
+
+   Interpret the argument as though it had been typed in response to the prompt.
+   This may be overridden, but should not normally need to be; see the
+   :meth:`precmd` and :meth:`postcmd` methods for useful execution hooks.  The
+   return value is a flag indicating whether interpretation of commands by the
+   interpreter should stop.  If there is a :meth:`do_\*` method for the command
+   *str*, the return value of that method is returned, otherwise the return value
+   from the :meth:`default` method is returned.
+
+
+.. method:: Cmd.emptyline()
+
+   Method called when an empty line is entered in response to the prompt. If this
+   method is not overridden, it repeats the last nonempty command entered.
+
+
+.. method:: Cmd.default(line)
+
+   Method called on an input line when the command prefix is not recognized. If
+   this method is not overridden, it prints an error message and returns.
+
+
+.. method:: Cmd.completedefault(text, line, begidx, endidx)
+
+   Method called to complete an input line when no command-specific
+   :meth:`complete_\*` method is available.  By default, it returns an empty list.
+
+
+.. method:: Cmd.precmd(line)
+
+   Hook method executed just before the command line *line* is interpreted, but
+   after the input prompt is generated and issued.  This method is a stub in
+   :class:`Cmd`; it exists to be overridden by subclasses.  The return value is
+   used as the command which will be executed by the :meth:`onecmd` method; the
+   :meth:`precmd` implementation may re-write the command or simply return *line*
+   unchanged.
+
+
+.. method:: Cmd.postcmd(stop, line)
+
+   Hook method executed just after a command dispatch is finished.  This method is
+   a stub in :class:`Cmd`; it exists to be overridden by subclasses.  *line* is the
+   command line which was executed, and *stop* is a flag which indicates whether
+   execution will be terminated after the call to :meth:`postcmd`; this will be the
+   return value of the :meth:`onecmd` method.  The return value of this method will
+   be used as the new value for the internal flag which corresponds to *stop*;
+   returning false will cause interpretation to continue.
+
+
+.. method:: Cmd.preloop()
+
+   Hook method executed once when :meth:`cmdloop` is called.  This method is a stub
+   in :class:`Cmd`; it exists to be overridden by subclasses.
+
+
+.. method:: Cmd.postloop()
+
+   Hook method executed once when :meth:`cmdloop` is about to return. This method
+   is a stub in :class:`Cmd`; it exists to be overridden by subclasses.
+
+Instances of :class:`Cmd` subclasses have some public instance variables:
+
+
+.. attribute:: Cmd.prompt
+
+   The prompt issued to solicit input.
+
+
+.. attribute:: Cmd.identchars
+
+   The string of characters accepted for the command prefix.
+
+
+.. attribute:: Cmd.lastcmd
+
+   The last nonempty command prefix seen.
+
+
+.. attribute:: Cmd.intro
+
+   A string to issue as an intro or banner.  May be overridden by giving the
+   :meth:`cmdloop` method an argument.
+
+
+.. attribute:: Cmd.doc_header
+
+   The header to issue if the help output has a section for documented commands.
+
+
+.. attribute:: Cmd.misc_header
+
+   The header to issue if the help output has a section for miscellaneous  help
+   topics (that is, there are :meth:`help_\*` methods without corresponding
+   :meth:`do_\*` methods).
+
+
+.. attribute:: Cmd.undoc_header
+
+   The header to issue if the help output has a section for undocumented  commands
+   (that is, there are :meth:`do_\*` methods without corresponding :meth:`help_\*`
+   methods).
+
+
+.. attribute:: Cmd.ruler
+
+   The character used to draw separator lines under the help-message headers.  If
+   empty, no ruler line is drawn.  It defaults to ``'='``.
+
+
+.. attribute:: Cmd.use_rawinput
+
+   A flag, defaulting to true.  If true, :meth:`cmdloop` uses :func:`input` to
+   display a prompt and read the next command; if false, :meth:`sys.stdout.write`
+   and :meth:`sys.stdin.readline` are used. (This means that by importing
+   :mod:`readline`, on systems that support it, the interpreter will automatically
+   support :program:`Emacs`\ -like line editing  and command-history keystrokes.)
+

Doc/library/code.rst

@@ -0,0 +1,167 @@
+
+:mod:`code` --- Interpreter base classes
+========================================
+
+.. module:: code
+   :synopsis: Facilities to implement read-eval-print loops.
+
+
+
+The ``code`` module provides facilities to implement read-eval-print loops in
+Python.  Two classes and convenience functions are included which can be used to
+build applications which provide an interactive interpreter prompt.
+
+
+.. class:: InteractiveInterpreter([locals])
+
+   This class deals with parsing and interpreter state (the user's namespace); it
+   does not deal with input buffering or prompting or input file naming (the
+   filename is always passed in explicitly). The optional *locals* argument
+   specifies the dictionary in which code will be executed; it defaults to a newly
+   created dictionary with key ``'__name__'`` set to ``'__console__'`` and key
+   ``'__doc__'`` set to ``None``.
+
+
+.. class:: InteractiveConsole([locals[, filename]])
+
+   Closely emulate the behavior of the interactive Python interpreter. This class
+   builds on :class:`InteractiveInterpreter` and adds prompting using the familiar
+   ``sys.ps1`` and ``sys.ps2``, and input buffering.
+
+
+.. function:: interact([banner[, readfunc[, local]]])
+
+   Convenience function to run a read-eval-print loop.  This creates a new instance
+   of :class:`InteractiveConsole` and sets *readfunc* to be used as the
+   :meth:`raw_input` method, if provided.  If *local* is provided, it is passed to
+   the :class:`InteractiveConsole` constructor for use as the default namespace for
+   the interpreter loop.  The :meth:`interact` method of the instance is then run
+   with *banner* passed as the banner to use, if provided.  The console object is
+   discarded after use.
+
+
+.. function:: compile_command(source[, filename[, symbol]])
+
+   This function is useful for programs that want to emulate Python's interpreter
+   main loop (a.k.a. the read-eval-print loop).  The tricky part is to determine
+   when the user has entered an incomplete command that can be completed by
+   entering more text (as opposed to a complete command or a syntax error).  This
+   function *almost* always makes the same decision as the real interpreter main
+   loop.
+
+   *source* is the source string; *filename* is the optional filename from which
+   source was read, defaulting to ``'<input>'``; and *symbol* is the optional
+   grammar start symbol, which should be either ``'single'`` (the default) or
+   ``'eval'``.
+
+   Returns a code object (the same as ``compile(source, filename, symbol)``) if the
+   command is complete and valid; ``None`` if the command is incomplete; raises
+   :exc:`SyntaxError` if the command is complete and contains a syntax error, or
+   raises :exc:`OverflowError` or :exc:`ValueError` if the command contains an
+   invalid literal.
+
+
+.. _interpreter-objects:
+
+Interactive Interpreter Objects
+-------------------------------
+
+
+.. method:: InteractiveInterpreter.runsource(source[, filename[, symbol]])
+
+   Compile and run some source in the interpreter. Arguments are the same as for
+   :func:`compile_command`; the default for *filename* is ``'<input>'``, and for
+   *symbol* is ``'single'``.  One several things can happen:
+
+   * The input is incorrect; :func:`compile_command` raised an exception
+     (:exc:`SyntaxError` or :exc:`OverflowError`).  A syntax traceback will be
+     printed by calling the :meth:`showsyntaxerror` method.  :meth:`runsource`
+     returns ``False``.
+
+   * The input is incomplete, and more input is required; :func:`compile_command`
+     returned ``None``. :meth:`runsource` returns ``True``.
+
+   * The input is complete; :func:`compile_command` returned a code object.  The
+     code is executed by calling the :meth:`runcode` (which also handles run-time
+     exceptions, except for :exc:`SystemExit`). :meth:`runsource` returns ``False``.
+
+   The return value can be used to decide whether to use ``sys.ps1`` or ``sys.ps2``
+   to prompt the next line.
+
+
+.. method:: InteractiveInterpreter.runcode(code)
+
+   Execute a code object. When an exception occurs, :meth:`showtraceback` is called
+   to display a traceback.  All exceptions are caught except :exc:`SystemExit`,
+   which is allowed to propagate.
+
+   A note about :exc:`KeyboardInterrupt`: this exception may occur elsewhere in
+   this code, and may not always be caught.  The caller should be prepared to deal
+   with it.
+
+
+.. method:: InteractiveInterpreter.showsyntaxerror([filename])
+
+   Display the syntax error that just occurred.  This does not display a stack
+   trace because there isn't one for syntax errors. If *filename* is given, it is
+   stuffed into the exception instead of the default filename provided by Python's
+   parser, because it always uses ``'<string>'`` when reading from a string. The
+   output is written by the :meth:`write` method.
+
+
+.. method:: InteractiveInterpreter.showtraceback()
+
+   Display the exception that just occurred.  We remove the first stack item
+   because it is within the interpreter object implementation. The output is
+   written by the :meth:`write` method.
+
+
+.. method:: InteractiveInterpreter.write(data)
+
+   Write a string to the standard error stream (``sys.stderr``). Derived classes
+   should override this to provide the appropriate output handling as needed.
+
+
+.. _console-objects:
+
+Interactive Console Objects
+---------------------------
+
+The :class:`InteractiveConsole` class is a subclass of
+:class:`InteractiveInterpreter`, and so offers all the methods of the
+interpreter objects as well as the following additions.
+
+
+.. method:: InteractiveConsole.interact([banner])
+
+   Closely emulate the interactive Python console. The optional banner argument
+   specify the banner to print before the first interaction; by default it prints a
+   banner similar to the one printed by the standard Python interpreter, followed
+   by the class name of the console object in parentheses (so as not to confuse
+   this with the real interpreter -- since it's so close!).
+
+
+.. method:: InteractiveConsole.push(line)
+
+   Push a line of source text to the interpreter. The line should not have a
+   trailing newline; it may have internal newlines.  The line is appended to a
+   buffer and the interpreter's :meth:`runsource` method is called with the
+   concatenated contents of the buffer as source.  If this indicates that the
+   command was executed or invalid, the buffer is reset; otherwise, the command is
+   incomplete, and the buffer is left as it was after the line was appended.  The
+   return value is ``True`` if more input is required, ``False`` if the line was
+   dealt with in some way (this is the same as :meth:`runsource`).
+
+
+.. method:: InteractiveConsole.resetbuffer()
+
+   Remove any unhandled source text from the input buffer.
+
+
+.. method:: InteractiveConsole.raw_input([prompt])
+
+   Write a prompt and read a line.  The returned line does not include the trailing
+   newline.  When the user enters the EOF key sequence, :exc:`EOFError` is raised.
+   The base implementation reads from ``sys.stdin``; a subclass may replace this
+   with a different implementation.
+

Doc/library/codeop.rst

@@ -0,0 +1,95 @@
+
+:mod:`codeop` --- Compile Python code
+=====================================
+
+.. module:: codeop
+   :synopsis: Compile (possibly incomplete) Python code.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+.. sectionauthor:: Michael Hudson <mwh@python.net>
+
+
+.. % LaTeXed from excellent doc-string.
+
+The :mod:`codeop` module provides utilities upon which the Python
+read-eval-print loop can be emulated, as is done in the :mod:`code` module.  As
+a result, you probably don't want to use the module directly; if you want to
+include such a loop in your program you probably want to use the :mod:`code`
+module instead.
+
+There are two parts to this job:
+
+#. Being able to tell if a line of input completes a Python  statement: in
+   short, telling whether to print '``>>>``' or '``...``' next.
+
+#. Remembering which future statements the user has entered, so  subsequent
+   input can be compiled with these in effect.
+
+The :mod:`codeop` module provides a way of doing each of these things, and a way
+of doing them both.
+
+To do just the former:
+
+
+.. function:: compile_command(source[, filename[, symbol]])
+
+   Tries to compile *source*, which should be a string of Python code and return a
+   code object if *source* is valid Python code. In that case, the filename
+   attribute of the code object will be *filename*, which defaults to
+   ``'<input>'``. Returns ``None`` if *source* is *not* valid Python code, but is a
+   prefix of valid Python code.
+
+   If there is a problem with *source*, an exception will be raised.
+   :exc:`SyntaxError` is raised if there is invalid Python syntax, and
+   :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.
+
+   The *symbol* argument determines whether *source* is compiled as a statement
+   (``'single'``, the default) or as an expression (``'eval'``).  Any other value
+   will cause :exc:`ValueError` to  be raised.
+
+   **Caveat:** It is possible (but not likely) that the parser stops parsing with a
+   successful outcome before reaching the end of the source; in this case, trailing
+   symbols may be ignored instead of causing an error.  For example, a backslash
+   followed by two newlines may be followed by arbitrary garbage.  This will be
+   fixed once the API for the parser is better.
+
+
+.. class:: Compile()
+
+   Instances of this class have :meth:`__call__` methods identical in signature to
+   the built-in function :func:`compile`, but with the difference that if the
+   instance compiles program text containing a :mod:`__future__` statement, the
+   instance 'remembers' and compiles all subsequent program texts with the
+   statement in force.
+
+
+.. class:: CommandCompiler()
+
+   Instances of this class have :meth:`__call__` methods identical in signature to
+   :func:`compile_command`; the difference is that if the instance compiles program
+   text containing a ``__future__`` statement, the instance 'remembers' and
+   compiles all subsequent program texts with the statement in force.
+
+A note on version compatibility: the :class:`Compile` and
+:class:`CommandCompiler` are new in Python 2.2.  If you want to enable the
+future-tracking features of 2.2 but also retain compatibility with 2.1 and
+earlier versions of Python you can either write ::
+
+   try:
+       from codeop import CommandCompiler
+       compile_command = CommandCompiler()
+       del CommandCompiler
+   except ImportError:
+       from codeop import compile_command
+
+which is a low-impact change, but introduces possibly unwanted global state into
+your program, or you can write::
+
+   try:
+       from codeop import CommandCompiler
+   except ImportError:
+       def CommandCompiler():
+           from codeop import compile_command
+           return compile_command
+
+and then call ``CommandCompiler`` every time you need a fresh compiler object.
+

Doc/library/collections.rst

@@ -0,0 +1,414 @@
+
+:mod:`collections` --- High-performance container datatypes
+===========================================================
+
+.. module:: collections
+   :synopsis: High-performance datatypes
+.. moduleauthor:: Raymond Hettinger <python@rcn.com>
+.. sectionauthor:: Raymond Hettinger <python@rcn.com>
+
+
+.. versionadded:: 2.4
+
+This module implements high-performance container datatypes.  Currently,
+there are two datatypes, :class:`deque` and :class:`defaultdict`, and
+one datatype factory function, :func:`NamedTuple`. Python already
+includes built-in containers, :class:`dict`, :class:`list`,
+:class:`set`, and :class:`tuple`. In addition, the optional :mod:`bsddb`
+module has a :meth:`bsddb.btopen` method that can be used to create in-memory
+or file based ordered dictionaries with string keys.
+
+Future editions of the standard library may include balanced trees and
+ordered dictionaries.
+
+.. versionchanged:: 2.5
+   Added :class:`defaultdict`.
+
+.. versionchanged:: 2.6
+   Added :class:`NamedTuple`.
+
+
+.. _deque-objects:
+
+:class:`deque` objects
+----------------------
+
+
+.. class:: deque([iterable])
+
+   Returns a new deque object initialized left-to-right (using :meth:`append`) with
+   data from *iterable*.  If *iterable* is not specified, the new deque is empty.
+
+   Deques are a generalization of stacks and queues (the name is pronounced "deck"
+   and is short for "double-ended queue").  Deques support thread-safe, memory
+   efficient appends and pops from either side of the deque with approximately the
+   same O(1) performance in either direction.
+
+   Though :class:`list` objects support similar operations, they are optimized for
+   fast fixed-length operations and incur O(n) memory movement costs for
+   ``pop(0)`` and ``insert(0, v)`` operations which change both the size and
+   position of the underlying data representation.
+
+   .. versionadded:: 2.4
+
+Deque objects support the following methods:
+
+
+.. method:: deque.append(x)
+
+   Add *x* to the right side of the deque.
+
+
+.. method:: deque.appendleft(x)
+
+   Add *x* to the left side of the deque.
+
+
+.. method:: deque.clear()
+
+   Remove all elements from the deque leaving it with length 0.
+
+
+.. method:: deque.extend(iterable)
+
+   Extend the right side of the deque by appending elements from the iterable
+   argument.
+
+
+.. method:: deque.extendleft(iterable)
+
+   Extend the left side of the deque by appending elements from *iterable*.  Note,
+   the series of left appends results in reversing the order of elements in the
+   iterable argument.
+
+
+.. method:: deque.pop()
+
+   Remove and return an element from the right side of the deque. If no elements
+   are present, raises an :exc:`IndexError`.
+
+
+.. method:: deque.popleft()
+
+   Remove and return an element from the left side of the deque. If no elements are
+   present, raises an :exc:`IndexError`.
+
+
+.. method:: deque.remove(value)
+
+   Removed the first occurrence of *value*.  If not found, raises a
+   :exc:`ValueError`.
+
+   .. versionadded:: 2.5
+
+
+.. method:: deque.rotate(n)
+
+   Rotate the deque *n* steps to the right.  If *n* is negative, rotate to the
+   left.  Rotating one step to the right is equivalent to:
+   ``d.appendleft(d.pop())``.
+
+In addition to the above, deques support iteration, pickling, ``len(d)``,
+``reversed(d)``, ``copy.copy(d)``, ``copy.deepcopy(d)``, membership testing with
+the :keyword:`in` operator, and subscript references such as ``d[-1]``.
+
+Example::
+
+   >>> from collections import deque
+   >>> d = deque('ghi')                 # make a new deque with three items
+   >>> for elem in d:                   # iterate over the deque's elements
+   ...     print elem.upper()	
+   G
+   H
+   I
+
+   >>> d.append('j')                    # add a new entry to the right side
+   >>> d.appendleft('f')                # add a new entry to the left side
+   >>> d                                # show the representation of the deque
+   deque(['f', 'g', 'h', 'i', 'j'])
+
+   >>> d.pop()                          # return and remove the rightmost item
+   'j'
+   >>> d.popleft()                      # return and remove the leftmost item
+   'f'
+   >>> list(d)                          # list the contents of the deque
+   ['g', 'h', 'i']
+   >>> d[0]                             # peek at leftmost item
+   'g'
+   >>> d[-1]                            # peek at rightmost item
+   'i'
+
+   >>> list(reversed(d))                # list the contents of a deque in reverse
+   ['i', 'h', 'g']
+   >>> 'h' in d                         # search the deque
+   True
+   >>> d.extend('jkl')                  # add multiple elements at once
+   >>> d
+   deque(['g', 'h', 'i', 'j', 'k', 'l'])
+   >>> d.rotate(1)                      # right rotation
+   >>> d
+   deque(['l', 'g', 'h', 'i', 'j', 'k'])
+   >>> d.rotate(-1)                     # left rotation
+   >>> d
+   deque(['g', 'h', 'i', 'j', 'k', 'l'])
+
+   >>> deque(reversed(d))               # make a new deque in reverse order
+   deque(['l', 'k', 'j', 'i', 'h', 'g'])
+   >>> d.clear()                        # empty the deque
+   >>> d.pop()                          # cannot pop from an empty deque
+   Traceback (most recent call last):
+     File "<pyshell#6>", line 1, in -toplevel-
+       d.pop()
+   IndexError: pop from an empty deque
+
+   >>> d.extendleft('abc')              # extendleft() reverses the input order
+   >>> d
+   deque(['c', 'b', 'a'])
+
+
+.. _deque-recipes:
+
+Recipes
+^^^^^^^
+
+This section shows various approaches to working with deques.
+
+The :meth:`rotate` method provides a way to implement :class:`deque` slicing and
+deletion.  For example, a pure python implementation of ``del d[n]`` relies on
+the :meth:`rotate` method to position elements to be popped::
+
+   def delete_nth(d, n):
+       d.rotate(-n)
+       d.popleft()
+       d.rotate(n)
+
+To implement :class:`deque` slicing, use a similar approach applying
+:meth:`rotate` to bring a target element to the left side of the deque. Remove
+old entries with :meth:`popleft`, add new entries with :meth:`extend`, and then
+reverse the rotation.
+
+With minor variations on that approach, it is easy to implement Forth style
+stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
+``rot``, and ``roll``.
+
+A roundrobin task server can be built from a :class:`deque` using
+:meth:`popleft` to select the current task and :meth:`append` to add it back to
+the tasklist if the input stream is not exhausted::
+
+   >>> def roundrobin(*iterables):
+   ...     pending = deque(iter(i) for i in iterables)
+   ...     while pending:
+   ...         task = pending.popleft()
+   ...         try:
+   ...             yield next(task)
+   ...         except StopIteration:
+   ...             continue
+   ...         pending.append(task)
+   ...
+   >>> for value in roundrobin('abc', 'd', 'efgh'):
+   ...     print value
+
+   a
+   d
+   e
+   b
+   f
+   c
+   g
+   h
+
+
+Multi-pass data reduction algorithms can be succinctly expressed and efficiently
+coded by extracting elements with multiple calls to :meth:`popleft`, applying
+the reduction function, and calling :meth:`append` to add the result back to the
+queue.
+
+For example, building a balanced binary tree of nested lists entails reducing
+two adjacent nodes into one by grouping them in a list::
+
+   >>> def maketree(iterable):
+   ...     d = deque(iterable)
+   ...     while len(d) > 1:
+   ...         pair = [d.popleft(), d.popleft()]
+   ...         d.append(pair)
+   ...     return list(d)
+   ...
+   >>> print maketree('abcdefgh')
+   [[[['a', 'b'], ['c', 'd']], [['e', 'f'], ['g', 'h']]]]
+
+
+
+.. _defaultdict-objects:
+
+:class:`defaultdict` objects
+----------------------------
+
+
+.. class:: defaultdict([default_factory[, ...]])
+
+   Returns a new dictionary-like object.  :class:`defaultdict` is a subclass of the
+   builtin :class:`dict` class.  It overrides one method and adds one writable
+   instance variable.  The remaining functionality is the same as for the
+   :class:`dict` class and is not documented here.
+
+   The first argument provides the initial value for the :attr:`default_factory`
+   attribute; it defaults to ``None``. All remaining arguments are treated the same
+   as if they were passed to the :class:`dict` constructor, including keyword
+   arguments.
+
+   .. versionadded:: 2.5
+
+:class:`defaultdict` objects support the following method in addition to the
+standard :class:`dict` operations:
+
+
+.. method:: defaultdict.__missing__(key)
+
+   If the :attr:`default_factory` attribute is ``None``, this raises an
+   :exc:`KeyError` exception with the *key* as argument.
+
+   If :attr:`default_factory` is not ``None``, it is called without arguments to
+   provide a default value for the given *key*, this value is inserted in the
+   dictionary for the *key*, and returned.
+
+   If calling :attr:`default_factory` raises an exception this exception is
+   propagated unchanged.
+
+   This method is called by the :meth:`__getitem__` method of the :class:`dict`
+   class when the requested key is not found; whatever it returns or raises is then
+   returned or raised by :meth:`__getitem__`.
+
+:class:`defaultdict` objects support the following instance variable:
+
+
+.. attribute:: defaultdict.default_factory
+
+   This attribute is used by the :meth:`__missing__` method; it is initialized from
+   the first argument to the constructor, if present, or to ``None``,  if absent.
+
+
+.. _defaultdict-examples:
+
+:class:`defaultdict` Examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Using :class:`list` as the :attr:`default_factory`, it is easy to group a
+sequence of key-value pairs into a dictionary of lists::
+
+   >>> s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)]
+   >>> d = defaultdict(list)
+   >>> for k, v in s:
+   ...     d[k].append(v)
+   ...
+   >>> d.items()
+   [('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
+
+When each key is encountered for the first time, it is not already in the
+mapping; so an entry is automatically created using the :attr:`default_factory`
+function which returns an empty :class:`list`.  The :meth:`list.append`
+operation then attaches the value to the new list.  When keys are encountered
+again, the look-up proceeds normally (returning the list for that key) and the
+:meth:`list.append` operation adds another value to the list. This technique is
+simpler and faster than an equivalent technique using :meth:`dict.setdefault`::
+
+   >>> d = {}
+   >>> for k, v in s:
+   ...     d.setdefault(k, []).append(v)
+   ...
+   >>> d.items()
+   [('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
+
+Setting the :attr:`default_factory` to :class:`int` makes the
+:class:`defaultdict` useful for counting (like a bag or multiset in other
+languages)::
+
+   >>> s = 'mississippi'
+   >>> d = defaultdict(int)
+   >>> for k in s:
+   ...     d[k] += 1
+   ...
+   >>> d.items()
+   [('i', 4), ('p', 2), ('s', 4), ('m', 1)]
+
+When a letter is first encountered, it is missing from the mapping, so the
+:attr:`default_factory` function calls :func:`int` to supply a default count of
+zero.  The increment operation then builds up the count for each letter.
+
+The function :func:`int` which always returns zero is just a special case of
+constant functions.  A faster and more flexible way to create constant functions
+is to use a lambda function which can supply any constant value (not just
+zero)::
+
+   >>> def constant_factory(value):
+   ...     return lambda: value
+   >>> d = defaultdict(constant_factory('<missing>'))
+   >>> d.update(name='John', action='ran')
+   >>> '%(name)s %(action)s to %(object)s' % d
+   'John ran to <missing>'
+
+Setting the :attr:`default_factory` to :class:`set` makes the
+:class:`defaultdict` useful for building a dictionary of sets::
+
+   >>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)]
+   >>> d = defaultdict(set)
+   >>> for k, v in s:
+   ...     d[k].add(v)
+   ...
+   >>> d.items()
+   [('blue', set([2, 4])), ('red', set([1, 3]))]
+
+
+.. _named-tuple-factory:
+
+:func:`NamedTuple` datatype factory function
+--------------------------------------------
+
+
+.. function:: NamedTuple(typename, fieldnames)
+
+   Returns a new tuple subclass named *typename*.  The new subclass is used to
+   create tuple-like objects that have fields accessable by attribute lookup as
+   well as being indexable and iterable.  Instances of the subclass also have a
+   helpful docstring (with typename and fieldnames) and a helpful :meth:`__repr__`
+   method which lists the tuple contents in a ``name=value`` format.
+
+   .. versionadded:: 2.6
+
+   The *fieldnames* are specified in a single string and are separated by spaces.
+   Any valid Python identifier may be used for a field name.
+
+   Example::
+
+      >>> Point = NamedTuple('Point', 'x y')
+      >>> Point.__doc__           # docstring for the new datatype
+      'Point(x, y)'
+      >>> p = Point(11, y=22)     # instantiate with positional or keyword arguments
+      >>> p[0] + p[1]             # works just like the tuple (11, 22)
+      33
+      >>> x, y = p                # unpacks just like a tuple
+      >>> x, y
+      (11, 22)
+      >>> p.x + p.y               # fields also accessable by name
+      33
+      >>> p                       # readable __repr__ with name=value style
+      Point(x=11, y=22)  
+
+   The use cases are the same as those for tuples.  The named factories assign
+   meaning to each tuple position and allow for more readable, self-documenting
+   code.  Named tuples can also be used to assign field names  to tuples returned
+   by the :mod:`csv` or :mod:`sqlite3` modules. For example::
+
+      from itertools import starmap
+      import csv
+      EmployeeRecord = NamedTuple('EmployeeRecord', 'name age title department paygrade')
+      for record in starmap(EmployeeRecord, csv.reader(open("employees.csv", "rb"))):
+          print record
+
+   To cast an individual record stored as :class:`list`, :class:`tuple`, or some
+   other iterable type, use the star-operator to unpack the values::
+
+      >>> Color = NamedTuple('Color', 'name code')
+      >>> m = dict(red=1, green=2, blue=3)
+      >>> print Color(*m.popitem())
+      Color(name='blue', code=3)
+

Doc/library/colorpicker.rst

@@ -0,0 +1,23 @@
+
+:mod:`ColorPicker` --- Color selection dialog
+=============================================
+
+.. module:: ColorPicker
+   :platform: Mac
+   :synopsis: Interface to the standard color selection dialog.
+.. moduleauthor:: Just van Rossum <just@letterror.com>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+The :mod:`ColorPicker` module provides access to the standard color picker
+dialog.
+
+
+.. function:: GetColor(prompt, rgb)
+
+   Show a standard color selection dialog and allow the user to select a color.
+   The user is given instruction by the *prompt* string, and the default color is
+   set to *rgb*.  *rgb* must be a tuple giving the red, green, and blue components
+   of the color. :func:`GetColor` returns a tuple giving the user's selected color
+   and a flag indicating whether they accepted the selection of cancelled.
+

Doc/library/colorsys.rst

@@ -0,0 +1,60 @@
+
+:mod:`colorsys` --- Conversions between color systems
+=====================================================
+
+.. module:: colorsys
+   :synopsis: Conversion functions between RGB and other color systems.
+.. sectionauthor:: David Ascher <da@python.net>
+
+
+The :mod:`colorsys` module defines bidirectional conversions of color values
+between colors expressed in the RGB (Red Green Blue) color space used in
+computer monitors and three other coordinate systems: YIQ, HLS (Hue Lightness
+Saturation) and HSV (Hue Saturation Value).  Coordinates in all of these color
+spaces are floating point values.  In the YIQ space, the Y coordinate is between
+0 and 1, but the I and Q coordinates can be positive or negative.  In all other
+spaces, the coordinates are all between 0 and 1.
+
+More information about color spaces can be found at
+http://www.poynton.com/ColorFAQ.html.
+
+The :mod:`colorsys` module defines the following functions:
+
+
+.. function:: rgb_to_yiq(r, g, b)
+
+   Convert the color from RGB coordinates to YIQ coordinates.
+
+
+.. function:: yiq_to_rgb(y, i, q)
+
+   Convert the color from YIQ coordinates to RGB coordinates.
+
+
+.. function:: rgb_to_hls(r, g, b)
+
+   Convert the color from RGB coordinates to HLS coordinates.
+
+
+.. function:: hls_to_rgb(h, l, s)
+
+   Convert the color from HLS coordinates to RGB coordinates.
+
+
+.. function:: rgb_to_hsv(r, g, b)
+
+   Convert the color from RGB coordinates to HSV coordinates.
+
+
+.. function:: hsv_to_rgb(h, s, v)
+
+   Convert the color from HSV coordinates to RGB coordinates.
+
+Example::
+
+   >>> import colorsys
+   >>> colorsys.rgb_to_hsv(.3, .4, .2)
+   (0.25, 0.5, 0.4)
+   >>> colorsys.hsv_to_rgb(0.25, 0.5, 0.4)
+   (0.3, 0.4, 0.2)
+

Doc/library/commands.rst

@@ -0,0 +1,53 @@
+
+:mod:`commands` --- Utilities for running commands
+==================================================
+
+.. module:: commands
+   :platform: Unix
+   :synopsis: Utility functions for running external commands.
+.. sectionauthor:: Sue Williams <sbw@provis.com>
+
+
+The :mod:`commands` module contains wrapper functions for :func:`os.popen` which
+take a system command as a string and return any output generated by the command
+and, optionally, the exit status.
+
+The :mod:`subprocess` module provides more powerful facilities for spawning new
+processes and retrieving their results.  Using the :mod:`subprocess` module is
+preferable to using the :mod:`commands` module.
+
+The :mod:`commands` module defines the following functions:
+
+
+.. function:: getstatusoutput(cmd)
+
+   Execute the string *cmd* in a shell with :func:`os.popen` and return a 2-tuple
+   ``(status, output)``.  *cmd* is actually run as ``{ cmd ; } 2>&1``, so that the
+   returned output will contain output or error messages. A trailing newline is
+   stripped from the output. The exit status for the command can be interpreted
+   according to the rules for the C function :cfunc:`wait`.
+
+
+.. function:: getoutput(cmd)
+
+   Like :func:`getstatusoutput`, except the exit status is ignored and the return
+   value is a string containing the command's output.
+
+Example::
+
+   >>> import commands
+   >>> commands.getstatusoutput('ls /bin/ls')
+   (0, '/bin/ls')
+   >>> commands.getstatusoutput('cat /bin/junk')
+   (256, 'cat: /bin/junk: No such file or directory')
+   >>> commands.getstatusoutput('/bin/junk')
+   (256, 'sh: /bin/junk: not found')
+   >>> commands.getoutput('ls /bin/ls')
+   '/bin/ls'
+
+
+.. seealso::
+
+   Module :mod:`subprocess`
+      Module for spawning and managing subprocesses.
+

Doc/library/compileall.rst

@@ -0,0 +1,57 @@
+
+:mod:`compileall` --- Byte-compile Python libraries
+===================================================
+
+.. module:: compileall
+   :synopsis: Tools for byte-compiling all Python source files in a directory tree.
+
+
+This module provides some utility functions to support installing Python
+libraries.  These functions compile Python source files in a directory tree,
+allowing users without permission to write to the libraries to take advantage of
+cached byte-code files.
+
+The source file for this module may also be used as a script to compile Python
+sources in directories named on the command line or in ``sys.path``.
+
+
+.. function:: compile_dir(dir[, maxlevels[, ddir[, force[,  rx[, quiet]]]]])
+
+   Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
+   files along the way.  The *maxlevels* parameter is used to limit the depth of
+   the recursion; it defaults to ``10``.  If *ddir* is given, it is used as the
+   base path from  which the filenames used in error messages will be generated.
+   If *force* is true, modules are re-compiled even if the timestamps are up to
+   date.
+
+   If *rx* is given, it specifies a regular expression of file names to exclude
+   from the search; that expression is searched for in the full path.
+
+   If *quiet* is true, nothing is printed to the standard output in normal
+   operation.
+
+
+.. function:: compile_path([skip_curdir[, maxlevels[, force]]])
+
+   Byte-compile all the :file:`.py` files found along ``sys.path``. If
+   *skip_curdir* is true (the default), the current directory is not included in
+   the search.  The *maxlevels* and *force* parameters default to ``0`` and are
+   passed to the :func:`compile_dir` function.
+
+To force a recompile of all the :file:`.py` files in the :file:`Lib/`
+subdirectory and all its subdirectories::
+
+   import compileall
+
+   compileall.compile_dir('Lib/', force=True)
+
+   # Perform same compilation, excluding files in .svn directories.
+   import re
+   compileall.compile_dir('Lib/', rx=re.compile('/[.]svn'), force=True)
+
+
+.. seealso::
+
+   Module :mod:`py_compile`
+      Byte-compile a single source file.
+

Doc/library/configparser.rst

@@ -0,0 +1,361 @@
+
+:mod:`ConfigParser` --- Configuration file parser
+=================================================
+
+.. module:: ConfigParser
+   :synopsis: Configuration file parser.
+.. moduleauthor:: Ken Manheimer <klm@zope.com>
+.. moduleauthor:: Barry Warsaw <bwarsaw@python.org>
+.. moduleauthor:: Eric S. Raymond <esr@thyrsus.com>
+.. sectionauthor:: Christopher G. Petrilli <petrilli@amber.org>
+
+
+.. index::
+   pair: .ini; file
+   pair: configuration; file
+   single: ini file
+   single: Windows ini file
+
+This module defines the class :class:`ConfigParser`.   The :class:`ConfigParser`
+class implements a basic configuration file parser language which provides a
+structure similar to what you would find on Microsoft Windows INI files.  You
+can use this to write Python programs which can be customized by end users
+easily.
+
+.. warning::
+
+   This library does *not* interpret or write the value-type prefixes used in the
+   Windows Registry extended version of INI syntax.
+
+The configuration file consists of sections, led by a ``[section]`` header and
+followed by ``name: value`` entries, with continuations in the style of
+:rfc:`822`; ``name=value`` is also accepted.  Note that leading whitespace is
+removed from values. The optional values can contain format strings which refer
+to other values in the same section, or values in a special ``DEFAULT`` section.
+Additional defaults can be provided on initialization and retrieval.  Lines
+beginning with ``'#'`` or ``';'`` are ignored and may be used to provide
+comments.
+
+For example::
+
+   [My Section]
+   foodir: %(dir)s/whatever
+   dir=frob
+
+would resolve the ``%(dir)s`` to the value of ``dir`` (``frob`` in this case).
+All reference expansions are done on demand.
+
+Default values can be specified by passing them into the :class:`ConfigParser`
+constructor as a dictionary.  Additional defaults  may be passed into the
+:meth:`get` method which will override all others.
+
+Sections are normally stored in a builtin dictionary. An alternative dictionary
+type can be passed to the :class:`ConfigParser` constructor. For example, if a
+dictionary type is passed that sorts its keys, the sections will be sorted on
+write-back, as will be the keys within each section.
+
+
+.. class:: RawConfigParser([defaults[, dict_type]])
+
+   The basic configuration object.  When *defaults* is given, it is initialized
+   into the dictionary of intrinsic defaults.  When *dict_type* is given, it will
+   be used to create the dictionary objects for the list of sections, for the
+   options within a section, and for the default values. This class does not
+   support the magical interpolation behavior.
+
+   .. versionadded:: 2.3
+
+   .. versionchanged:: 2.6
+      *dict_type* was added.
+
+
+.. class:: ConfigParser([defaults])
+
+   Derived class of :class:`RawConfigParser` that implements the magical
+   interpolation feature and adds optional arguments to the :meth:`get` and
+   :meth:`items` methods.  The values in *defaults* must be appropriate for the
+   ``%()s`` string interpolation.  Note that *__name__* is an intrinsic default;
+   its value is the section name, and will override any value provided in
+   *defaults*.
+
+   All option names used in interpolation will be passed through the
+   :meth:`optionxform` method just like any other option name reference.  For
+   example, using the default implementation of :meth:`optionxform` (which converts
+   option names to lower case), the values ``foo %(bar)s`` and ``foo %(BAR)s`` are
+   equivalent.
+
+
+.. class:: SafeConfigParser([defaults])
+
+   Derived class of :class:`ConfigParser` that implements a more-sane variant of
+   the magical interpolation feature.  This implementation is more predictable as
+   well. New applications should prefer this version if they don't need to be
+   compatible with older versions of Python.
+
+   .. % XXX Need to explain what's safer/more predictable about it.
+
+   .. versionadded:: 2.3
+
+
+.. exception:: NoSectionError
+
+   Exception raised when a specified section is not found.
+
+
+.. exception:: DuplicateSectionError
+
+   Exception raised if :meth:`add_section` is called with the name of a section
+   that is already present.
+
+
+.. exception:: NoOptionError
+
+   Exception raised when a specified option is not found in the specified  section.
+
+
+.. exception:: InterpolationError
+
+   Base class for exceptions raised when problems occur performing string
+   interpolation.
+
+
+.. exception:: InterpolationDepthError
+
+   Exception raised when string interpolation cannot be completed because the
+   number of iterations exceeds :const:`MAX_INTERPOLATION_DEPTH`. Subclass of
+   :exc:`InterpolationError`.
+
+
+.. exception:: InterpolationMissingOptionError
+
+   Exception raised when an option referenced from a value does not exist. Subclass
+   of :exc:`InterpolationError`.
+
+   .. versionadded:: 2.3
+
+
+.. exception:: InterpolationSyntaxError
+
+   Exception raised when the source text into which substitutions are made does not
+   conform to the required syntax. Subclass of :exc:`InterpolationError`.
+
+   .. versionadded:: 2.3
+
+
+.. exception:: MissingSectionHeaderError
+
+   Exception raised when attempting to parse a file which has no section headers.
+
+
+.. exception:: ParsingError
+
+   Exception raised when errors occur attempting to parse a file.
+
+
+.. data:: MAX_INTERPOLATION_DEPTH
+
+   The maximum depth for recursive interpolation for :meth:`get` when the *raw*
+   parameter is false.  This is relevant only for the :class:`ConfigParser` class.
+
+
+.. seealso::
+
+   Module :mod:`shlex`
+      Support for a creating Unix shell-like mini-languages which can be used as an
+      alternate format for application configuration files.
+
+
+.. _rawconfigparser-objects:
+
+RawConfigParser Objects
+-----------------------
+
+:class:`RawConfigParser` instances have the following methods:
+
+
+.. method:: RawConfigParser.defaults()
+
+   Return a dictionary containing the instance-wide defaults.
+
+
+.. method:: RawConfigParser.sections()
+
+   Return a list of the sections available; ``DEFAULT`` is not included in the
+   list.
+
+
+.. method:: RawConfigParser.add_section(section)
+
+   Add a section named *section* to the instance.  If a section by the given name
+   already exists, :exc:`DuplicateSectionError` is raised.
+
+
+.. method:: RawConfigParser.has_section(section)
+
+   Indicates whether the named section is present in the configuration. The
+   ``DEFAULT`` section is not acknowledged.
+
+
+.. method:: RawConfigParser.options(section)
+
+   Returns a list of options available in the specified *section*.
+
+
+.. method:: RawConfigParser.has_option(section, option)
+
+   If the given section exists, and contains the given option, return
+   :const:`True`; otherwise return :const:`False`.
+
+   .. versionadded:: 1.6
+
+
+.. method:: RawConfigParser.read(filenames)
+
+   Attempt to read and parse a list of filenames, returning a list of filenames
+   which were successfully parsed.  If *filenames* is a string or Unicode string,
+   it is treated as a single filename. If a file named in *filenames* cannot be
+   opened, that file will be ignored.  This is designed so that you can specify a
+   list of potential configuration file locations (for example, the current
+   directory, the user's home directory, and some system-wide directory), and all
+   existing configuration files in the list will be read.  If none of the named
+   files exist, the :class:`ConfigParser` instance will contain an empty dataset.
+   An application which requires initial values to be loaded from a file should
+   load the required file or files using :meth:`readfp` before calling :meth:`read`
+   for any optional files::
+
+      import ConfigParser, os
+
+      config = ConfigParser.ConfigParser()
+      config.readfp(open('defaults.cfg'))
+      config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
+
+   .. versionchanged:: 2.4
+      Returns list of successfully parsed filenames.
+
+
+.. method:: RawConfigParser.readfp(fp[, filename])
+
+   Read and parse configuration data from the file or file-like object in *fp*
+   (only the :meth:`readline` method is used).  If *filename* is omitted and *fp*
+   has a :attr:`name` attribute, that is used for *filename*; the default is
+   ``<???>``.
+
+
+.. method:: RawConfigParser.get(section, option)
+
+   Get an *option* value for the named *section*.
+
+
+.. method:: RawConfigParser.getint(section, option)
+
+   A convenience method which coerces the *option* in the specified *section* to an
+   integer.
+
+
+.. method:: RawConfigParser.getfloat(section, option)
+
+   A convenience method which coerces the *option* in the specified *section* to a
+   floating point number.
+
+
+.. method:: RawConfigParser.getboolean(section, option)
+
+   A convenience method which coerces the *option* in the specified *section* to a
+   Boolean value.  Note that the accepted values for the option are ``"1"``,
+   ``"yes"``, ``"true"``, and ``"on"``, which cause this method to return ``True``,
+   and ``"0"``, ``"no"``, ``"false"``, and ``"off"``, which cause it to return
+   ``False``.  These string values are checked in a case-insensitive manner.  Any
+   other value will cause it to raise :exc:`ValueError`.
+
+
+.. method:: RawConfigParser.items(section)
+
+   Return a list of ``(name, value)`` pairs for each option in the given *section*.
+
+
+.. method:: RawConfigParser.set(section, option, value)
+
+   If the given section exists, set the given option to the specified value;
+   otherwise raise :exc:`NoSectionError`.  While it is possible to use
+   :class:`RawConfigParser` (or :class:`ConfigParser` with *raw* parameters set to
+   true) for *internal* storage of non-string values, full functionality (including
+   interpolation and output to files) can only be achieved using string values.
+
+   .. versionadded:: 1.6
+
+
+.. method:: RawConfigParser.write(fileobject)
+
+   Write a representation of the configuration to the specified file object.  This
+   representation can be parsed by a future :meth:`read` call.
+
+   .. versionadded:: 1.6
+
+
+.. method:: RawConfigParser.remove_option(section, option)
+
+   Remove the specified *option* from the specified *section*. If the section does
+   not exist, raise :exc:`NoSectionError`.  If the option existed to be removed,
+   return :const:`True`; otherwise return :const:`False`.
+
+   .. versionadded:: 1.6
+
+
+.. method:: RawConfigParser.remove_section(section)
+
+   Remove the specified *section* from the configuration. If the section in fact
+   existed, return ``True``. Otherwise return ``False``.
+
+
+.. method:: RawConfigParser.optionxform(option)
+
+   Transforms the option name *option* as found in an input file or as passed in by
+   client code to the form that should be used in the internal structures.  The
+   default implementation returns a lower-case version of *option*; subclasses may
+   override this or client code can set an attribute of this name on instances to
+   affect this behavior.  Setting this to :func:`str`, for example, would make
+   option names case sensitive.
+
+
+.. _configparser-objects:
+
+ConfigParser Objects
+--------------------
+
+The :class:`ConfigParser` class extends some methods of the
+:class:`RawConfigParser` interface, adding some optional arguments.
+
+
+.. method:: ConfigParser.get(section, option[, raw[, vars]])
+
+   Get an *option* value for the named *section*.  All the ``'%'`` interpolations
+   are expanded in the return values, based on the defaults passed into the
+   constructor, as well as the options *vars* provided, unless the *raw* argument
+   is true.
+
+
+.. method:: ConfigParser.items(section[, raw[, vars]])
+
+   Return a list of ``(name, value)`` pairs for each option in the given *section*.
+   Optional arguments have the same meaning as for the :meth:`get` method.
+
+   .. versionadded:: 2.3
+
+
+.. _safeconfigparser-objects:
+
+SafeConfigParser Objects
+------------------------
+
+The :class:`SafeConfigParser` class implements the same extended interface as
+:class:`ConfigParser`, with the following addition:
+
+
+.. method:: SafeConfigParser.set(section, option, value)
+
+   If the given section exists, set the given option to the specified value;
+   otherwise raise :exc:`NoSectionError`.  *value* must be a string (:class:`str`
+   or :class:`unicode`); if not, :exc:`TypeError` is raised.
+
+   .. versionadded:: 2.4
+

Doc/library/constants.rst

@@ -0,0 +1,42 @@
+
+Built-in Constants
+==================
+
+A small number of constants live in the built-in namespace.  They are:
+
+
+.. data:: False
+
+   The false value of the :class:`bool` type.
+
+   .. versionadded:: 2.3
+
+
+.. data:: True
+
+   The true value of the :class:`bool` type.
+
+   .. versionadded:: 2.3
+
+
+.. data:: None
+
+   The sole value of :attr:`types.NoneType`.  ``None`` is frequently used to
+   represent the absence of a value, as when default arguments are not passed to a
+   function.
+
+
+.. data:: NotImplemented
+
+   Special value which can be returned by the "rich comparison" special methods
+   (:meth:`__eq__`, :meth:`__lt__`, and friends), to indicate that the comparison
+   is not implemented with respect to the other type.
+
+
+.. data:: Ellipsis
+
+   The same as ``...``. Special value used mostly in conjunction with extended
+   slicing syntax for user-defined container data types.
+
+   .. % XXX Someone who understands extended slicing should fill in here.
+

Doc/library/contextlib.rst

@@ -0,0 +1,120 @@
+
+:mod:`contextlib` --- Utilities for :keyword:`with`\ -statement contexts.
+=========================================================================
+
+.. module:: contextlib
+   :synopsis: Utilities for with-statement contexts.
+
+
+.. versionadded:: 2.5
+
+This module provides utilities for common tasks involving the :keyword:`with`
+statement. For more information see also :ref:`typecontextmanager` and
+:ref:`context-managers`.
+
+Functions provided:
+
+
+.. function:: contextmanager(func)
+
+   This function is a decorator that can be used to define a factory function for
+   :keyword:`with` statement context managers, without needing to create a class or
+   separate :meth:`__enter__` and :meth:`__exit__` methods.
+
+   A simple example (this is not recommended as a real way of generating HTML!)::
+
+      from __future__ import with_statement
+      from contextlib import contextmanager
+
+      @contextmanager
+      def tag(name):
+          print "<%s>" % name
+          yield
+          print "</%s>" % name
+
+      >>> with tag("h1"):
+      ...    print "foo"
+      ...
+      <h1>
+      foo
+      </h1>
+
+   The function being decorated must return a generator-iterator when called. This
+   iterator must yield exactly one value, which will be bound to the targets in the
+   :keyword:`with` statement's :keyword:`as` clause, if any.
+
+   At the point where the generator yields, the block nested in the :keyword:`with`
+   statement is executed.  The generator is then resumed after the block is exited.
+   If an unhandled exception occurs in the block, it is reraised inside the
+   generator at the point where the yield occurred.  Thus, you can use a
+   :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` statement to trap
+   the error (if any), or ensure that some cleanup takes place. If an exception is
+   trapped merely in order to log it or to perform some action (rather than to
+   suppress it entirely), the generator must reraise that exception. Otherwise the
+   generator context manager will indicate to the :keyword:`with` statement that
+   the exception has been handled, and execution will resume with the statement
+   immediately following the :keyword:`with` statement.
+
+
+.. function:: nested(mgr1[, mgr2[, ...]])
+
+   Combine multiple context managers into a single nested context manager.
+
+   Code like this::
+
+      from contextlib import nested
+
+      with nested(A, B, C) as (X, Y, Z):
+          do_something()
+
+   is equivalent to this::
+
+      with A as X:
+          with B as Y:
+              with C as Z:
+                  do_something()
+
+   Note that if the :meth:`__exit__` method of one of the nested context managers
+   indicates an exception should be suppressed, no exception information will be
+   passed to any remaining outer context managers. Similarly, if the
+   :meth:`__exit__` method of one of the nested managers raises an exception, any
+   previous exception state will be lost; the new exception will be passed to the
+   :meth:`__exit__` methods of any remaining outer context managers. In general,
+   :meth:`__exit__` methods should avoid raising exceptions, and in particular they
+   should not re-raise a passed-in exception.
+
+
+.. function:: closing(thing)
+
+   Return a context manager that closes *thing* upon completion of the block.  This
+   is basically equivalent to::
+
+      from contextlib import contextmanager
+
+      @contextmanager
+      def closing(thing):
+          try:
+              yield thing
+          finally:
+              thing.close()
+
+   And lets you write code like this::
+
+      from __future__ import with_statement
+      from contextlib import closing
+      import urllib
+
+      with closing(urllib.urlopen('http://www.python.org')) as page:
+          for line in page:
+              print line
+
+   without needing to explicitly close ``page``.  Even if an error occurs,
+   ``page.close()`` will be called when the :keyword:`with` block is exited.
+
+
+.. seealso::
+
+   :pep:`0343` - The "with" statement
+      The specification, background, and examples for the Python :keyword:`with`
+      statement.
+

Doc/library/cookie.rst

@@ -0,0 +1,282 @@
+
+:mod:`Cookie` --- HTTP state management
+=======================================
+
+.. module:: Cookie
+   :synopsis: Support for HTTP state management (cookies).
+.. moduleauthor:: Timothy O'Malley <timo@alum.mit.edu>
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+The :mod:`Cookie` module defines classes for abstracting the concept of
+cookies, an HTTP state management mechanism. It supports both simple string-only
+cookies, and provides an abstraction for having any serializable data-type as
+cookie value.
+
+The module formerly strictly applied the parsing rules described in the
+:rfc:`2109` and :rfc:`2068` specifications.  It has since been discovered that
+MSIE 3.0x doesn't follow the character rules outlined in those specs.  As a
+result, the parsing rules used are a bit less strict.
+
+
+.. exception:: CookieError
+
+   Exception failing because of :rfc:`2109` invalidity: incorrect attributes,
+   incorrect :mailheader:`Set-Cookie` header, etc.
+
+
+.. class:: BaseCookie([input])
+
+   This class is a dictionary-like object whose keys are strings and whose values
+   are :class:`Morsel` instances. Note that upon setting a key to a value, the
+   value is first converted to a :class:`Morsel` containing the key and the value.
+
+   If *input* is given, it is passed to the :meth:`load` method.
+
+
+.. class:: SimpleCookie([input])
+
+   This class derives from :class:`BaseCookie` and overrides :meth:`value_decode`
+   and :meth:`value_encode` to be the identity and :func:`str` respectively.
+
+
+.. class:: SerialCookie([input])
+
+   This class derives from :class:`BaseCookie` and overrides :meth:`value_decode`
+   and :meth:`value_encode` to be the :func:`pickle.loads` and
+   :func:`pickle.dumps`.
+
+   .. deprecated:: 2.3
+      Reading pickled values from untrusted cookie data is a huge security hole, as
+      pickle strings can be crafted to cause arbitrary code to execute on your server.
+      It is supported for backwards compatibility only, and may eventually go away.
+
+
+.. class:: SmartCookie([input])
+
+   This class derives from :class:`BaseCookie`. It overrides :meth:`value_decode`
+   to be :func:`pickle.loads` if it is a valid pickle, and otherwise the value
+   itself. It overrides :meth:`value_encode` to be :func:`pickle.dumps` unless it
+   is a string, in which case it returns the value itself.
+
+   .. deprecated:: 2.3
+      The same security warning from :class:`SerialCookie` applies here.
+
+A further security note is warranted.  For backwards compatibility, the
+:mod:`Cookie` module exports a class named :class:`Cookie` which is just an
+alias for :class:`SmartCookie`.  This is probably a mistake and will likely be
+removed in a future version.  You should not use the :class:`Cookie` class in
+your applications, for the same reason why you should not use the
+:class:`SerialCookie` class.
+
+
+.. seealso::
+
+   Module :mod:`cookielib`
+      HTTP cookie handling for web *clients*.  The :mod:`cookielib` and :mod:`Cookie`
+      modules do not depend on each other.
+
+   :rfc:`2109` - HTTP State Management Mechanism
+      This is the state management specification implemented by this module.
+
+
+.. _cookie-objects:
+
+Cookie Objects
+--------------
+
+
+.. method:: BaseCookie.value_decode(val)
+
+   Return a decoded value from a string representation. Return value can be any
+   type. This method does nothing in :class:`BaseCookie` --- it exists so it can be
+   overridden.
+
+
+.. method:: BaseCookie.value_encode(val)
+
+   Return an encoded value. *val* can be any type, but return value must be a
+   string. This method does nothing in :class:`BaseCookie` --- it exists so it can
+   be overridden
+
+   In general, it should be the case that :meth:`value_encode` and
+   :meth:`value_decode` are inverses on the range of *value_decode*.
+
+
+.. method:: BaseCookie.output([attrs[, header[, sep]]])
+
+   Return a string representation suitable to be sent as HTTP headers. *attrs* and
+   *header* are sent to each :class:`Morsel`'s :meth:`output` method. *sep* is used
+   to join the headers together, and is by default the combination ``'\r\n'``
+   (CRLF).
+
+   .. versionchanged:: 2.5
+      The default separator has been changed from ``'\n'`` to match the cookie
+      specification.
+
+
+.. method:: BaseCookie.js_output([attrs])
+
+   Return an embeddable JavaScript snippet, which, if run on a browser which
+   supports JavaScript, will act the same as if the HTTP headers was sent.
+
+   The meaning for *attrs* is the same as in :meth:`output`.
+
+
+.. method:: BaseCookie.load(rawdata)
+
+   If *rawdata* is a string, parse it as an ``HTTP_COOKIE`` and add the values
+   found there as :class:`Morsel`\ s. If it is a dictionary, it is equivalent to::
+
+      for k, v in rawdata.items():
+          cookie[k] = v
+
+
+.. _morsel-objects:
+
+Morsel Objects
+--------------
+
+
+.. class:: Morsel()
+
+   Abstract a key/value pair, which has some :rfc:`2109` attributes.
+
+   Morsels are dictionary-like objects, whose set of keys is constant --- the valid
+   :rfc:`2109` attributes, which are
+
+   * ``expires``
+   * ``path``
+   * ``comment``
+   * ``domain``
+   * ``max-age``
+   * ``secure``
+   * ``version``
+
+   The keys are case-insensitive.
+
+
+.. attribute:: Morsel.value
+
+   The value of the cookie.
+
+
+.. attribute:: Morsel.coded_value
+
+   The encoded value of the cookie --- this is what should be sent.
+
+
+.. attribute:: Morsel.key
+
+   The name of the cookie.
+
+
+.. method:: Morsel.set(key, value, coded_value)
+
+   Set the *key*, *value* and *coded_value* members.
+
+
+.. method:: Morsel.isReservedKey(K)
+
+   Whether *K* is a member of the set of keys of a :class:`Morsel`.
+
+
+.. method:: Morsel.output([attrs[, header]])
+
+   Return a string representation of the Morsel, suitable to be sent as an HTTP
+   header. By default, all the attributes are included, unless *attrs* is given, in
+   which case it should be a list of attributes to use. *header* is by default
+   ``"Set-Cookie:"``.
+
+
+.. method:: Morsel.js_output([attrs])
+
+   Return an embeddable JavaScript snippet, which, if run on a browser which
+   supports JavaScript, will act the same as if the HTTP header was sent.
+
+   The meaning for *attrs* is the same as in :meth:`output`.
+
+
+.. method:: Morsel.OutputString([attrs])
+
+   Return a string representing the Morsel, without any surrounding HTTP or
+   JavaScript.
+
+   The meaning for *attrs* is the same as in :meth:`output`.
+
+
+.. _cookie-example:
+
+Example
+-------
+
+The following example demonstrates how to use the :mod:`Cookie` module. ::
+
+   >>> import Cookie
+   >>> C = Cookie.SimpleCookie()
+   >>> C = Cookie.SerialCookie()
+   >>> C = Cookie.SmartCookie()
+   >>> C["fig"] = "newton"
+   >>> C["sugar"] = "wafer"
+   >>> print C # generate HTTP headers
+   Set-Cookie: sugar=wafer
+   Set-Cookie: fig=newton
+   >>> print C.output() # same thing
+   Set-Cookie: sugar=wafer
+   Set-Cookie: fig=newton
+   >>> C = Cookie.SmartCookie()
+   >>> C["rocky"] = "road"
+   >>> C["rocky"]["path"] = "/cookie"
+   >>> print C.output(header="Cookie:")
+   Cookie: rocky=road; Path=/cookie
+   >>> print C.output(attrs=[], header="Cookie:")
+   Cookie: rocky=road
+   >>> C = Cookie.SmartCookie()
+   >>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
+   >>> print C
+   Set-Cookie: vienna=finger
+   Set-Cookie: chips=ahoy
+   >>> C = Cookie.SmartCookie()
+   >>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
+   >>> print C
+   Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
+   >>> C = Cookie.SmartCookie()
+   >>> C["oreo"] = "doublestuff"
+   >>> C["oreo"]["path"] = "/"
+   >>> print C
+   Set-Cookie: oreo=doublestuff; Path=/
+   >>> C = Cookie.SmartCookie()
+   >>> C["twix"] = "none for you"
+   >>> C["twix"].value
+   'none for you'
+   >>> C = Cookie.SimpleCookie()
+   >>> C["number"] = 7 # equivalent to C["number"] = str(7)
+   >>> C["string"] = "seven"
+   >>> C["number"].value
+   '7'
+   >>> C["string"].value
+   'seven'
+   >>> print C
+   Set-Cookie: number=7
+   Set-Cookie: string=seven
+   >>> C = Cookie.SerialCookie()
+   >>> C["number"] = 7
+   >>> C["string"] = "seven"
+   >>> C["number"].value
+   7
+   >>> C["string"].value
+   'seven'
+   >>> print C
+   Set-Cookie: number="I7\012."
+   Set-Cookie: string="S'seven'\012p1\012."
+   >>> C = Cookie.SmartCookie()
+   >>> C["number"] = 7
+   >>> C["string"] = "seven"
+   >>> C["number"].value
+   7
+   >>> C["string"].value
+   'seven'
+   >>> print C
+   Set-Cookie: number="I7\012."
+   Set-Cookie: string=seven
+

Doc/library/cookielib.rst

@@ -0,0 +1,768 @@
+
+:mod:`cookielib` --- Cookie handling for HTTP clients
+=====================================================
+
+.. module:: cookielib
+   :synopsis: Classes for automatic handling of HTTP cookies.
+.. moduleauthor:: John J. Lee <jjl@pobox.com>
+.. sectionauthor:: John J. Lee <jjl@pobox.com>
+
+
+.. versionadded:: 2.4
+
+
+
+The :mod:`cookielib` module defines classes for automatic handling of HTTP
+cookies.  It is useful for accessing web sites that require small pieces of data
+-- :dfn:`cookies` -- to be set on the client machine by an HTTP response from a
+web server, and then returned to the server in later HTTP requests.
+
+Both the regular Netscape cookie protocol and the protocol defined by
+:rfc:`2965` are handled.  RFC 2965 handling is switched off by default.
+:rfc:`2109` cookies are parsed as Netscape cookies and subsequently treated
+either as Netscape or RFC 2965 cookies according to the 'policy' in effect.
+Note that the great majority of cookies on the Internet are Netscape cookies.
+:mod:`cookielib` attempts to follow the de-facto Netscape cookie protocol (which
+differs substantially from that set out in the original Netscape specification),
+including taking note of the ``max-age`` and ``port`` cookie-attributes
+introduced with RFC 2965.
+
+.. note::
+
+   The various named parameters found in :mailheader:`Set-Cookie` and
+   :mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are
+   conventionally referred to as :dfn:`attributes`.  To distinguish them from
+   Python attributes, the documentation for this module uses the term
+   :dfn:`cookie-attribute` instead.
+
+
+The module defines the following exception:
+
+
+.. exception:: LoadError
+
+   Instances of :class:`FileCookieJar` raise this exception on failure to load
+   cookies from a file.
+
+   .. note::
+
+      For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`),
+      :exc:`LoadError` is a subclass of :exc:`IOError`.
+
+
+The following classes are provided:
+
+
+.. class:: CookieJar(policy=None)
+
+   *policy* is an object implementing the :class:`CookiePolicy` interface.
+
+   The :class:`CookieJar` class stores HTTP cookies.  It extracts cookies from HTTP
+   requests, and returns them in HTTP responses. :class:`CookieJar` instances
+   automatically expire contained cookies when necessary.  Subclasses are also
+   responsible for storing and retrieving cookies from a file or database.
+
+
+.. class:: FileCookieJar(filename, delayload=None, policy=None)
+
+   *policy* is an object implementing the :class:`CookiePolicy` interface.  For the
+   other arguments, see the documentation for the corresponding attributes.
+
+   A :class:`CookieJar` which can load cookies from, and perhaps save cookies to, a
+   file on disk.  Cookies are **NOT** loaded from the named file until either the
+   :meth:`load` or :meth:`revert` method is called.  Subclasses of this class are
+   documented in section :ref:`file-cookie-jar-classes`.
+
+
+.. class:: CookiePolicy()
+
+   This class is responsible for deciding whether each cookie should be accepted
+   from / returned to the server.
+
+
+.. class:: DefaultCookiePolicy( blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False )
+
+   Constructor arguments should be passed as keyword arguments only.
+   *blocked_domains* is a sequence of domain names that we never accept cookies
+   from, nor return cookies to. *allowed_domains* if not :const:`None`, this is a
+   sequence of the only domains for which we accept and return cookies.  For all
+   other arguments, see the documentation for :class:`CookiePolicy` and
+   :class:`DefaultCookiePolicy` objects.
+
+   :class:`DefaultCookiePolicy` implements the standard accept / reject rules for
+   Netscape and RFC 2965 cookies.  By default, RFC 2109 cookies (ie. cookies
+   received in a :mailheader:`Set-Cookie` header with a version cookie-attribute of
+   1) are treated according to the RFC 2965 rules.  However, if RFC 2965 handling
+   is turned off or :attr:`rfc2109_as_netscape` is True, RFC 2109 cookies are
+   'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by
+   setting the :attr:`version` attribute of the :class:`Cookie` instance to 0.
+   :class:`DefaultCookiePolicy` also provides some parameters to allow some
+   fine-tuning of policy.
+
+
+.. class:: Cookie()
+
+   This class represents Netscape, RFC 2109 and RFC 2965 cookies.  It is not
+   expected that users of :mod:`cookielib` construct their own :class:`Cookie`
+   instances.  Instead, if necessary, call :meth:`make_cookies` on a
+   :class:`CookieJar` instance.
+
+
+.. seealso::
+
+   Module :mod:`urllib2`
+      URL opening with automatic cookie handling.
+
+   Module :mod:`Cookie`
+      HTTP cookie classes, principally useful for server-side code.  The
+      :mod:`cookielib` and :mod:`Cookie` modules do not depend on each other.
+
+   http://wwwsearch.sf.net/ClientCookie/
+      Extensions to this module, including a class for reading Microsoft Internet
+      Explorer cookies on Windows.
+
+   http://www.netscape.com/newsref/std/cookie_spec.html
+      The specification of the original Netscape cookie protocol.  Though this is
+      still the dominant protocol, the 'Netscape cookie protocol' implemented by all
+      the major browsers (and :mod:`cookielib`) only bears a passing resemblance to
+      the one sketched out in ``cookie_spec.html``.
+
+   :rfc:`2109` - HTTP State Management Mechanism
+      Obsoleted by RFC 2965. Uses :mailheader:`Set-Cookie` with version=1.
+
+   :rfc:`2965` - HTTP State Management Mechanism
+      The Netscape protocol with the bugs fixed.  Uses :mailheader:`Set-Cookie2` in
+      place of :mailheader:`Set-Cookie`.  Not widely used.
+
+   http://kristol.org/cookie/errata.html
+      Unfinished errata to RFC 2965.
+
+   :rfc:`2964` - Use of HTTP State Management
+
+.. _cookie-jar-objects:
+
+CookieJar and FileCookieJar Objects
+-----------------------------------
+
+:class:`CookieJar` objects support the iterator protocol for iterating over
+contained :class:`Cookie` objects.
+
+:class:`CookieJar` has the following methods:
+
+
+.. method:: CookieJar.add_cookie_header(request)
+
+   Add correct :mailheader:`Cookie` header to *request*.
+
+   If policy allows (ie. the :attr:`rfc2965` and :attr:`hide_cookie2` attributes of
+   the :class:`CookieJar`'s :class:`CookiePolicy` instance are true and false
+   respectively), the :mailheader:`Cookie2` header is also added when appropriate.
+
+   The *request* object (usually a :class:`urllib2.Request` instance) must support
+   the methods :meth:`get_full_url`, :meth:`get_host`, :meth:`get_type`,
+   :meth:`unverifiable`, :meth:`get_origin_req_host`, :meth:`has_header`,
+   :meth:`get_header`, :meth:`header_items`, and :meth:`add_unredirected_header`,as
+   documented by :mod:`urllib2`.
+
+
+.. method:: CookieJar.extract_cookies(response, request)
+
+   Extract cookies from HTTP *response* and store them in the :class:`CookieJar`,
+   where allowed by policy.
+
+   The :class:`CookieJar` will look for allowable :mailheader:`Set-Cookie` and
+   :mailheader:`Set-Cookie2` headers in the *response* argument, and store cookies
+   as appropriate (subject to the :meth:`CookiePolicy.set_ok` method's approval).
+
+   The *response* object (usually the result of a call to :meth:`urllib2.urlopen`,
+   or similar) should support an :meth:`info` method, which returns an object with
+   a :meth:`getallmatchingheaders` method (usually a :class:`mimetools.Message`
+   instance).
+
+   The *request* object (usually a :class:`urllib2.Request` instance) must support
+   the methods :meth:`get_full_url`, :meth:`get_host`, :meth:`unverifiable`, and
+   :meth:`get_origin_req_host`, as documented by :mod:`urllib2`.  The request is
+   used to set default values for cookie-attributes as well as for checking that
+   the cookie is allowed to be set.
+
+
+.. method:: CookieJar.set_policy(policy)
+
+   Set the :class:`CookiePolicy` instance to be used.
+
+
+.. method:: CookieJar.make_cookies(response, request)
+
+   Return sequence of :class:`Cookie` objects extracted from *response* object.
+
+   See the documentation for :meth:`extract_cookies` for the interfaces required of
+   the *response* and *request* arguments.
+
+
+.. method:: CookieJar.set_cookie_if_ok(cookie, request)
+
+   Set a :class:`Cookie` if policy says it's OK to do so.
+
+
+.. method:: CookieJar.set_cookie(cookie)
+
+   Set a :class:`Cookie`, without checking with policy to see whether or not it
+   should be set.
+
+
+.. method:: CookieJar.clear([domain[, path[, name]]])
+
+   Clear some cookies.
+
+   If invoked without arguments, clear all cookies.  If given a single argument,
+   only cookies belonging to that *domain* will be removed. If given two arguments,
+   cookies belonging to the specified *domain* and URL *path* are removed.  If
+   given three arguments, then the cookie with the specified *domain*, *path* and
+   *name* is removed.
+
+   Raises :exc:`KeyError` if no matching cookie exists.
+
+
+.. method:: CookieJar.clear_session_cookies()
+
+   Discard all session cookies.
+
+   Discards all contained cookies that have a true :attr:`discard` attribute
+   (usually because they had either no ``max-age`` or ``expires`` cookie-attribute,
+   or an explicit ``discard`` cookie-attribute).  For interactive browsers, the end
+   of a session usually corresponds to closing the browser window.
+
+   Note that the :meth:`save` method won't save session cookies anyway, unless you
+   ask otherwise by passing a true *ignore_discard* argument.
+
+:class:`FileCookieJar` implements the following additional methods:
+
+
+.. method:: FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False)
+
+   Save cookies to a file.
+
+   This base class raises :exc:`NotImplementedError`.  Subclasses may leave this
+   method unimplemented.
+
+   *filename* is the name of file in which to save cookies.  If *filename* is not
+   specified, :attr:`self.filename` is used (whose default is the value passed to
+   the constructor, if any); if :attr:`self.filename` is :const:`None`,
+   :exc:`ValueError` is raised.
+
+   *ignore_discard*: save even cookies set to be discarded. *ignore_expires*: save
+   even cookies that have expired
+
+   The file is overwritten if it already exists, thus wiping all the cookies it
+   contains.  Saved cookies can be restored later using the :meth:`load` or
+   :meth:`revert` methods.
+
+
+.. method:: FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)
+
+   Load cookies from a file.
+
+   Old cookies are kept unless overwritten by newly loaded ones.
+
+   Arguments are as for :meth:`save`.
+
+   The named file must be in the format understood by the class, or
+   :exc:`LoadError` will be raised.  Also, :exc:`IOError` may be raised, for
+   example if the file does not exist.
+
+   .. note::
+
+      For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`),
+      :exc:`LoadError` is a subclass of :exc:`IOError`.
+
+
+.. method:: FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)
+
+   Clear all cookies and reload cookies from a saved file.
+
+   :meth:`revert` can raise the same exceptions as :meth:`load`. If there is a
+   failure, the object's state will not be altered.
+
+:class:`FileCookieJar` instances have the following public attributes:
+
+
+.. attribute:: FileCookieJar.filename
+
+   Filename of default file in which to keep cookies.  This attribute may be
+   assigned to.
+
+
+.. attribute:: FileCookieJar.delayload
+
+   If true, load cookies lazily from disk.  This attribute should not be assigned
+   to.  This is only a hint, since this only affects performance, not behaviour
+   (unless the cookies on disk are changing). A :class:`CookieJar` object may
+   ignore it.  None of the :class:`FileCookieJar` classes included in the standard
+   library lazily loads cookies.
+
+
+.. _file-cookie-jar-classes:
+
+FileCookieJar subclasses and co-operation with web browsers
+-----------------------------------------------------------
+
+The following :class:`CookieJar` subclasses are provided for reading and writing
+.  Further :class:`CookieJar` subclasses, including one that reads Microsoft
+Internet Explorer cookies, are available at
+http://wwwsearch.sf.net/ClientCookie/.
+
+
+.. class:: MozillaCookieJar(filename, delayload=None, policy=None)
+
+   A :class:`FileCookieJar` that can load from and save cookies to disk in the
+   Mozilla ``cookies.txt`` file format (which is also used by the Lynx and Netscape
+   browsers).
+
+   .. note::
+
+      This loses information about RFC 2965 cookies, and also about newer or
+      non-standard cookie-attributes such as ``port``.
+
+   .. warning::
+
+      Back up your cookies before saving if you have cookies whose loss / corruption
+      would be inconvenient (there are some subtleties which may lead to slight
+      changes in the file over a load / save round-trip).
+
+   Also note that cookies saved while Mozilla is running will get clobbered by
+   Mozilla.
+
+
+.. class:: LWPCookieJar(filename, delayload=None, policy=None)
+
+   A :class:`FileCookieJar` that can load from and save cookies to disk in format
+   compatible with the libwww-perl library's ``Set-Cookie3`` file format.  This is
+   convenient if you want to store cookies in a human-readable file.
+
+
+.. _cookie-policy-objects:
+
+CookiePolicy Objects
+--------------------
+
+Objects implementing the :class:`CookiePolicy` interface have the following
+methods:
+
+
+.. method:: CookiePolicy.set_ok(cookie, request)
+
+   Return boolean value indicating whether cookie should be accepted from server.
+
+   *cookie* is a :class:`cookielib.Cookie` instance.  *request* is an object
+   implementing the interface defined by the documentation for
+   :meth:`CookieJar.extract_cookies`.
+
+
+.. method:: CookiePolicy.return_ok(cookie, request)
+
+   Return boolean value indicating whether cookie should be returned to server.
+
+   *cookie* is a :class:`cookielib.Cookie` instance.  *request* is an object
+   implementing the interface defined by the documentation for
+   :meth:`CookieJar.add_cookie_header`.
+
+
+.. method:: CookiePolicy.domain_return_ok(domain, request)
+
+   Return false if cookies should not be returned, given cookie domain.
+
+   This method is an optimization.  It removes the need for checking every cookie
+   with a particular domain (which might involve reading many files).  Returning
+   true from :meth:`domain_return_ok` and :meth:`path_return_ok` leaves all the
+   work to :meth:`return_ok`.
+
+   If :meth:`domain_return_ok` returns true for the cookie domain,
+   :meth:`path_return_ok` is called for the cookie path.  Otherwise,
+   :meth:`path_return_ok` and :meth:`return_ok` are never called for that cookie
+   domain.  If :meth:`path_return_ok` returns true, :meth:`return_ok` is called
+   with the :class:`Cookie` object itself for a full check.  Otherwise,
+   :meth:`return_ok` is never called for that cookie path.
+
+   Note that :meth:`domain_return_ok` is called for every *cookie* domain, not just
+   for the *request* domain.  For example, the function might be called with both
+   ``".example.com"`` and ``"www.example.com"`` if the request domain is
+   ``"www.example.com"``.  The same goes for :meth:`path_return_ok`.
+
+   The *request* argument is as documented for :meth:`return_ok`.
+
+
+.. method:: CookiePolicy.path_return_ok(path, request)
+
+   Return false if cookies should not be returned, given cookie path.
+
+   See the documentation for :meth:`domain_return_ok`.
+
+In addition to implementing the methods above, implementations of the
+:class:`CookiePolicy` interface must also supply the following attributes,
+indicating which protocols should be used, and how.  All of these attributes may
+be assigned to.
+
+
+.. attribute:: CookiePolicy.netscape
+
+   Implement Netscape protocol.
+
+
+.. attribute:: CookiePolicy.rfc2965
+
+   Implement RFC 2965 protocol.
+
+
+.. attribute:: CookiePolicy.hide_cookie2
+
+   Don't add :mailheader:`Cookie2` header to requests (the presence of this header
+   indicates to the server that we understand RFC 2965 cookies).
+
+The most useful way to define a :class:`CookiePolicy` class is by subclassing
+from :class:`DefaultCookiePolicy` and overriding some or all of the methods
+above.  :class:`CookiePolicy` itself may be used as a 'null policy' to allow
+setting and receiving any and all cookies (this is unlikely to be useful).
+
+
+.. _default-cookie-policy-objects:
+
+DefaultCookiePolicy Objects
+---------------------------
+
+Implements the standard rules for accepting and returning cookies.
+
+Both RFC 2965 and Netscape cookies are covered.  RFC 2965 handling is switched
+off by default.
+
+The easiest way to provide your own policy is to override this class and call
+its methods in your overridden implementations before adding your own additional
+checks::
+
+   import cookielib
+   class MyCookiePolicy(cookielib.DefaultCookiePolicy):
+       def set_ok(self, cookie, request):
+           if not cookielib.DefaultCookiePolicy.set_ok(self, cookie, request):
+               return False
+           if i_dont_want_to_store_this_cookie(cookie):
+               return False
+           return True
+
+In addition to the features required to implement the :class:`CookiePolicy`
+interface, this class allows you to block and allow domains from setting and
+receiving cookies.  There are also some strictness switches that allow you to
+tighten up the rather loose Netscape protocol rules a little bit (at the cost of
+blocking some benign cookies).
+
+A domain blacklist and whitelist is provided (both off by default). Only domains
+not in the blacklist and present in the whitelist (if the whitelist is active)
+participate in cookie setting and returning.  Use the *blocked_domains*
+constructor argument, and :meth:`blocked_domains` and
+:meth:`set_blocked_domains` methods (and the corresponding argument and methods
+for *allowed_domains*).  If you set a whitelist, you can turn it off again by
+setting it to :const:`None`.
+
+Domains in block or allow lists that do not start with a dot must equal the
+cookie domain to be matched.  For example, ``"example.com"`` matches a blacklist
+entry of ``"example.com"``, but ``"www.example.com"`` does not.  Domains that do
+start with a dot are matched by more specific domains too. For example, both
+``"www.example.com"`` and ``"www.coyote.example.com"`` match ``".example.com"``
+(but ``"example.com"`` itself does not).  IP addresses are an exception, and
+must match exactly.  For example, if blocked_domains contains ``"192.168.1.2"``
+and ``".168.1.2"``, 192.168.1.2 is blocked, but 193.168.1.2 is not.
+
+:class:`DefaultCookiePolicy` implements the following additional methods:
+
+
+.. method:: DefaultCookiePolicy.blocked_domains()
+
+   Return the sequence of blocked domains (as a tuple).
+
+
+.. method:: DefaultCookiePolicy.set_blocked_domains(blocked_domains)
+
+   Set the sequence of blocked domains.
+
+
+.. method:: DefaultCookiePolicy.is_blocked(domain)
+
+   Return whether *domain* is on the blacklist for setting or receiving cookies.
+
+
+.. method:: DefaultCookiePolicy.allowed_domains()
+
+   Return :const:`None`, or the sequence of allowed domains (as a tuple).
+
+
+.. method:: DefaultCookiePolicy.set_allowed_domains(allowed_domains)
+
+   Set the sequence of allowed domains, or :const:`None`.
+
+
+.. method:: DefaultCookiePolicy.is_not_allowed(domain)
+
+   Return whether *domain* is not on the whitelist for setting or receiving
+   cookies.
+
+:class:`DefaultCookiePolicy` instances have the following attributes, which are
+all initialised from the constructor arguments of the same name, and which may
+all be assigned to.
+
+
+.. attribute:: DefaultCookiePolicy.rfc2109_as_netscape
+
+   If true, request that the :class:`CookieJar` instance downgrade RFC 2109 cookies
+   (ie. cookies received in a :mailheader:`Set-Cookie` header with a version
+   cookie-attribute of 1) to Netscape cookies by setting the version attribute of
+   the :class:`Cookie` instance to 0.  The default value is :const:`None`, in which
+   case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned
+   off.  Therefore, RFC 2109 cookies are downgraded by default.
+
+   .. versionadded:: 2.5
+
+General strictness switches:
+
+
+.. attribute:: DefaultCookiePolicy.strict_domain
+
+   Don't allow sites to set two-component domains with country-code top-level
+   domains like ``.co.uk``, ``.gov.uk``, ``.co.nz``.etc.  This is far from perfect
+   and isn't guaranteed to work!
+
+RFC 2965 protocol strictness switches:
+
+
+.. attribute:: DefaultCookiePolicy.strict_rfc2965_unverifiable
+
+   Follow RFC 2965 rules on unverifiable transactions (usually, an unverifiable
+   transaction is one resulting from a redirect or a request for an image hosted on
+   another site).  If this is false, cookies are *never* blocked on the basis of
+   verifiability
+
+Netscape protocol strictness switches:
+
+
+.. attribute:: DefaultCookiePolicy.strict_ns_unverifiable
+
+   apply RFC 2965 rules on unverifiable transactions even to Netscape cookies
+
+
+.. attribute:: DefaultCookiePolicy.strict_ns_domain
+
+   Flags indicating how strict to be with domain-matching rules for Netscape
+   cookies.  See below for acceptable values.
+
+
+.. attribute:: DefaultCookiePolicy.strict_ns_set_initial_dollar
+
+   Ignore cookies in Set-Cookie: headers that have names starting with ``'$'``.
+
+
+.. attribute:: DefaultCookiePolicy.strict_ns_set_path
+
+   Don't allow setting cookies whose path doesn't path-match request URI.
+
+:attr:`strict_ns_domain` is a collection of flags.  Its value is constructed by
+or-ing together (for example, ``DomainStrictNoDots|DomainStrictNonDomain`` means
+both flags are set).
+
+
+.. attribute:: DefaultCookiePolicy.DomainStrictNoDots
+
+   When setting cookies, the 'host prefix' must not contain a dot (eg.
+   ``www.foo.bar.com`` can't set a cookie for ``.bar.com``, because ``www.foo``
+   contains a dot).
+
+
+.. attribute:: DefaultCookiePolicy.DomainStrictNonDomain
+
+   Cookies that did not explicitly specify a ``domain`` cookie-attribute can only
+   be returned to a domain equal to the domain that set the cookie (eg.
+   ``spam.example.com`` won't be returned cookies from ``example.com`` that had no
+   ``domain`` cookie-attribute).
+
+
+.. attribute:: DefaultCookiePolicy.DomainRFC2965Match
+
+   When setting cookies, require a full RFC 2965 domain-match.
+
+The following attributes are provided for convenience, and are the most useful
+combinations of the above flags:
+
+
+.. attribute:: DefaultCookiePolicy.DomainLiberal
+
+   Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched
+   off).
+
+
+.. attribute:: DefaultCookiePolicy.DomainStrict
+
+   Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``.
+
+
+.. _cookielib-cookie-objects:
+
+Cookie Objects
+--------------
+
+:class:`Cookie` instances have Python attributes roughly corresponding to the
+standard cookie-attributes specified in the various cookie standards.  The
+correspondence is not one-to-one, because there are complicated rules for
+assigning default values, because the ``max-age`` and ``expires``
+cookie-attributes contain equivalent information, and because RFC 2109 cookies
+may be 'downgraded' by :mod:`cookielib` from version 1 to version 0 (Netscape)
+cookies.
+
+Assignment to these attributes should not be necessary other than in rare
+circumstances in a :class:`CookiePolicy` method.  The class does not enforce
+internal consistency, so you should know what you're doing if you do that.
+
+
+.. attribute:: Cookie.version
+
+   Integer or :const:`None`.  Netscape cookies have :attr:`version` 0. RFC 2965 and
+   RFC 2109 cookies have a ``version`` cookie-attribute of 1.  However, note that
+   :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which
+   case :attr:`version` is 0.
+
+
+.. attribute:: Cookie.name
+
+   Cookie name (a string).
+
+
+.. attribute:: Cookie.value
+
+   Cookie value (a string), or :const:`None`.
+
+
+.. attribute:: Cookie.port
+
+   String representing a port or a set of ports (eg. '80', or '80,8080'), or
+   :const:`None`.
+
+
+.. attribute:: Cookie.path
+
+   Cookie path (a string, eg. ``'/acme/rocket_launchers'``).
+
+
+.. attribute:: Cookie.secure
+
+   True if cookie should only be returned over a secure connection.
+
+
+.. attribute:: Cookie.expires
+
+   Integer expiry date in seconds since epoch, or :const:`None`.  See also the
+   :meth:`is_expired` method.
+
+
+.. attribute:: Cookie.discard
+
+   True if this is a session cookie.
+
+
+.. attribute:: Cookie.comment
+
+   String comment from the server explaining the function of this cookie, or
+   :const:`None`.
+
+
+.. attribute:: Cookie.comment_url
+
+   URL linking to a comment from the server explaining the function of this cookie,
+   or :const:`None`.
+
+
+.. attribute:: Cookie.rfc2109
+
+   True if this cookie was received as an RFC 2109 cookie (ie. the cookie
+   arrived in a :mailheader:`Set-Cookie` header, and the value of the Version
+   cookie-attribute in that header was 1).  This attribute is provided because
+   :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in
+   which case :attr:`version` is 0.
+
+   .. versionadded:: 2.5
+
+
+.. attribute:: Cookie.port_specified
+
+   True if a port or set of ports was explicitly specified by the server (in the
+   :mailheader:`Set-Cookie` / :mailheader:`Set-Cookie2` header).
+
+
+.. attribute:: Cookie.domain_specified
+
+   True if a domain was explicitly specified by the server.
+
+
+.. attribute:: Cookie.domain_initial_dot
+
+   True if the domain explicitly specified by the server began with a dot
+   (``'.'``).
+
+Cookies may have additional non-standard cookie-attributes.  These may be
+accessed using the following methods:
+
+
+.. method:: Cookie.has_nonstandard_attr(name)
+
+   Return true if cookie has the named cookie-attribute.
+
+
+.. method:: Cookie.get_nonstandard_attr(name, default=None)
+
+   If cookie has the named cookie-attribute, return its value. Otherwise, return
+   *default*.
+
+
+.. method:: Cookie.set_nonstandard_attr(name, value)
+
+   Set the value of the named cookie-attribute.
+
+The :class:`Cookie` class also defines the following method:
+
+
+.. method:: Cookie.is_expired([now=:const:`None`])
+
+   True if cookie has passed the time at which the server requested it should
+   expire.  If *now* is given (in seconds since the epoch), return whether the
+   cookie has expired at the specified time.
+
+
+.. _cookielib-examples:
+
+Examples
+--------
+
+The first example shows the most common usage of :mod:`cookielib`::
+
+   import cookielib, urllib2
+   cj = cookielib.CookieJar()
+   opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
+   r = opener.open("http://example.com/")
+
+This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx
+cookies (assumes Unix/Netscape convention for location of the cookies file)::
+
+   import os, cookielib, urllib2
+   cj = cookielib.MozillaCookieJar()
+   cj.load(os.path.join(os.environ["HOME"], ".netscape/cookies.txt"))
+   opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
+   r = opener.open("http://example.com/")
+
+The next example illustrates the use of :class:`DefaultCookiePolicy`. Turn on
+RFC 2965 cookies, be more strict about domains when setting and returning
+Netscape cookies, and block some domains from setting cookies or having them
+returned::
+
+   import urllib2
+   from cookielib import CookieJar, DefaultCookiePolicy
+   policy = DefaultCookiePolicy(
+       rfc2965=True, strict_ns_domain=Policy.DomainStrict,
+       blocked_domains=["ads.net", ".ads.net"])
+   cj = CookieJar(policy)
+   opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
+   r = opener.open("http://example.com/")
+

Doc/library/copy.rst

@@ -0,0 +1,85 @@
+
+:mod:`copy` --- Shallow and deep copy operations
+================================================
+
+.. module:: copy
+   :synopsis: Shallow and deep copy operations.
+
+
+.. index::
+   single: copy() (in copy)
+   single: deepcopy() (in copy)
+
+This module provides generic (shallow and deep) copying operations.
+
+Interface summary::
+
+   import copy
+
+   x = copy.copy(y)        # make a shallow copy of y
+   x = copy.deepcopy(y)    # make a deep copy of y
+
+For module specific errors, :exc:`copy.error` is raised.
+
+.. % 
+
+The difference between shallow and deep copying is only relevant for compound
+objects (objects that contain other objects, like lists or class instances):
+
+* A *shallow copy* constructs a new compound object and then (to the extent
+  possible) inserts *references* into it to the objects found in the original.
+
+* A *deep copy* constructs a new compound object and then, recursively, inserts
+  *copies* into it of the objects found in the original.
+
+Two problems often exist with deep copy operations that don't exist with shallow
+copy operations:
+
+* Recursive objects (compound objects that, directly or indirectly, contain a
+  reference to themselves) may cause a recursive loop.
+
+* Because deep copy copies *everything* it may copy too much, e.g.,
+  administrative data structures that should be shared even between copies.
+
+The :func:`deepcopy` function avoids these problems by:
+
+* keeping a "memo" dictionary of objects already copied during the current
+  copying pass; and
+
+* letting user-defined classes override the copying operation or the set of
+  components copied.
+
+This module does not copy types like module, method, stack trace, stack frame,
+file, socket, window, array, or any similar types.  It does "copy" functions and
+classes (shallow and deeply), by returning the original object unchanged; this
+is compatible with the way these are treated by the :mod:`pickle` module.
+
+.. versionchanged:: 2.5
+   Added copying functions.
+
+.. index:: module: pickle
+
+Classes can use the same interfaces to control copying that they use to control
+pickling.  See the description of module :mod:`pickle` for information on these
+methods.  The :mod:`copy` module does not use the :mod:`copy_reg` registration
+module.
+
+.. index::
+   single: __copy__() (copy protocol)
+   single: __deepcopy__() (copy protocol)
+
+In order for a class to define its own copy implementation, it can define
+special methods :meth:`__copy__` and :meth:`__deepcopy__`.  The former is called
+to implement the shallow copy operation; no additional arguments are passed.
+The latter is called to implement the deep copy operation; it is passed one
+argument, the memo dictionary.  If the :meth:`__deepcopy__` implementation needs
+to make a deep copy of a component, it should call the :func:`deepcopy` function
+with the component as first argument and the memo dictionary as second argument.
+
+
+.. seealso::
+
+   Module :mod:`pickle`
+      Discussion of the special methods used to support object state retrieval and
+      restoration.
+

Doc/library/copy_reg.rst

@@ -0,0 +1,42 @@
+
+:mod:`copy_reg` --- Register :mod:`pickle` support functions
+============================================================
+
+.. module:: copy_reg
+   :synopsis: Register pickle support functions.
+
+
+.. index::
+   module: pickle
+   module: cPickle
+   module: copy
+
+The :mod:`copy_reg` module provides support for the :mod:`pickle` and
+:mod:`cPickle` modules.  The :mod:`copy` module is likely to use this in the
+future as well.  It provides configuration information about object constructors
+which are not classes.  Such constructors may be factory functions or class
+instances.
+
+
+.. function:: constructor(object)
+
+   Declares *object* to be a valid constructor.  If *object* is not callable (and
+   hence not valid as a constructor), raises :exc:`TypeError`.
+
+
+.. function:: pickle(type, function[, constructor])
+
+   Declares that *function* should be used as a "reduction" function for objects of
+   type *type*; *type* must not be a "classic" class object.  (Classic classes are
+   handled differently; see the documentation for the :mod:`pickle` module for
+   details.)  *function* should return either a string or a tuple containing two or
+   three elements.
+
+   The optional *constructor* parameter, if provided, is a callable object which
+   can be used to reconstruct the object when called with the tuple of arguments
+   returned by *function* at pickling time.  :exc:`TypeError` will be raised if
+   *object* is a class or *constructor* is not callable.
+
+   See the :mod:`pickle` module for more details on the interface expected of
+   *function* and *constructor*.
+

Doc/library/crypt.rst

@@ -0,0 +1,66 @@
+
+:mod:`crypt` --- Function to check Unix passwords
+=================================================
+
+.. module:: crypt
+   :platform: Unix
+   :synopsis: The crypt() function used to check Unix passwords.
+.. moduleauthor:: Steven D. Majewski <sdm7g@virginia.edu>
+.. sectionauthor:: Steven D. Majewski <sdm7g@virginia.edu>
+.. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
+
+
+.. index::
+   single: crypt(3)
+   pair: cipher; DES
+
+This module implements an interface to the :manpage:`crypt(3)` routine, which is
+a one-way hash function based upon a modified DES algorithm; see the Unix man
+page for further details.  Possible uses include allowing Python scripts to
+accept typed passwords from the user, or attempting to crack Unix passwords with
+a dictionary.
+
+.. index:: single: crypt(3)
+
+Notice that the behavior of this module depends on the actual implementation  of
+the :manpage:`crypt(3)` routine in the running system.  Therefore, any
+extensions available on the current implementation will also  be available on
+this module.
+
+
+.. function:: crypt(word, salt)
+
+   *word* will usually be a user's password as typed at a prompt or  in a graphical
+   interface.  *salt* is usually a random two-character string which will be used
+   to perturb the DES algorithm in one of 4096 ways.  The characters in *salt* must
+   be in the set ``[./a-zA-Z0-9]``.  Returns the hashed password as a string, which
+   will be composed of characters from the same alphabet as the salt (the first two
+   characters represent the salt itself).
+
+   .. index:: single: crypt(3)
+
+   Since a few :manpage:`crypt(3)` extensions allow different values, with
+   different sizes in the *salt*, it is recommended to use  the full crypted
+   password as salt when checking for a password.
+
+A simple example illustrating typical use::
+
+   import crypt, getpass, pwd
+
+   def raw_input(prompt):
+       import sys
+       sys.stdout.write(prompt)
+       sys.stdout.flush()
+       return sys.stdin.readline()
+
+   def login():
+       username = raw_input('Python login:')
+       cryptedpasswd = pwd.getpwnam(username)[1]
+       if cryptedpasswd:
+           if cryptedpasswd == 'x' or cryptedpasswd == '*': 
+               raise "Sorry, currently no support for shadow passwords"
+           cleartext = getpass.getpass()
+           return crypt.crypt(cleartext, cryptedpasswd) == cryptedpasswd
+       else:
+           return 1
+

Doc/library/crypto.rst

@@ -0,0 +1,30 @@
+
+.. _crypto:
+
+**********************
+Cryptographic Services
+**********************
+
+.. index:: single: cryptography
+
+The modules described in this chapter implement various algorithms of a
+cryptographic nature.  They are available at the discretion of the installation.
+Here's an overview:
+
+
+.. toctree::
+
+   hashlib.rst
+   hmac.rst
+
+.. index::
+   pair: AES; algorithm
+   single: cryptography
+   single: Kuchling, Andrew
+
+Hardcore cypherpunks will probably find the cryptographic modules written by
+A.M. Kuchling of further interest; the package contains modules for various
+encryption algorithms, most notably AES.  These modules are not distributed with
+Python but available separately.  See the URL
+http://www.amk.ca/python/code/crypto.html  for more information.
+

Doc/library/csv.rst

@@ -0,0 +1,530 @@
+
+:mod:`csv` --- CSV File Reading and Writing
+===========================================
+
+.. module:: csv
+   :synopsis: Write and read tabular data to and from delimited files.
+.. sectionauthor:: Skip Montanaro <skip@pobox.com>
+
+
+.. versionadded:: 2.3
+
+.. index::
+   single: csv
+   pair: data; tabular
+
+The so-called CSV (Comma Separated Values) format is the most common import and
+export format for spreadsheets and databases.  There is no "CSV standard", so
+the format is operationally defined by the many applications which read and
+write it.  The lack of a standard means that subtle differences often exist in
+the data produced and consumed by different applications.  These differences can
+make it annoying to process CSV files from multiple sources.  Still, while the
+delimiters and quoting characters vary, the overall format is similar enough
+that it is possible to write a single module which can efficiently manipulate
+such data, hiding the details of reading and writing the data from the
+programmer.
+
+The :mod:`csv` module implements classes to read and write tabular data in CSV
+format.  It allows programmers to say, "write this data in the format preferred
+by Excel," or "read data from this file which was generated by Excel," without
+knowing the precise details of the CSV format used by Excel.  Programmers can
+also describe the CSV formats understood by other applications or define their
+own special-purpose CSV formats.
+
+The :mod:`csv` module's :class:`reader` and :class:`writer` objects read and
+write sequences.  Programmers can also read and write data in dictionary form
+using the :class:`DictReader` and :class:`DictWriter` classes.
+
+.. note::
+
+   This version of the :mod:`csv` module doesn't support Unicode input.  Also,
+   there are currently some issues regarding ASCII NUL characters.  Accordingly,
+   all input should be UTF-8 or printable ASCII to be safe; see the examples in
+   section :ref:`csv-examples`. These restrictions will be removed in the future.
+
+
+.. seealso::
+
+   .. % \seemodule{array}{Arrays of uniformly types numeric values.}
+
+   :pep:`305` - CSV File API
+      The Python Enhancement Proposal which proposed this addition to Python.
+
+
+.. _csv-contents:
+
+Module Contents
+---------------
+
+The :mod:`csv` module defines the following functions:
+
+
+.. function:: reader(csvfile[, dialect='excel'][, fmtparam])
+
+   Return a reader object which will iterate over lines in the given *csvfile*.
+   *csvfile* can be any object which supports the iterator protocol and returns a
+   string each time its :meth:`next` method is called --- file objects and list
+   objects are both suitable.   If *csvfile* is a file object, it must be opened
+   with the 'b' flag on platforms where that makes a difference.  An optional
+   *dialect* parameter can be given which is used to define a set of parameters
+   specific to a particular CSV dialect.  It may be an instance of a subclass of
+   the :class:`Dialect` class or one of the strings returned by the
+   :func:`list_dialects` function.  The other optional *fmtparam* keyword arguments
+   can be given to override individual formatting parameters in the current
+   dialect.  For full details about the dialect and formatting parameters, see
+   section :ref:`csv-fmt-params`.
+
+   All data read are returned as strings.  No automatic data type conversion is
+   performed.
+
+   .. versionchanged:: 2.5
+      The parser is now stricter with respect to multi-line quoted fields. Previously,
+      if a line ended within a quoted field without a terminating newline character, a
+      newline would be inserted into the returned field. This behavior caused problems
+      when reading files which contained carriage return characters within fields.
+      The behavior was changed to return the field without inserting newlines. As a
+      consequence, if newlines embedded within fields are important, the input should
+      be split into lines in a manner which preserves the newline characters.
+
+
+.. function:: writer(csvfile[, dialect='excel'][, fmtparam])
+
+   Return a writer object responsible for converting the user's data into delimited
+   strings on the given file-like object.  *csvfile* can be any object with a
+   :func:`write` method.  If *csvfile* is a file object, it must be opened with the
+   'b' flag on platforms where that makes a difference.  An optional *dialect*
+   parameter can be given which is used to define a set of parameters specific to a
+   particular CSV dialect.  It may be an instance of a subclass of the
+   :class:`Dialect` class or one of the strings returned by the
+   :func:`list_dialects` function.  The other optional *fmtparam* keyword arguments
+   can be given to override individual formatting parameters in the current
+   dialect.  For full details about the dialect and formatting parameters, see
+   section :ref:`csv-fmt-params`. To make it
+   as easy as possible to interface with modules which implement the DB API, the
+   value :const:`None` is written as the empty string.  While this isn't a
+   reversible transformation, it makes it easier to dump SQL NULL data values to
+   CSV files without preprocessing the data returned from a ``cursor.fetch*`` call.
+   All other non-string data are stringified with :func:`str` before being written.
+
+
+.. function:: register_dialect(name[, dialect][, fmtparam])
+
+   Associate *dialect* with *name*.  *name* must be a string or Unicode object. The
+   dialect can be specified either by passing a sub-class of :class:`Dialect`, or
+   by *fmtparam* keyword arguments, or both, with keyword arguments overriding
+   parameters of the dialect. For full details about the dialect and formatting
+   parameters, see section :ref:`csv-fmt-params`.
+
+
+.. function:: unregister_dialect(name)
+
+   Delete the dialect associated with *name* from the dialect registry.  An
+   :exc:`Error` is raised if *name* is not a registered dialect name.
+
+
+.. function:: get_dialect(name)
+
+   Return the dialect associated with *name*.  An :exc:`Error` is raised if *name*
+   is not a registered dialect name.
+
+
+.. function:: list_dialects()
+
+   Return the names of all registered dialects.
+
+
+.. function:: field_size_limit([new_limit])
+
+   Returns the current maximum field size allowed by the parser. If *new_limit* is
+   given, this becomes the new limit.
+
+   .. versionadded:: 2.5
+
+The :mod:`csv` module defines the following classes:
+
+
+.. class:: DictReader(csvfile[, fieldnames=:const:None,[, restkey=:const:None[, restval=None[, dialect='excel'[, *args, **kwds]]]]])
+
+   Create an object which operates like a regular reader but maps the information
+   read into a dict whose keys are given by the optional  *fieldnames* parameter.
+   If the *fieldnames* parameter is omitted, the values in the first row of the
+   *csvfile* will be used as the fieldnames. If the row read has fewer fields than
+   the fieldnames sequence, the value of *restval* will be used as the default
+   value.  If the row read has more fields than the fieldnames sequence, the
+   remaining data is added as a sequence keyed by the value of *restkey*.  If the
+   row read has fewer fields than the fieldnames sequence, the remaining keys take
+   the value of the optional *restval* parameter.  Any other optional or keyword
+   arguments are passed to the underlying :class:`reader` instance.
+
+
+.. class:: DictWriter(csvfile, fieldnames[, restval=''[, extrasaction='raise'[, dialect='excel'[, *args, **kwds]]]])
+
+   Create an object which operates like a regular writer but maps dictionaries onto
+   output rows.  The *fieldnames* parameter identifies the order in which values in
+   the dictionary passed to the :meth:`writerow` method are written to the
+   *csvfile*.  The optional *restval* parameter specifies the value to be written
+   if the dictionary is missing a key in *fieldnames*.  If the dictionary passed to
+   the :meth:`writerow` method contains a key not found in *fieldnames*, the
+   optional *extrasaction* parameter indicates what action to take.  If it is set
+   to ``'raise'`` a :exc:`ValueError` is raised.  If it is set to ``'ignore'``,
+   extra values in the dictionary are ignored.  Any other optional or keyword
+   arguments are passed to the underlying :class:`writer` instance.
+
+   Note that unlike the :class:`DictReader` class, the *fieldnames* parameter of
+   the :class:`DictWriter` is not optional.  Since Python's :class:`dict` objects
+   are not ordered, there is not enough information available to deduce the order
+   in which the row should be written to the *csvfile*.
+
+
+.. class:: Dialect
+
+   The :class:`Dialect` class is a container class relied on primarily for its
+   attributes, which are used to define the parameters for a specific
+   :class:`reader` or :class:`writer` instance.
+
+
+.. class:: excel()
+
+   The :class:`excel` class defines the usual properties of an Excel-generated CSV
+   file.  It is registered with the dialect name ``'excel'``.
+
+
+.. class:: excel_tab()
+
+   The :class:`excel_tab` class defines the usual properties of an Excel-generated
+   TAB-delimited file.  It is registered with the dialect name ``'excel-tab'``.
+
+
+.. class:: Sniffer()
+
+   The :class:`Sniffer` class is used to deduce the format of a CSV file.
+
+The :class:`Sniffer` class provides two methods:
+
+
+.. method:: Sniffer.sniff(sample[, delimiters=None])
+
+   Analyze the given *sample* and return a :class:`Dialect` subclass reflecting the
+   parameters found.  If the optional *delimiters* parameter is given, it is
+   interpreted as a string containing possible valid delimiter characters.
+
+
+.. method:: Sniffer.has_header(sample)
+
+   Analyze the sample text (presumed to be in CSV format) and return :const:`True`
+   if the first row appears to be a series of column headers.
+
+The :mod:`csv` module defines the following constants:
+
+
+.. data:: QUOTE_ALL
+
+   Instructs :class:`writer` objects to quote all fields.
+
+
+.. data:: QUOTE_MINIMAL
+
+   Instructs :class:`writer` objects to only quote those fields which contain
+   special characters such as *delimiter*, *quotechar* or any of the characters in
+   *lineterminator*.
+
+
+.. data:: QUOTE_NONNUMERIC
+
+   Instructs :class:`writer` objects to quote all non-numeric fields.
+
+   Instructs the reader to convert all non-quoted fields to type *float*.
+
+
+.. data:: QUOTE_NONE
+
+   Instructs :class:`writer` objects to never quote fields.  When the current
+   *delimiter* occurs in output data it is preceded by the current *escapechar*
+   character.  If *escapechar* is not set, the writer will raise :exc:`Error` if
+   any characters that require escaping are encountered.
+
+   Instructs :class:`reader` to perform no special processing of quote characters.
+
+The :mod:`csv` module defines the following exception:
+
+
+.. exception:: Error
+
+   Raised by any of the functions when an error is detected.
+
+
+.. _csv-fmt-params:
+
+Dialects and Formatting Parameters
+----------------------------------
+
+To make it easier to specify the format of input and output records, specific
+formatting parameters are grouped together into dialects.  A dialect is a
+subclass of the :class:`Dialect` class having a set of specific methods and a
+single :meth:`validate` method.  When creating :class:`reader` or
+:class:`writer` objects, the programmer can specify a string or a subclass of
+the :class:`Dialect` class as the dialect parameter.  In addition to, or instead
+of, the *dialect* parameter, the programmer can also specify individual
+formatting parameters, which have the same names as the attributes defined below
+for the :class:`Dialect` class.
+
+Dialects support the following attributes:
+
+
+.. attribute:: Dialect.delimiter
+
+   A one-character string used to separate fields.  It defaults to ``','``.
+
+
+.. attribute:: Dialect.doublequote
+
+   Controls how instances of *quotechar* appearing inside a field should be
+   themselves be quoted.  When :const:`True`, the character is doubled. When
+   :const:`False`, the *escapechar* is used as a prefix to the *quotechar*.  It
+   defaults to :const:`True`.
+
+   On output, if *doublequote* is :const:`False` and no *escapechar* is set,
+   :exc:`Error` is raised if a *quotechar* is found in a field.
+
+
+.. attribute:: Dialect.escapechar
+
+   A one-character string used by the writer to escape the *delimiter* if *quoting*
+   is set to :const:`QUOTE_NONE` and the *quotechar* if *doublequote* is
+   :const:`False`. On reading, the *escapechar* removes any special meaning from
+   the following character. It defaults to :const:`None`, which disables escaping.
+
+
+.. attribute:: Dialect.lineterminator
+
+   The string used to terminate lines produced by the :class:`writer`. It defaults
+   to ``'\r\n'``.
+
+   .. note::
+
+      The :class:`reader` is hard-coded to recognise either ``'\r'`` or ``'\n'`` as
+      end-of-line, and ignores *lineterminator*. This behavior may change in the
+      future.
+
+
+.. attribute:: Dialect.quotechar
+
+   A one-character string used to quote fields containing special characters, such
+   as the *delimiter* or *quotechar*, or which contain new-line characters.  It
+   defaults to ``'"'``.
+
+
+.. attribute:: Dialect.quoting
+
+   Controls when quotes should be generated by the writer and recognised by the
+   reader.  It can take on any of the :const:`QUOTE_\*` constants (see section
+   :ref:`csv-contents`) and defaults to :const:`QUOTE_MINIMAL`.
+
+
+.. attribute:: Dialect.skipinitialspace
+
+   When :const:`True`, whitespace immediately following the *delimiter* is ignored.
+   The default is :const:`False`.
+
+
+Reader Objects
+--------------
+
+Reader objects (:class:`DictReader` instances and objects returned by the
+:func:`reader` function) have the following public methods:
+
+
+.. method:: csvreader.next()
+
+   Return the next row of the reader's iterable object as a list, parsed according
+   to the current dialect.
+
+Reader objects have the following public attributes:
+
+
+.. attribute:: csvreader.dialect
+
+   A read-only description of the dialect in use by the parser.
+
+
+.. attribute:: csvreader.line_num
+
+   The number of lines read from the source iterator. This is not the same as the
+   number of records returned, as records can span multiple lines.
+
+   .. versionadded:: 2.5
+
+
+Writer Objects
+--------------
+
+:class:`Writer` objects (:class:`DictWriter` instances and objects returned by
+the :func:`writer` function) have the following public methods.  A *row* must be
+a sequence of strings or numbers for :class:`Writer` objects and a dictionary
+mapping fieldnames to strings or numbers (by passing them through :func:`str`
+first) for :class:`DictWriter` objects.  Note that complex numbers are written
+out surrounded by parens. This may cause some problems for other programs which
+read CSV files (assuming they support complex numbers at all).
+
+
+.. method:: csvwriter.writerow(row)
+
+   Write the *row* parameter to the writer's file object, formatted according to
+   the current dialect.
+
+
+.. method:: csvwriter.writerows(rows)
+
+   Write all the *rows* parameters (a list of *row* objects as described above) to
+   the writer's file object, formatted according to the current dialect.
+
+Writer objects have the following public attribute:
+
+
+.. attribute:: csvwriter.dialect
+
+   A read-only description of the dialect in use by the writer.
+
+
+.. _csv-examples:
+
+Examples
+--------
+
+The simplest example of reading a CSV file::
+
+   import csv
+   reader = csv.reader(open("some.csv", "rb"))
+   for row in reader:
+       print row
+
+Reading a file with an alternate format::
+
+   import csv
+   reader = csv.reader(open("passwd", "rb"), delimiter=':', quoting=csv.QUOTE_NONE)
+   for row in reader:
+       print row
+
+The corresponding simplest possible writing example is::
+
+   import csv
+   writer = csv.writer(open("some.csv", "wb"))
+   writer.writerows(someiterable)
+
+Registering a new dialect::
+
+   import csv
+
+   csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
+
+   reader = csv.reader(open("passwd", "rb"), 'unixpwd')
+
+A slightly more advanced use of the reader --- catching and reporting errors::
+
+   import csv, sys
+   filename = "some.csv"
+   reader = csv.reader(open(filename, "rb"))
+   try:
+       for row in reader:
+           print row
+   except csv.Error as e:
+       sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e))
+
+And while the module doesn't directly support parsing strings, it can easily be
+done::
+
+   import csv
+   for row in csv.reader(['one,two,three']):
+       print row
+
+The :mod:`csv` module doesn't directly support reading and writing Unicode, but
+it is 8-bit-clean save for some problems with ASCII NUL characters.  So you can
+write functions or classes that handle the encoding and decoding for you as long
+as you avoid encodings like UTF-16 that use NULs.  UTF-8 is recommended.
+
+:func:`unicode_csv_reader` below is a generator that wraps :class:`csv.reader`
+to handle Unicode CSV data (a list of Unicode strings).  :func:`utf_8_encoder`
+is a generator that encodes the Unicode strings as UTF-8, one string (or row) at
+a time.  The encoded strings are parsed by the CSV reader, and
+:func:`unicode_csv_reader` decodes the UTF-8-encoded cells back into Unicode::
+
+   import csv
+
+   def unicode_csv_reader(unicode_csv_data, dialect=csv.excel, **kwargs):
+       # csv.py doesn't do Unicode; encode temporarily as UTF-8:
+       csv_reader = csv.reader(utf_8_encoder(unicode_csv_data),
+                               dialect=dialect, **kwargs)
+       for row in csv_reader:
+           # decode UTF-8 back to Unicode, cell by cell:
+           yield [unicode(cell, 'utf-8') for cell in row]
+
+   def utf_8_encoder(unicode_csv_data):
+       for line in unicode_csv_data:
+           yield line.encode('utf-8')
+
+For all other encodings the following :class:`UnicodeReader` and
+:class:`UnicodeWriter` classes can be used. They take an additional *encoding*
+parameter in their constructor and make sure that the data passes the real
+reader or writer encoded as UTF-8::
+
+   import csv, codecs, cStringIO
+
+   class UTF8Recoder:
+       """
+       Iterator that reads an encoded stream and reencodes the input to UTF-8
+       """
+       def __init__(self, f, encoding):
+           self.reader = codecs.getreader(encoding)(f)
+
+       def __iter__(self):
+           return self
+
+       def __next__(self):
+           return next(self.reader).encode("utf-8")
+
+   class UnicodeReader:
+       """
+       A CSV reader which will iterate over lines in the CSV file "f",
+       which is encoded in the given encoding.
+       """
+
+       def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
+           f = UTF8Recoder(f, encoding)
+           self.reader = csv.reader(f, dialect=dialect, **kwds)
+
+       def __next__(self):
+           row = next(self.reader)
+           return [unicode(s, "utf-8") for s in row]
+
+       def __iter__(self):
+           return self
+
+   class UnicodeWriter:
+       """
+       A CSV writer which will write rows to CSV file "f",
+       which is encoded in the given encoding.
+       """
+
+       def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
+           # Redirect output to a queue
+           self.queue = cStringIO.StringIO()
+           self.writer = csv.writer(self.queue, dialect=dialect, **kwds)
+           self.stream = f
+           self.encoder = codecs.getincrementalencoder(encoding)()
+
+       def writerow(self, row):
+           self.writer.writerow([s.encode("utf-8") for s in row])
+           # Fetch UTF-8 output from the queue ...
+           data = self.queue.getvalue()
+           data = data.decode("utf-8")
+           # ... and reencode it into the target encoding
+           data = self.encoder.encode(data)
+           # write to the target stream
+           self.stream.write(data)
+           # empty queue
+           self.queue.truncate(0)
+
+       def writerows(self, rows):
+           for row in rows:
+               self.writerow(row)
+

Doc/library/curses.ascii.rst

@@ -0,0 +1,228 @@
+
+:mod:`curses.ascii` --- Utilities for ASCII characters
+======================================================
+
+.. module:: curses.ascii
+   :synopsis: Constants and set-membership functions for ASCII characters.
+.. moduleauthor:: Eric S. Raymond <esr@thyrsus.com>
+.. sectionauthor:: Eric S. Raymond <esr@thyrsus.com>
+
+
+.. versionadded:: 1.6
+
+The :mod:`curses.ascii` module supplies name constants for ASCII characters and
+functions to test membership in various ASCII character classes.  The constants
+supplied are names for control characters as follows:
+
++--------------+----------------------------------------------+
+| Name         | Meaning                                      |
++==============+==============================================+
+| :const:`NUL` |                                              |
++--------------+----------------------------------------------+
+| :const:`SOH` | Start of heading, console interrupt          |
++--------------+----------------------------------------------+
+| :const:`STX` | Start of text                                |
++--------------+----------------------------------------------+
+| :const:`ETX` | End of text                                  |
++--------------+----------------------------------------------+
+| :const:`EOT` | End of transmission                          |
++--------------+----------------------------------------------+
+| :const:`ENQ` | Enquiry, goes with :const:`ACK` flow control |
++--------------+----------------------------------------------+
+| :const:`ACK` | Acknowledgement                              |
++--------------+----------------------------------------------+
+| :const:`BEL` | Bell                                         |
++--------------+----------------------------------------------+
+| :const:`BS`  | Backspace                                    |
++--------------+----------------------------------------------+
+| :const:`TAB` | Tab                                          |
++--------------+----------------------------------------------+
+| :const:`HT`  | Alias for :const:`TAB`: "Horizontal tab"     |
++--------------+----------------------------------------------+
+| :const:`LF`  | Line feed                                    |
++--------------+----------------------------------------------+
+| :const:`NL`  | Alias for :const:`LF`: "New line"            |
++--------------+----------------------------------------------+
+| :const:`VT`  | Vertical tab                                 |
++--------------+----------------------------------------------+
+| :const:`FF`  | Form feed                                    |
++--------------+----------------------------------------------+
+| :const:`CR`  | Carriage return                              |
++--------------+----------------------------------------------+
+| :const:`SO`  | Shift-out, begin alternate character set     |
++--------------+----------------------------------------------+
+| :const:`SI`  | Shift-in, resume default character set       |
++--------------+----------------------------------------------+
+| :const:`DLE` | Data-link escape                             |
++--------------+----------------------------------------------+
+| :const:`DC1` | XON, for flow control                        |
++--------------+----------------------------------------------+
+| :const:`DC2` | Device control 2, block-mode flow control    |
++--------------+----------------------------------------------+
+| :const:`DC3` | XOFF, for flow control                       |
++--------------+----------------------------------------------+
+| :const:`DC4` | Device control 4                             |
++--------------+----------------------------------------------+
+| :const:`NAK` | Negative acknowledgement                     |
++--------------+----------------------------------------------+
+| :const:`SYN` | Synchronous idle                             |
++--------------+----------------------------------------------+
+| :const:`ETB` | End transmission block                       |
++--------------+----------------------------------------------+
+| :const:`CAN` | Cancel                                       |
++--------------+----------------------------------------------+
+| :const:`EM`  | End of medium                                |
++--------------+----------------------------------------------+
+| :const:`SUB` | Substitute                                   |
++--------------+----------------------------------------------+
+| :const:`ESC` | Escape                                       |
++--------------+----------------------------------------------+
+| :const:`FS`  | File separator                               |
++--------------+----------------------------------------------+
+| :const:`GS`  | Group separator                              |
++--------------+----------------------------------------------+
+| :const:`RS`  | Record separator, block-mode terminator      |
++--------------+----------------------------------------------+
+| :const:`US`  | Unit separator                               |
++--------------+----------------------------------------------+
+| :const:`SP`  | Space                                        |
++--------------+----------------------------------------------+
+| :const:`DEL` | Delete                                       |
++--------------+----------------------------------------------+
+
+Note that many of these have little practical significance in modern usage.  The
+mnemonics derive from teleprinter conventions that predate digital computers.
+
+The module supplies the following functions, patterned on those in the standard
+C library:
+
+
+.. function:: isalnum(c)
+
+   Checks for an ASCII alphanumeric character; it is equivalent to ``isalpha(c) or
+   isdigit(c)``.
+
+
+.. function:: isalpha(c)
+
+   Checks for an ASCII alphabetic character; it is equivalent to ``isupper(c) or
+   islower(c)``.
+
+
+.. function:: isascii(c)
+
+   Checks for a character value that fits in the 7-bit ASCII set.
+
+
+.. function:: isblank(c)
+
+   Checks for an ASCII whitespace character.
+
+
+.. function:: iscntrl(c)
+
+   Checks for an ASCII control character (in the range 0x00 to 0x1f).
+
+
+.. function:: isdigit(c)
+
+   Checks for an ASCII decimal digit, ``'0'`` through ``'9'``.  This is equivalent
+   to ``c in string.digits``.
+
+
+.. function:: isgraph(c)
+
+   Checks for ASCII any printable character except space.
+
+
+.. function:: islower(c)
+
+   Checks for an ASCII lower-case character.
+
+
+.. function:: isprint(c)
+
+   Checks for any ASCII printable character including space.
+
+
+.. function:: ispunct(c)
+
+   Checks for any printable ASCII character which is not a space or an alphanumeric
+   character.
+
+
+.. function:: isspace(c)
+
+   Checks for ASCII white-space characters; space, line feed, carriage return, form
+   feed, horizontal tab, vertical tab.
+
+
+.. function:: isupper(c)
+
+   Checks for an ASCII uppercase letter.
+
+
+.. function:: isxdigit(c)
+
+   Checks for an ASCII hexadecimal digit.  This is equivalent to ``c in
+   string.hexdigits``.
+
+
+.. function:: isctrl(c)
+
+   Checks for an ASCII control character (ordinal values 0 to 31).
+
+
+.. function:: ismeta(c)
+
+   Checks for a non-ASCII character (ordinal values 0x80 and above).
+
+These functions accept either integers or strings; when the argument is a
+string, it is first converted using the built-in function :func:`ord`.
+
+Note that all these functions check ordinal bit values derived from the  first
+character of the string you pass in; they do not actually know anything about
+the host machine's character encoding.  For functions  that know about the
+character encoding (and handle internationalization properly) see the
+:mod:`string` module.
+
+The following two functions take either a single-character string or integer
+byte value; they return a value of the same type.
+
+
+.. function:: ascii(c)
+
+   Return the ASCII value corresponding to the low 7 bits of *c*.
+
+
+.. function:: ctrl(c)
+
+   Return the control character corresponding to the given character (the character
+   bit value is bitwise-anded with 0x1f).
+
+
+.. function:: alt(c)
+
+   Return the 8-bit character corresponding to the given ASCII character (the
+   character bit value is bitwise-ored with 0x80).
+
+The following function takes either a single-character string or integer value;
+it returns a string.
+
+
+.. function:: unctrl(c)
+
+   Return a string representation of the ASCII character *c*.  If *c* is printable,
+   this string is the character itself.  If the character is a control character
+   (0x00-0x1f) the string consists of a caret (``'^'``) followed by the
+   corresponding uppercase letter. If the character is an ASCII delete (0x7f) the
+   string is ``'^?'``.  If the character has its meta bit (0x80) set, the meta bit
+   is stripped, the preceding rules applied, and ``'!'`` prepended to the result.
+
+
+.. data:: controlnames
+
+   A 33-element string array that contains the ASCII mnemonics for the thirty-two
+   ASCII control characters from 0 (NUL) to 0x1f (US), in order, plus the mnemonic
+   ``SP`` for the space character.
+

Doc/library/curses.panel.rst

@@ -0,0 +1,119 @@
+
+:mod:`curses.panel` --- A panel stack extension for curses.
+===========================================================
+
+.. module:: curses.panel
+   :synopsis: A panel stack extension that adds depth to  curses windows.
+.. sectionauthor:: A.M. Kuchling <amk@amk.ca>
+
+
+Panels are windows with the added feature of depth, so they can be stacked on
+top of each other, and only the visible portions of each window will be
+displayed.  Panels can be added, moved up or down in the stack, and removed.
+
+
+.. _cursespanel-functions:
+
+Functions
+---------
+
+The module :mod:`curses.panel` defines the following functions:
+
+
+.. function:: bottom_panel()
+
+   Returns the bottom panel in the panel stack.
+
+
+.. function:: new_panel(win)
+
+   Returns a panel object, associating it with the given window *win*. Be aware
+   that you need to keep the returned panel object referenced explicitly.  If you
+   don't, the panel object is garbage collected and removed from the panel stack.
+
+
+.. function:: top_panel()
+
+   Returns the top panel in the panel stack.
+
+
+.. function:: update_panels()
+
+   Updates the virtual screen after changes in the panel stack. This does not call
+   :func:`curses.doupdate`, so you'll have to do this yourself.
+
+
+.. _curses-panel-objects:
+
+Panel Objects
+-------------
+
+Panel objects, as returned by :func:`new_panel` above, are windows with a
+stacking order. There's always a window associated with a panel which determines
+the content, while the panel methods are responsible for the window's depth in
+the panel stack.
+
+Panel objects have the following methods:
+
+
+.. method:: Panel.above()
+
+   Returns the panel above the current panel.
+
+
+.. method:: Panel.below()
+
+   Returns the panel below the current panel.
+
+
+.. method:: Panel.bottom()
+
+   Push the panel to the bottom of the stack.
+
+
+.. method:: Panel.hidden()
+
+   Returns true if the panel is hidden (not visible), false otherwise.
+
+
+.. method:: Panel.hide()
+
+   Hide the panel. This does not delete the object, it just makes the window on
+   screen invisible.
+
+
+.. method:: Panel.move(y, x)
+
+   Move the panel to the screen coordinates ``(y, x)``.
+
+
+.. method:: Panel.replace(win)
+
+   Change the window associated with the panel to the window *win*.
+
+
+.. method:: Panel.set_userptr(obj)
+
+   Set the panel's user pointer to *obj*. This is used to associate an arbitrary
+   piece of data with the panel, and can be any Python object.
+
+
+.. method:: Panel.show()
+
+   Display the panel (which might have been hidden).
+
+
+.. method:: Panel.top()
+
+   Push panel to the top of the stack.
+
+
+.. method:: Panel.userptr()
+
+   Returns the user pointer for the panel.  This might be any Python object.
+
+
+.. method:: Panel.window()
+
+   Returns the window object associated with the panel.
+

Doc/library/custominterp.rst

@@ -0,0 +1,20 @@
+
+.. _custominterp:
+
+**************************
+Custom Python Interpreters
+**************************
+
+The modules described in this chapter allow writing interfaces similar to
+Python's interactive interpreter.  If you want a Python interpreter that
+supports some special feature in addition to the Python language, you should
+look at the :mod:`code` module.  (The :mod:`codeop` module is lower-level, used
+to support compiling a possibly-incomplete chunk of Python code.)
+
+The full list of modules described in this chapter is:
+
+
+.. toctree::
+
+   code.rst
+   codeop.rst

Doc/library/datatypes.rst

@@ -0,0 +1,37 @@
+
+.. _datatypes:
+
+**********
+Data Types
+**********
+
+The modules described in this chapter provide a variety of specialized data
+types such as dates and times, fixed-type arrays, heap queues, synchronized
+queues, and sets.
+
+Python also provides some built-in data types, in particular,
+:class:`dict`, :class:`list`, :class:`set` and :class:`frozenset`, and
+:class:`tuple`.  The :class:`str` class can be used to handle binary data
+and 8-bit text, and the :class:`unicode` class to handle Unicode text.
+
+The following modules are documented in this chapter:
+
+
+.. toctree::
+
+   datetime.rst
+   calendar.rst
+   collections.rst
+   heapq.rst
+   bisect.rst
+   array.rst
+   sched.rst
+   mutex.rst
+   queue.rst
+   weakref.rst
+   userdict.rst
+   types.rst
+   new.rst
+   copy.rst
+   pprint.rst
+   repr.rst

Doc/library/dbhash.rst

@@ -0,0 +1,114 @@
+
+:mod:`dbhash` --- DBM-style interface to the BSD database library
+=================================================================
+
+.. module:: dbhash
+   :synopsis: DBM-style interface to the BSD database library.
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+.. index:: module: bsddb
+
+The :mod:`dbhash` module provides a function to open databases using the BSD
+``db`` library.  This module mirrors the interface of the other Python database
+modules that provide access to DBM-style databases.  The :mod:`bsddb` module is
+required  to use :mod:`dbhash`.
+
+This module provides an exception and a function:
+
+
+.. exception:: error
+
+   Exception raised on database errors other than :exc:`KeyError`.  It is a synonym
+   for :exc:`bsddb.error`.
+
+
+.. function:: open(path[, flag[, mode]])
+
+   Open a ``db`` database and return the database object.  The *path* argument is
+   the name of the database file.
+
+   The *flag* argument can be:
+
+   +---------+-------------------------------------------+
+   | Value   | Meaning                                   |
+   +=========+===========================================+
+   | ``'r'`` | Open existing database for reading only   |
+   |         | (default)                                 |
+   +---------+-------------------------------------------+
+   | ``'w'`` | Open existing database for reading and    |
+   |         | writing                                   |
+   +---------+-------------------------------------------+
+   | ``'c'`` | Open database for reading and writing,    |
+   |         | creating it if it doesn't exist           |
+   +---------+-------------------------------------------+
+   | ``'n'`` | Always create a new, empty database, open |
+   |         | for reading and writing                   |
+   +---------+-------------------------------------------+
+
+   For platforms on which the BSD ``db`` library supports locking, an ``'l'``
+   can be appended to indicate that locking should be used.
+
+   The optional *mode* parameter is used to indicate the Unix permission bits that
+   should be set if a new database must be created; this will be masked by the
+   current umask value for the process.
+
+
+.. seealso::
+
+   Module :mod:`anydbm`
+      Generic interface to ``dbm``\ -style databases.
+
+   Module :mod:`bsddb`
+      Lower-level interface to the BSD ``db`` library.
+
+   Module :mod:`whichdb`
+      Utility module used to determine the type of an existing database.
+
+
+.. _dbhash-objects:
+
+Database Objects
+----------------
+
+The database objects returned by :func:`open` provide the methods  common to all
+the DBM-style databases and mapping objects.  The following methods are
+available in addition to the standard methods.
+
+
+.. method:: dbhash.first()
+
+   It's possible to loop over every key/value pair in the database using this
+   method   and the :meth:`next` method.  The traversal is ordered by the databases
+   internal hash values, and won't be sorted by the key values.  This method
+   returns the starting key.
+
+
+.. method:: dbhash.last()
+
+   Return the last key/value pair in a database traversal.  This may be used to
+   begin a reverse-order traversal; see :meth:`previous`.
+
+
+.. method:: dbhash.next()
+
+   Returns the key next key/value pair in a database traversal.  The following code
+   prints every key in the database ``db``, without having to create a list in
+   memory that contains them all::
+
+      print db.first()
+      for i in range(1, len(db)):
+          print db.next()
+
+
+.. method:: dbhash.previous()
+
+   Returns the previous key/value pair in a forward-traversal of the database. In
+   conjunction with :meth:`last`, this may be used to implement a reverse-order
+   traversal.
+
+
+.. method:: dbhash.sync()
+
+   This method forces any unwritten data to be written to the disk.
+

Doc/library/dbm.rst

@@ -0,0 +1,74 @@
+
+:mod:`dbm` --- Simple "database" interface
+==========================================
+
+.. module:: dbm
+   :platform: Unix
+   :synopsis: The standard "database" interface, based on ndbm.
+
+
+The :mod:`dbm` module provides an interface to the Unix "(n)dbm" library.  Dbm
+objects behave like mappings (dictionaries), except that keys and values are
+always strings. Printing a dbm object doesn't print the keys and values, and the
+:meth:`items` and :meth:`values` methods are not supported.
+
+This module can be used with the "classic" ndbm interface, the BSD DB
+compatibility interface, or the GNU GDBM compatibility interface. On Unix, the
+:program:`configure` script will attempt to locate the appropriate header file
+to simplify building this module.
+
+The module defines the following:
+
+
+.. exception:: error
+
+   Raised on dbm-specific errors, such as I/O errors. :exc:`KeyError` is raised for
+   general mapping errors like specifying an incorrect key.
+
+
+.. data:: library
+
+   Name of the ``ndbm`` implementation library used.
+
+
+.. function:: open(filename[, flag[, mode]])
+
+   Open a dbm database and return a dbm object.  The *filename* argument is the
+   name of the database file (without the :file:`.dir` or :file:`.pag` extensions;
+   note that the BSD DB implementation of the interface will append the extension
+   :file:`.db` and only create one file).
+
+   The optional *flag* argument must be one of these values:
+
+   +---------+-------------------------------------------+
+   | Value   | Meaning                                   |
+   +=========+===========================================+
+   | ``'r'`` | Open existing database for reading only   |
+   |         | (default)                                 |
+   +---------+-------------------------------------------+
+   | ``'w'`` | Open existing database for reading and    |
+   |         | writing                                   |
+   +---------+-------------------------------------------+
+   | ``'c'`` | Open database for reading and writing,    |
+   |         | creating it if it doesn't exist           |
+   +---------+-------------------------------------------+
+   | ``'n'`` | Always create a new, empty database, open |
+   |         | for reading and writing                   |
+   +---------+-------------------------------------------+
+
+   The optional *mode* argument is the Unix mode of the file, used only when the
+   database has to be created.  It defaults to octal ``0666`` (and will be
+   modified by the prevailing umask).
+
+
+.. seealso::
+
+   Module :mod:`anydbm`
+      Generic interface to ``dbm``\ -style databases.
+
+   Module :mod:`gdbm`
+      Similar interface to the GNU GDBM library.
+
+   Module :mod:`whichdb`
+      Utility module used to determine the type of an existing database.
+

Doc/library/development.rst

@@ -0,0 +1,22 @@
+
+.. _development:
+
+*****************
+Development Tools
+*****************
+
+The modules described in this chapter help you write software.  For example, the
+:mod:`pydoc` module takes a module and generates documentation based on the
+module's contents.  The :mod:`doctest` and :mod:`unittest` modules contains
+frameworks for writing unit tests that automatically exercise code and verify
+that the expected output  is produced.
+
+The list of modules described in this chapter is:
+
+
+.. toctree::
+
+   pydoc.rst
+   doctest.rst
+   unittest.rst
+   test.rst

Doc/library/difflib.rst

@@ -0,0 +1,644 @@
+
+:mod:`difflib` --- Helpers for computing deltas
+===============================================
+
+.. module:: difflib
+   :synopsis: Helpers for computing differences between objects.
+.. moduleauthor:: Tim Peters <tim_one@users.sourceforge.net>
+.. sectionauthor:: Tim Peters <tim_one@users.sourceforge.net>
+
+
+.. % LaTeXification by Fred L. Drake, Jr. <fdrake@acm.org>.
+
+.. versionadded:: 2.1
+
+
+.. class:: SequenceMatcher
+
+   This is a flexible class for comparing pairs of sequences of any type, so long
+   as the sequence elements are hashable.  The basic algorithm predates, and is a
+   little fancier than, an algorithm published in the late 1980's by Ratcliff and
+   Obershelp under the hyperbolic name "gestalt pattern matching."  The idea is to
+   find the longest contiguous matching subsequence that contains no "junk"
+   elements (the Ratcliff and Obershelp algorithm doesn't address junk).  The same
+   idea is then applied recursively to the pieces of the sequences to the left and
+   to the right of the matching subsequence.  This does not yield minimal edit
+   sequences, but does tend to yield matches that "look right" to people.
+
+   **Timing:** The basic Ratcliff-Obershelp algorithm is cubic time in the worst
+   case and quadratic time in the expected case. :class:`SequenceMatcher` is
+   quadratic time for the worst case and has expected-case behavior dependent in a
+   complicated way on how many elements the sequences have in common; best case
+   time is linear.
+
+
+.. class:: Differ
+
+   This is a class for comparing sequences of lines of text, and producing
+   human-readable differences or deltas.  Differ uses :class:`SequenceMatcher`
+   both to compare sequences of lines, and to compare sequences of characters
+   within similar (near-matching) lines.
+
+   Each line of a :class:`Differ` delta begins with a two-letter code:
+
+   +----------+-------------------------------------------+
+   | Code     | Meaning                                   |
+   +==========+===========================================+
+   | ``'- '`` | line unique to sequence 1                 |
+   +----------+-------------------------------------------+
+   | ``'+ '`` | line unique to sequence 2                 |
+   +----------+-------------------------------------------+
+   | ``'  '`` | line common to both sequences             |
+   +----------+-------------------------------------------+
+   | ``'? '`` | line not present in either input sequence |
+   +----------+-------------------------------------------+
+
+   Lines beginning with '``?``' attempt to guide the eye to intraline differences,
+   and were not present in either input sequence. These lines can be confusing if
+   the sequences contain tab characters.
+
+
+.. class:: HtmlDiff
+
+   This class can be used to create an HTML table (or a complete HTML file
+   containing the table) showing a side by side, line by line comparison of text
+   with inter-line and intra-line change highlights.  The table can be generated in
+   either full or contextual difference mode.
+
+   The constructor for this class is:
+
+
+   .. function:: __init__([tabsize][, wrapcolumn][, linejunk][, charjunk])
+
+      Initializes instance of :class:`HtmlDiff`.
+
+      *tabsize* is an optional keyword argument to specify tab stop spacing and
+      defaults to ``8``.
+
+      *wrapcolumn* is an optional keyword to specify column number where lines are
+      broken and wrapped, defaults to ``None`` where lines are not wrapped.
+
+      *linejunk* and *charjunk* are optional keyword arguments passed into ``ndiff()``
+      (used by :class:`HtmlDiff` to generate the side by side HTML differences).  See
+      ``ndiff()`` documentation for argument default values and descriptions.
+
+   The following methods are public:
+
+
+   .. function:: make_file(fromlines, tolines [, fromdesc][, todesc][, context][, numlines])
+
+      Compares *fromlines* and *tolines* (lists of strings) and returns a string which
+      is a complete HTML file containing a table showing line by line differences with
+      inter-line and intra-line changes highlighted.
+
+      *fromdesc* and *todesc* are optional keyword arguments to specify from/to file
+      column header strings (both default to an empty string).
+
+      *context* and *numlines* are both optional keyword arguments. Set *context* to
+      ``True`` when contextual differences are to be shown, else the default is
+      ``False`` to show the full files. *numlines* defaults to ``5``.  When *context*
+      is ``True`` *numlines* controls the number of context lines which surround the
+      difference highlights.  When *context* is ``False`` *numlines* controls the
+      number of lines which are shown before a difference highlight when using the
+      "next" hyperlinks (setting to zero would cause the "next" hyperlinks to place
+      the next difference highlight at the top of the browser without any leading
+      context).
+
+
+   .. function:: make_table(fromlines, tolines [, fromdesc][, todesc][, context][, numlines])
+
+      Compares *fromlines* and *tolines* (lists of strings) and returns a string which
+      is a complete HTML table showing line by line differences with inter-line and
+      intra-line changes highlighted.
+
+      The arguments for this method are the same as those for the :meth:`make_file`
+      method.
+
+   :file:`Tools/scripts/diff.py` is a command-line front-end to this class and
+   contains a good example of its use.
+
+   .. versionadded:: 2.4
+
+
+.. function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
+
+   Compare *a* and *b* (lists of strings); return a delta (a generator generating
+   the delta lines) in context diff format.
+
+   Context diffs are a compact way of showing just the lines that have changed plus
+   a few lines of context.  The changes are shown in a before/after style.  The
+   number of context lines is set by *n* which defaults to three.
+
+   By default, the diff control lines (those with ``***`` or ``---``) are created
+   with a trailing newline.  This is helpful so that inputs created from
+   :func:`file.readlines` result in diffs that are suitable for use with
+   :func:`file.writelines` since both the inputs and outputs have trailing
+   newlines.
+
+   For inputs that do not have trailing newlines, set the *lineterm* argument to
+   ``""`` so that the output will be uniformly newline free.
+
+   The context diff format normally has a header for filenames and modification
+   times.  Any or all of these may be specified using strings for *fromfile*,
+   *tofile*, *fromfiledate*, and *tofiledate*. The modification times are normally
+   expressed in the format returned by :func:`time.ctime`.  If not specified, the
+   strings default to blanks.
+
+   :file:`Tools/scripts/diff.py` is a command-line front-end for this function.
+
+   .. versionadded:: 2.3
+
+
+.. function:: get_close_matches(word, possibilities[, n][, cutoff])
+
+   Return a list of the best "good enough" matches.  *word* is a sequence for which
+   close matches are desired (typically a string), and *possibilities* is a list of
+   sequences against which to match *word* (typically a list of strings).
+
+   Optional argument *n* (default ``3``) is the maximum number of close matches to
+   return; *n* must be greater than ``0``.
+
+   Optional argument *cutoff* (default ``0.6``) is a float in the range [0, 1].
+   Possibilities that don't score at least that similar to *word* are ignored.
+
+   The best (no more than *n*) matches among the possibilities are returned in a
+   list, sorted by similarity score, most similar first. ::
+
+      >>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
+      ['apple', 'ape']
+      >>> import keyword
+      >>> get_close_matches('wheel', keyword.kwlist)
+      ['while']
+      >>> get_close_matches('apple', keyword.kwlist)
+      []
+      >>> get_close_matches('accept', keyword.kwlist)
+      ['except']
+
+
+.. function:: ndiff(a, b[, linejunk][, charjunk])
+
+   Compare *a* and *b* (lists of strings); return a :class:`Differ`\ -style delta
+   (a generator generating the delta lines).
+
+   Optional keyword parameters *linejunk* and *charjunk* are for filter functions
+   (or ``None``):
+
+   *linejunk*: A function that accepts a single string argument, and returns true
+   if the string is junk, or false if not. The default is (``None``), starting with
+   Python 2.3.  Before then, the default was the module-level function
+   :func:`IS_LINE_JUNK`, which filters out lines without visible characters, except
+   for at most one pound character (``'#'``). As of Python 2.3, the underlying
+   :class:`SequenceMatcher` class does a dynamic analysis of which lines are so
+   frequent as to constitute noise, and this usually works better than the pre-2.3
+   default.
+
+   *charjunk*: A function that accepts a character (a string of length 1), and
+   returns if the character is junk, or false if not. The default is module-level
+   function :func:`IS_CHARACTER_JUNK`, which filters out whitespace characters (a
+   blank or tab; note: bad idea to include newline in this!).
+
+   :file:`Tools/scripts/ndiff.py` is a command-line front-end to this function. ::
+
+      >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
+      ...              'ore\ntree\nemu\n'.splitlines(1))
+      >>> print ''.join(diff),
+      - one
+      ?  ^
+      + ore
+      ?  ^
+      - two
+      - three
+      ?  -
+      + tree
+      + emu
+
+
+.. function:: restore(sequence, which)
+
+   Return one of the two sequences that generated a delta.
+
+   Given a *sequence* produced by :meth:`Differ.compare` or :func:`ndiff`, extract
+   lines originating from file 1 or 2 (parameter *which*), stripping off line
+   prefixes.
+
+   Example::
+
+      >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
+      ...              'ore\ntree\nemu\n'.splitlines(1))
+      >>> diff = list(diff) # materialize the generated delta into a list
+      >>> print ''.join(restore(diff, 1)),
+      one
+      two
+      three
+      >>> print ''.join(restore(diff, 2)),
+      ore
+      tree
+      emu
+
+
+.. function:: unified_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
+
+   Compare *a* and *b* (lists of strings); return a delta (a generator generating
+   the delta lines) in unified diff format.
+
+   Unified diffs are a compact way of showing just the lines that have changed plus
+   a few lines of context.  The changes are shown in a inline style (instead of
+   separate before/after blocks).  The number of context lines is set by *n* which
+   defaults to three.
+
+   By default, the diff control lines (those with ``---``, ``+++``, or ``@@``) are
+   created with a trailing newline.  This is helpful so that inputs created from
+   :func:`file.readlines` result in diffs that are suitable for use with
+   :func:`file.writelines` since both the inputs and outputs have trailing
+   newlines.
+
+   For inputs that do not have trailing newlines, set the *lineterm* argument to
+   ``""`` so that the output will be uniformly newline free.
+
+   The context diff format normally has a header for filenames and modification
+   times.  Any or all of these may be specified using strings for *fromfile*,
+   *tofile*, *fromfiledate*, and *tofiledate*. The modification times are normally
+   expressed in the format returned by :func:`time.ctime`.  If not specified, the
+   strings default to blanks.
+
+   :file:`Tools/scripts/diff.py` is a command-line front-end for this function.
+
+   .. versionadded:: 2.3
+
+
+.. function:: IS_LINE_JUNK(line)
+
+   Return true for ignorable lines.  The line *line* is ignorable if *line* is
+   blank or contains a single ``'#'``, otherwise it is not ignorable.  Used as a
+   default for parameter *linejunk* in :func:`ndiff` before Python 2.3.
+
+
+.. function:: IS_CHARACTER_JUNK(ch)
+
+   Return true for ignorable characters.  The character *ch* is ignorable if *ch*
+   is a space or tab, otherwise it is not ignorable.  Used as a default for
+   parameter *charjunk* in :func:`ndiff`.
+
+
+.. seealso::
+
+   `Pattern Matching: The Gestalt Approach <http://www.ddj.com/184407970?pgno=5>`_
+      Discussion of a similar algorithm by John W. Ratcliff and D. E. Metzener. This
+      was published in `Dr. Dobb's Journal <http://www.ddj.com/>`_ in July, 1988.
+
+
+.. _sequence-matcher:
+
+SequenceMatcher Objects
+-----------------------
+
+The :class:`SequenceMatcher` class has this constructor:
+
+
+.. class:: SequenceMatcher([isjunk[, a[, b]]])
+
+   Optional argument *isjunk* must be ``None`` (the default) or a one-argument
+   function that takes a sequence element and returns true if and only if the
+   element is "junk" and should be ignored. Passing ``None`` for *isjunk* is
+   equivalent to passing ``lambda x: 0``; in other words, no elements are ignored.
+   For example, pass::
+
+      lambda x: x in " \t"
+
+   if you're comparing lines as sequences of characters, and don't want to synch up
+   on blanks or hard tabs.
+
+   The optional arguments *a* and *b* are sequences to be compared; both default to
+   empty strings.  The elements of both sequences must be hashable.
+
+:class:`SequenceMatcher` objects have the following methods:
+
+
+.. method:: SequenceMatcher.set_seqs(a, b)
+
+   Set the two sequences to be compared.
+
+:class:`SequenceMatcher` computes and caches detailed information about the
+second sequence, so if you want to compare one sequence against many sequences,
+use :meth:`set_seq2` to set the commonly used sequence once and call
+:meth:`set_seq1` repeatedly, once for each of the other sequences.
+
+
+.. method:: SequenceMatcher.set_seq1(a)
+
+   Set the first sequence to be compared.  The second sequence to be compared is
+   not changed.
+
+
+.. method:: SequenceMatcher.set_seq2(b)
+
+   Set the second sequence to be compared.  The first sequence to be compared is
+   not changed.
+
+
+.. method:: SequenceMatcher.find_longest_match(alo, ahi, blo, bhi)
+
+   Find longest matching block in ``a[alo:ahi]`` and ``b[blo:bhi]``.
+
+   If *isjunk* was omitted or ``None``, :meth:`get_longest_match` returns ``(i, j,
+   k)`` such that ``a[i:i+k]`` is equal to ``b[j:j+k]``, where ``alo <= i <= i+k <=
+   ahi`` and ``blo <= j <= j+k <= bhi``. For all ``(i', j', k')`` meeting those
+   conditions, the additional conditions ``k >= k'``, ``i <= i'``, and if ``i ==
+   i'``, ``j <= j'`` are also met. In other words, of all maximal matching blocks,
+   return one that starts earliest in *a*, and of all those maximal matching blocks
+   that start earliest in *a*, return the one that starts earliest in *b*. ::
+
+      >>> s = SequenceMatcher(None, " abcd", "abcd abcd")
+      >>> s.find_longest_match(0, 5, 0, 9)
+      (0, 4, 5)
+
+   If *isjunk* was provided, first the longest matching block is determined as
+   above, but with the additional restriction that no junk element appears in the
+   block.  Then that block is extended as far as possible by matching (only) junk
+   elements on both sides. So the resulting block never matches on junk except as
+   identical junk happens to be adjacent to an interesting match.
+
+   Here's the same example as before, but considering blanks to be junk. That
+   prevents ``' abcd'`` from matching the ``' abcd'`` at the tail end of the second
+   sequence directly.  Instead only the ``'abcd'`` can match, and matches the
+   leftmost ``'abcd'`` in the second sequence::
+
+      >>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
+      >>> s.find_longest_match(0, 5, 0, 9)
+      (1, 0, 4)
+
+   If no blocks match, this returns ``(alo, blo, 0)``.
+
+
+.. method:: SequenceMatcher.get_matching_blocks()
+
+   Return list of triples describing matching subsequences. Each triple is of the
+   form ``(i, j, n)``, and means that ``a[i:i+n] == b[j:j+n]``.  The triples are
+   monotonically increasing in *i* and *j*.
+
+   The last triple is a dummy, and has the value ``(len(a), len(b), 0)``.  It is
+   the only triple with ``n == 0``.  If ``(i, j, n)`` and ``(i', j', n')`` are
+   adjacent triples in the list, and the second is not the last triple in the list,
+   then ``i+n != i'`` or ``j+n != j'``; in other words, adjacent triples always
+   describe non-adjacent equal blocks.
+
+   .. % Explain why a dummy is used!
+
+   .. versionchanged:: 2.5
+      The guarantee that adjacent triples always describe non-adjacent blocks was
+      implemented.
+
+   ::
+
+      >>> s = SequenceMatcher(None, "abxcd", "abcd")
+      >>> s.get_matching_blocks()
+      [(0, 0, 2), (3, 2, 2), (5, 4, 0)]
+
+
+.. method:: SequenceMatcher.get_opcodes()
+
+   Return list of 5-tuples describing how to turn *a* into *b*. Each tuple is of
+   the form ``(tag, i1, i2, j1, j2)``.  The first tuple has ``i1 == j1 == 0``, and
+   remaining tuples have *i1* equal to the *i2* from the preceding tuple, and,
+   likewise, *j1* equal to the previous *j2*.
+
+   The *tag* values are strings, with these meanings:
+
+   +---------------+---------------------------------------------+
+   | Value         | Meaning                                     |
+   +===============+=============================================+
+   | ``'replace'`` | ``a[i1:i2]`` should be replaced by          |
+   |               | ``b[j1:j2]``.                               |
+   +---------------+---------------------------------------------+
+   | ``'delete'``  | ``a[i1:i2]`` should be deleted.  Note that  |
+   |               | ``j1 == j2`` in this case.                  |
+   +---------------+---------------------------------------------+
+   | ``'insert'``  | ``b[j1:j2]`` should be inserted at          |
+   |               | ``a[i1:i1]``. Note that ``i1 == i2`` in     |
+   |               | this case.                                  |
+   +---------------+---------------------------------------------+
+   | ``'equal'``   | ``a[i1:i2] == b[j1:j2]`` (the sub-sequences |
+   |               | are equal).                                 |
+   +---------------+---------------------------------------------+
+
+   For example::
+
+      >>> a = "qabxcd"
+      >>> b = "abycdf"
+      >>> s = SequenceMatcher(None, a, b)
+      >>> for tag, i1, i2, j1, j2 in s.get_opcodes():
+      ...    print ("%7s a[%d:%d] (%s) b[%d:%d] (%s)" %
+      ...           (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2]))
+       delete a[0:1] (q) b[0:0] ()
+        equal a[1:3] (ab) b[0:2] (ab)
+      replace a[3:4] (x) b[2:3] (y)
+        equal a[4:6] (cd) b[3:5] (cd)
+       insert a[6:6] () b[5:6] (f)
+
+
+.. method:: SequenceMatcher.get_grouped_opcodes([n])
+
+   Return a generator of groups with up to *n* lines of context.
+
+   Starting with the groups returned by :meth:`get_opcodes`, this method splits out
+   smaller change clusters and eliminates intervening ranges which have no changes.
+
+   The groups are returned in the same format as :meth:`get_opcodes`.
+
+   .. versionadded:: 2.3
+
+
+.. method:: SequenceMatcher.ratio()
+
+   Return a measure of the sequences' similarity as a float in the range [0, 1].
+
+   Where T is the total number of elements in both sequences, and M is the number
+   of matches, this is 2.0\*M / T. Note that this is ``1.0`` if the sequences are
+   identical, and ``0.0`` if they have nothing in common.
+
+   This is expensive to compute if :meth:`get_matching_blocks` or
+   :meth:`get_opcodes` hasn't already been called, in which case you may want to
+   try :meth:`quick_ratio` or :meth:`real_quick_ratio` first to get an upper bound.
+
+
+.. method:: SequenceMatcher.quick_ratio()
+
+   Return an upper bound on :meth:`ratio` relatively quickly.
+
+   This isn't defined beyond that it is an upper bound on :meth:`ratio`, and is
+   faster to compute.
+
+
+.. method:: SequenceMatcher.real_quick_ratio()
+
+   Return an upper bound on :meth:`ratio` very quickly.
+
+   This isn't defined beyond that it is an upper bound on :meth:`ratio`, and is
+   faster to compute than either :meth:`ratio` or :meth:`quick_ratio`.
+
+The three methods that return the ratio of matching to total characters can give
+different results due to differing levels of approximation, although
+:meth:`quick_ratio` and :meth:`real_quick_ratio` are always at least as large as
+:meth:`ratio`::
+
+   >>> s = SequenceMatcher(None, "abcd", "bcde")
+   >>> s.ratio()
+   0.75
+   >>> s.quick_ratio()
+   0.75
+   >>> s.real_quick_ratio()
+   1.0
+
+
+.. _sequencematcher-examples:
+
+SequenceMatcher Examples
+------------------------
+
+This example compares two strings, considering blanks to be "junk:" ::
+
+   >>> s = SequenceMatcher(lambda x: x == " ",
+   ...                     "private Thread currentThread;",
+   ...                     "private volatile Thread currentThread;")
+
+:meth:`ratio` returns a float in [0, 1], measuring the similarity of the
+sequences.  As a rule of thumb, a :meth:`ratio` value over 0.6 means the
+sequences are close matches::
+
+   >>> print round(s.ratio(), 3)
+   0.866
+
+If you're only interested in where the sequences match,
+:meth:`get_matching_blocks` is handy::
+
+   >>> for block in s.get_matching_blocks():
+   ...     print "a[%d] and b[%d] match for %d elements" % block
+   a[0] and b[0] match for 8 elements
+   a[8] and b[17] match for 6 elements
+   a[14] and b[23] match for 15 elements
+   a[29] and b[38] match for 0 elements
+
+Note that the last tuple returned by :meth:`get_matching_blocks` is always a
+dummy, ``(len(a), len(b), 0)``, and this is the only case in which the last
+tuple element (number of elements matched) is ``0``.
+
+If you want to know how to change the first sequence into the second, use
+:meth:`get_opcodes`::
+
+   >>> for opcode in s.get_opcodes():
+   ...     print "%6s a[%d:%d] b[%d:%d]" % opcode
+    equal a[0:8] b[0:8]
+   insert a[8:8] b[8:17]
+    equal a[8:14] b[17:23]
+    equal a[14:29] b[23:38]
+
+See also the function :func:`get_close_matches` in this module, which shows how
+simple code building on :class:`SequenceMatcher` can be used to do useful work.
+
+
+.. _differ-objects:
+
+Differ Objects
+--------------
+
+Note that :class:`Differ`\ -generated deltas make no claim to be **minimal**
+diffs. To the contrary, minimal diffs are often counter-intuitive, because they
+synch up anywhere possible, sometimes accidental matches 100 pages apart.
+Restricting synch points to contiguous matches preserves some notion of
+locality, at the occasional cost of producing a longer diff.
+
+The :class:`Differ` class has this constructor:
+
+
+.. class:: Differ([linejunk[, charjunk]])
+
+   Optional keyword parameters *linejunk* and *charjunk* are for filter functions
+   (or ``None``):
+
+   *linejunk*: A function that accepts a single string argument, and returns true
+   if the string is junk.  The default is ``None``, meaning that no line is
+   considered junk.
+
+   *charjunk*: A function that accepts a single character argument (a string of
+   length 1), and returns true if the character is junk. The default is ``None``,
+   meaning that no character is considered junk.
+
+:class:`Differ` objects are used (deltas generated) via a single method:
+
+
+.. method:: Differ.compare(a, b)
+
+   Compare two sequences of lines, and generate the delta (a sequence of lines).
+
+   Each sequence must contain individual single-line strings ending with newlines.
+   Such sequences can be obtained from the :meth:`readlines` method of file-like
+   objects.  The delta generated also consists of newline-terminated strings, ready
+   to be printed as-is via the :meth:`writelines` method of a file-like object.
+
+
+.. _differ-examples:
+
+Differ Example
+--------------
+
+This example compares two texts. First we set up the texts, sequences of
+individual single-line strings ending with newlines (such sequences can also be
+obtained from the :meth:`readlines` method of file-like objects)::
+
+   >>> text1 = '''  1. Beautiful is better than ugly.
+   ...   2. Explicit is better than implicit.
+   ...   3. Simple is better than complex.
+   ...   4. Complex is better than complicated.
+   ... '''.splitlines(1)
+   >>> len(text1)
+   4
+   >>> text1[0][-1]
+   '\n'
+   >>> text2 = '''  1. Beautiful is better than ugly.
+   ...   3.   Simple is better than complex.
+   ...   4. Complicated is better than complex.
+   ...   5. Flat is better than nested.
+   ... '''.splitlines(1)
+
+Next we instantiate a Differ object::
+
+   >>> d = Differ()
+
+Note that when instantiating a :class:`Differ` object we may pass functions to
+filter out line and character "junk."  See the :meth:`Differ` constructor for
+details.
+
+Finally, we compare the two::
+
+   >>> result = list(d.compare(text1, text2))
+
+``result`` is a list of strings, so let's pretty-print it::
+
+   >>> from pprint import pprint
+   >>> pprint(result)
+   ['    1. Beautiful is better than ugly.\n',
+    '-   2. Explicit is better than implicit.\n',
+    '-   3. Simple is better than complex.\n',
+    '+   3.   Simple is better than complex.\n',
+    '?     ++                                \n',
+    '-   4. Complex is better than complicated.\n',
+    '?            ^                     ---- ^  \n',
+    '+   4. Complicated is better than complex.\n',
+    '?           ++++ ^                      ^  \n',
+    '+   5. Flat is better than nested.\n']
+
+As a single multi-line string it looks like this::
+
+   >>> import sys
+   >>> sys.stdout.writelines(result)
+       1. Beautiful is better than ugly.
+   -   2. Explicit is better than implicit.
+   -   3. Simple is better than complex.
+   +   3.   Simple is better than complex.
+   ?     ++
+   -   4. Complex is better than complicated.
+   ?            ^                     ---- ^
+   +   4. Complicated is better than complex.
+   ?           ++++ ^                      ^
+   +   5. Flat is better than nested.
+

Doc/library/dircache.rst

@@ -0,0 +1,56 @@
+
+:mod:`dircache` --- Cached directory listings
+=============================================
+
+.. module:: dircache
+   :synopsis: Return directory listing, with cache mechanism.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+The :mod:`dircache` module defines a function for reading directory listing
+using a cache, and cache invalidation using the *mtime* of the directory.
+Additionally, it defines a function to annotate directories by appending a
+slash.
+
+The :mod:`dircache` module defines the following functions:
+
+
+.. function:: reset()
+
+   Resets the directory cache.
+
+
+.. function:: listdir(path)
+
+   Return a directory listing of *path*, as gotten from :func:`os.listdir`. Note
+   that unless *path* changes, further call to :func:`listdir` will not re-read the
+   directory structure.
+
+   Note that the list returned should be regarded as read-only. (Perhaps a future
+   version should change it to return a tuple?)
+
+
+.. function:: opendir(path)
+
+   Same as :func:`listdir`. Defined for backwards compatibility.
+
+
+.. function:: annotate(head, list)
+
+   Assume *list* is a list of paths relative to *head*, and append, in place, a
+   ``'/'`` to each path which points to a directory.
+
+::
+
+   >>> import dircache
+   >>> a = dircache.listdir('/')
+   >>> a = a[:] # Copy the return value so we can change 'a'
+   >>> a
+   ['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+
+   found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz']
+   >>> dircache.annotate('/', a)
+   >>> a
+   ['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/
+   ', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm
+   linuz']
+

Doc/library/dis.rst

@@ -0,0 +1,775 @@
+
+:mod:`dis` --- Disassembler for Python byte code
+================================================
+
+.. module:: dis
+   :synopsis: Disassembler for Python byte code.
+
+
+The :mod:`dis` module supports the analysis of Python byte code by disassembling
+it.  Since there is no Python assembler, this module defines the Python assembly
+language.  The Python byte code which this module takes as an input is defined
+in the file  :file:`Include/opcode.h` and used by the compiler and the
+interpreter.
+
+Example: Given the function :func:`myfunc`::
+
+   def myfunc(alist):
+       return len(alist)
+
+the following command can be used to get the disassembly of :func:`myfunc`::
+
+   >>> dis.dis(myfunc)
+     2           0 LOAD_GLOBAL              0 (len)
+                 3 LOAD_FAST                0 (alist)
+                 6 CALL_FUNCTION            1
+                 9 RETURN_VALUE
+
+(The "2" is a line number).
+
+The :mod:`dis` module defines the following functions and constants:
+
+
+.. function:: dis([bytesource])
+
+   Disassemble the *bytesource* object. *bytesource* can denote either a module, a
+   class, a method, a function, or a code object.   For a module, it disassembles
+   all functions.  For a class, it disassembles all methods.  For a single code
+   sequence, it prints one line per byte code instruction.  If no object is
+   provided, it disassembles the last traceback.
+
+
+.. function:: distb([tb])
+
+   Disassembles the top-of-stack function of a traceback, using the last traceback
+   if none was passed.  The instruction causing the exception is indicated.
+
+
+.. function:: disassemble(code[, lasti])
+
+   Disassembles a code object, indicating the last instruction if *lasti* was
+   provided.  The output is divided in the following columns:
+
+   #. the line number, for the first instruction of each line
+   #. the current instruction, indicated as ``-->``,
+   #. a labelled instruction, indicated with ``>>``,
+   #. the address of the instruction,
+   #. the operation code name,
+   #. operation parameters, and
+   #. interpretation of the parameters in parentheses.
+
+   The parameter interpretation recognizes local and global variable names,
+   constant values, branch targets, and compare operators.
+
+
+.. function:: disco(code[, lasti])
+
+   A synonym for disassemble.  It is more convenient to type, and kept for
+   compatibility with earlier Python releases.
+
+
+.. data:: opname
+
+   Sequence of operation names, indexable using the byte code.
+
+
+.. data:: opmap
+
+   Dictionary mapping byte codes to operation names.
+
+
+.. data:: cmp_op
+
+   Sequence of all compare operation names.
+
+
+.. data:: hasconst
+
+   Sequence of byte codes that have a constant parameter.
+
+
+.. data:: hasfree
+
+   Sequence of byte codes that access a free variable.
+
+
+.. data:: hasname
+
+   Sequence of byte codes that access an attribute by name.
+
+
+.. data:: hasjrel
+
+   Sequence of byte codes that have a relative jump target.
+
+
+.. data:: hasjabs
+
+   Sequence of byte codes that have an absolute jump target.
+
+
+.. data:: haslocal
+
+   Sequence of byte codes that access a local variable.
+
+
+.. data:: hascompare
+
+   Sequence of byte codes of Boolean operations.
+
+
+.. _bytecodes:
+
+Python Byte Code Instructions
+-----------------------------
+
+The Python compiler currently generates the following byte code instructions.
+
+
+.. opcode:: STOP_CODE ()
+
+   Indicates end-of-code to the compiler, not used by the interpreter.
+
+
+.. opcode:: NOP ()
+
+   Do nothing code.  Used as a placeholder by the bytecode optimizer.
+
+
+.. opcode:: POP_TOP ()
+
+   Removes the top-of-stack (TOS) item.
+
+
+.. opcode:: ROT_TWO ()
+
+   Swaps the two top-most stack items.
+
+
+.. opcode:: ROT_THREE ()
+
+   Lifts second and third stack item one position up, moves top down to position
+   three.
+
+
+.. opcode:: ROT_FOUR ()
+
+   Lifts second, third and forth stack item one position up, moves top down to
+   position four.
+
+
+.. opcode:: DUP_TOP ()
+
+   Duplicates the reference on top of the stack.
+
+Unary Operations take the top of the stack, apply the operation, and push the
+result back on the stack.
+
+
+.. opcode:: UNARY_POSITIVE ()
+
+   Implements ``TOS = +TOS``.
+
+
+.. opcode:: UNARY_NEGATIVE ()
+
+   Implements ``TOS = -TOS``.
+
+
+.. opcode:: UNARY_NOT ()
+
+   Implements ``TOS = not TOS``.
+
+
+.. opcode:: UNARY_INVERT ()
+
+   Implements ``TOS = ~TOS``.
+
+
+.. opcode:: GET_ITER ()
+
+   Implements ``TOS = iter(TOS)``.
+
+Binary operations remove the top of the stack (TOS) and the second top-most
+stack item (TOS1) from the stack.  They perform the operation, and put the
+result back on the stack.
+
+
+.. opcode:: BINARY_POWER ()
+
+   Implements ``TOS = TOS1 ** TOS``.
+
+
+.. opcode:: BINARY_MULTIPLY ()
+
+   Implements ``TOS = TOS1 * TOS``.
+
+
+.. opcode:: BINARY_FLOOR_DIVIDE ()
+
+   Implements ``TOS = TOS1 // TOS``.
+
+
+.. opcode:: BINARY_TRUE_DIVIDE ()
+
+   Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is in
+   effect.
+
+
+.. opcode:: BINARY_MODULO ()
+
+   Implements ``TOS = TOS1 % TOS``.
+
+
+.. opcode:: BINARY_ADD ()
+
+   Implements ``TOS = TOS1 + TOS``.
+
+
+.. opcode:: BINARY_SUBTRACT ()
+
+   Implements ``TOS = TOS1 - TOS``.
+
+
+.. opcode:: BINARY_SUBSCR ()
+
+   Implements ``TOS = TOS1[TOS]``.
+
+
+.. opcode:: BINARY_LSHIFT ()
+
+   Implements ``TOS = TOS1 << TOS``.
+
+
+.. opcode:: BINARY_RSHIFT ()
+
+   Implements ``TOS = TOS1 >> TOS``.
+
+
+.. opcode:: BINARY_AND ()
+
+   Implements ``TOS = TOS1 & TOS``.
+
+
+.. opcode:: BINARY_XOR ()
+
+   Implements ``TOS = TOS1 ^ TOS``.
+
+
+.. opcode:: BINARY_OR ()
+
+   Implements ``TOS = TOS1 | TOS``.
+
+In-place operations are like binary operations, in that they remove TOS and
+TOS1, and push the result back on the stack, but the operation is done in-place
+when TOS1 supports it, and the resulting TOS may be (but does not have to be)
+the original TOS1.
+
+
+.. opcode:: INPLACE_POWER ()
+
+   Implements in-place ``TOS = TOS1 ** TOS``.
+
+
+.. opcode:: INPLACE_MULTIPLY ()
+
+   Implements in-place ``TOS = TOS1 * TOS``.
+
+
+.. opcode:: INPLACE_FLOOR_DIVIDE ()
+
+   Implements in-place ``TOS = TOS1 // TOS``.
+
+
+.. opcode:: INPLACE_TRUE_DIVIDE ()
+
+   Implements in-place ``TOS = TOS1 / TOS`` when ``from __future__ import
+   division`` is in effect.
+
+
+.. opcode:: INPLACE_MODULO ()
+
+   Implements in-place ``TOS = TOS1 % TOS``.
+
+
+.. opcode:: INPLACE_ADD ()
+
+   Implements in-place ``TOS = TOS1 + TOS``.
+
+
+.. opcode:: INPLACE_SUBTRACT ()
+
+   Implements in-place ``TOS = TOS1 - TOS``.
+
+
+.. opcode:: INPLACE_LSHIFT ()
+
+   Implements in-place ``TOS = TOS1 << TOS``.
+
+
+.. opcode:: INPLACE_RSHIFT ()
+
+   Implements in-place ``TOS = TOS1 >> TOS``.
+
+
+.. opcode:: INPLACE_AND ()
+
+   Implements in-place ``TOS = TOS1 & TOS``.
+
+
+.. opcode:: INPLACE_XOR ()
+
+   Implements in-place ``TOS = TOS1 ^ TOS``.
+
+
+.. opcode:: INPLACE_OR ()
+
+   Implements in-place ``TOS = TOS1 | TOS``.
+
+The slice opcodes take up to three parameters.
+
+
+.. opcode:: SLICE+0 ()
+
+   Implements ``TOS = TOS[:]``.
+
+
+.. opcode:: SLICE+1 ()
+
+   Implements ``TOS = TOS1[TOS:]``.
+
+
+.. opcode:: SLICE+2 ()
+
+   Implements ``TOS = TOS1[:TOS]``.
+
+
+.. opcode:: SLICE+3 ()
+
+   Implements ``TOS = TOS2[TOS1:TOS]``.
+
+Slice assignment needs even an additional parameter.  As any statement, they put
+nothing on the stack.
+
+
+.. opcode:: STORE_SLICE+0 ()
+
+   Implements ``TOS[:] = TOS1``.
+
+
+.. opcode:: STORE_SLICE+1 ()
+
+   Implements ``TOS1[TOS:] = TOS2``.
+
+
+.. opcode:: STORE_SLICE+2 ()
+
+   Implements ``TOS1[:TOS] = TOS2``.
+
+
+.. opcode:: STORE_SLICE+3 ()
+
+   Implements ``TOS2[TOS1:TOS] = TOS3``.
+
+
+.. opcode:: DELETE_SLICE+0 ()
+
+   Implements ``del TOS[:]``.
+
+
+.. opcode:: DELETE_SLICE+1 ()
+
+   Implements ``del TOS1[TOS:]``.
+
+
+.. opcode:: DELETE_SLICE+2 ()
+
+   Implements ``del TOS1[:TOS]``.
+
+
+.. opcode:: DELETE_SLICE+3 ()
+
+   Implements ``del TOS2[TOS1:TOS]``.
+
+
+.. opcode:: STORE_SUBSCR ()
+
+   Implements ``TOS1[TOS] = TOS2``.
+
+
+.. opcode:: DELETE_SUBSCR ()
+
+   Implements ``del TOS1[TOS]``.
+
+Miscellaneous opcodes.
+
+
+.. opcode:: PRINT_EXPR ()
+
+   Implements the expression statement for the interactive mode.  TOS is removed
+   from the stack and printed.  In non-interactive mode, an expression statement is
+   terminated with ``POP_STACK``.
+
+
+.. opcode:: BREAK_LOOP ()
+
+   Terminates a loop due to a :keyword:`break` statement.
+
+
+.. opcode:: CONTINUE_LOOP (target)
+
+   Continues a loop due to a :keyword:`continue` statement.  *target* is the
+   address to jump to (which should be a ``FOR_ITER`` instruction).
+
+
+.. opcode:: SET_ADD ()
+
+   Calls ``set.add(TOS1, TOS)``.  Used to implement set comprehensions.
+
+
+.. opcode:: LIST_APPEND ()
+
+   Calls ``list.append(TOS1, TOS)``.  Used to implement list comprehensions.
+
+
+.. opcode:: LOAD_LOCALS ()
+
+   Pushes a reference to the locals of the current scope on the stack. This is used
+   in the code for a class definition: After the class body is evaluated, the
+   locals are passed to the class definition.
+
+
+.. opcode:: RETURN_VALUE ()
+
+   Returns with TOS to the caller of the function.
+
+
+.. opcode:: YIELD_VALUE ()
+
+   Pops ``TOS`` and yields it from a generator.
+
+
+.. opcode:: IMPORT_STAR ()
+
+   Loads all symbols not starting with ``'_'`` directly from the module TOS to the
+   local namespace. The module is popped after loading all names. This opcode
+   implements ``from module import *``.
+
+
+.. opcode:: POP_BLOCK ()
+
+   Removes one block from the block stack.  Per frame, there is a  stack of blocks,
+   denoting nested loops, try statements, and such.
+
+
+.. opcode:: END_FINALLY ()
+
+   Terminates a :keyword:`finally` clause.  The interpreter recalls whether the
+   exception has to be re-raised, or whether the function returns, and continues
+   with the outer-next block.
+
+
+.. opcode:: BUILD_CLASS ()
+
+   Creates a new class object.  TOS is the methods dictionary, TOS1 the tuple of
+   the names of the base classes, and TOS2 the class name.
+
+All of the following opcodes expect arguments.  An argument is two bytes, with
+the more significant byte last.
+
+
+.. opcode:: STORE_NAME (namei)
+
+   Implements ``name = TOS``. *namei* is the index of *name* in the attribute
+   :attr:`co_names` of the code object. The compiler tries to use ``STORE_LOCAL``
+   or ``STORE_GLOBAL`` if possible.
+
+
+.. opcode:: DELETE_NAME (namei)
+
+   Implements ``del name``, where *namei* is the index into :attr:`co_names`
+   attribute of the code object.
+
+
+.. opcode:: UNPACK_SEQUENCE (count)
+
+   Unpacks TOS into *count* individual values, which are put onto the stack
+   right-to-left.
+
+.. % \begin{opcodedesc}{UNPACK_LIST}{count}
+.. % This opcode is obsolete.
+.. % \end{opcodedesc}
+.. % \begin{opcodedesc}{UNPACK_ARG}{count}
+.. % This opcode is obsolete.
+.. % \end{opcodedesc}
+
+
+.. opcode:: DUP_TOPX (count)
+
+   Duplicate *count* items, keeping them in the same order. Due to implementation
+   limits, *count* should be between 1 and 5 inclusive.
+
+
+.. opcode:: STORE_ATTR (namei)
+
+   Implements ``TOS.name = TOS1``, where *namei* is the index of name in
+   :attr:`co_names`.
+
+
+.. opcode:: DELETE_ATTR (namei)
+
+   Implements ``del TOS.name``, using *namei* as index into :attr:`co_names`.
+
+
+.. opcode:: STORE_GLOBAL (namei)
+
+   Works as ``STORE_NAME``, but stores the name as a global.
+
+
+.. opcode:: DELETE_GLOBAL (namei)
+
+   Works as ``DELETE_NAME``, but deletes a global name.
+
+.. % \begin{opcodedesc}{UNPACK_VARARG}{argc}
+.. % This opcode is obsolete.
+.. % \end{opcodedesc}
+
+
+.. opcode:: LOAD_CONST (consti)
+
+   Pushes ``co_consts[consti]`` onto the stack.
+
+
+.. opcode:: LOAD_NAME (namei)
+
+   Pushes the value associated with ``co_names[namei]`` onto the stack.
+
+
+.. opcode:: BUILD_TUPLE (count)
+
+   Creates a tuple consuming *count* items from the stack, and pushes the resulting
+   tuple onto the stack.
+
+
+.. opcode:: BUILD_LIST (count)
+
+   Works as ``BUILD_TUPLE``, but creates a list.
+
+
+.. opcode:: BUILD_SET (count)
+
+   Works as ``BUILD_TUPLE``, but creates a set.
+
+
+.. opcode:: BUILD_MAP (zero)
+
+   Pushes a new empty dictionary object onto the stack.  The argument is ignored
+   and set to zero by the compiler.
+
+
+.. opcode:: LOAD_ATTR (namei)
+
+   Replaces TOS with ``getattr(TOS, co_names[namei])``.
+
+
+.. opcode:: COMPARE_OP (opname)
+
+   Performs a Boolean operation.  The operation name can be found in
+   ``cmp_op[opname]``.
+
+
+.. opcode:: IMPORT_NAME (namei)
+
+   Imports the module ``co_names[namei]``.  The module object is pushed onto the
+   stack.  The current namespace is not affected: for a proper import statement, a
+   subsequent ``STORE_FAST`` instruction modifies the namespace.
+
+
+.. opcode:: IMPORT_FROM (namei)
+
+   Loads the attribute ``co_names[namei]`` from the module found in TOS. The
+   resulting object is pushed onto the stack, to be subsequently stored by a
+   ``STORE_FAST`` instruction.
+
+
+.. opcode:: JUMP_FORWARD (delta)
+
+   Increments byte code counter by *delta*.
+
+
+.. opcode:: JUMP_IF_TRUE (delta)
+
+   If TOS is true, increment the byte code counter by *delta*.  TOS is left on the
+   stack.
+
+
+.. opcode:: JUMP_IF_FALSE (delta)
+
+   If TOS is false, increment the byte code counter by *delta*.  TOS is not
+   changed.
+
+
+.. opcode:: JUMP_ABSOLUTE (target)
+
+   Set byte code counter to *target*.
+
+
+.. opcode:: FOR_ITER (delta)
+
+   ``TOS`` is an iterator.  Call its :meth:`__next__` method.  If this yields a new
+   value, push it on the stack (leaving the iterator below it).  If the iterator
+   indicates it is exhausted ``TOS`` is popped, and the byte code counter is
+   incremented by *delta*.
+
+.. % \begin{opcodedesc}{FOR_LOOP}{delta}
+.. % This opcode is obsolete.
+.. % \end{opcodedesc}
+.. % \begin{opcodedesc}{LOAD_LOCAL}{namei}
+.. % This opcode is obsolete.
+.. % \end{opcodedesc}
+
+
+.. opcode:: LOAD_GLOBAL (namei)
+
+   Loads the global named ``co_names[namei]`` onto the stack.
+
+.. % \begin{opcodedesc}{SET_FUNC_ARGS}{argc}
+.. % This opcode is obsolete.
+.. % \end{opcodedesc}
+
+
+.. opcode:: SETUP_LOOP (delta)
+
+   Pushes a block for a loop onto the block stack.  The block spans from the
+   current instruction with a size of *delta* bytes.
+
+
+.. opcode:: SETUP_EXCEPT (delta)
+
+   Pushes a try block from a try-except clause onto the block stack. *delta* points
+   to the first except block.
+
+
+.. opcode:: SETUP_FINALLY (delta)
+
+   Pushes a try block from a try-except clause onto the block stack. *delta* points
+   to the finally block.
+
+
+.. opcode:: LOAD_FAST (var_num)
+
+   Pushes a reference to the local ``co_varnames[var_num]`` onto the stack.
+
+
+.. opcode:: STORE_FAST (var_num)
+
+   Stores TOS into the local ``co_varnames[var_num]``.
+
+
+.. opcode:: DELETE_FAST (var_num)
+
+   Deletes local ``co_varnames[var_num]``.
+
+
+.. opcode:: LOAD_CLOSURE (i)
+
+   Pushes a reference to the cell contained in slot *i* of the cell and free
+   variable storage.  The name of the variable is  ``co_cellvars[i]`` if *i* is
+   less than the length of *co_cellvars*.  Otherwise it is  ``co_freevars[i -
+   len(co_cellvars)]``.
+
+
+.. opcode:: LOAD_DEREF (i)
+
+   Loads the cell contained in slot *i* of the cell and free variable storage.
+   Pushes a reference to the object the cell contains on the stack.
+
+
+.. opcode:: STORE_DEREF (i)
+
+   Stores TOS into the cell contained in slot *i* of the cell and free variable
+   storage.
+
+
+.. opcode:: SET_LINENO (lineno)
+
+   This opcode is obsolete.
+
+
+.. opcode:: RAISE_VARARGS (argc)
+
+   Raises an exception. *argc* indicates the number of parameters to the raise
+   statement, ranging from 0 to 3.  The handler will find the traceback as TOS2,
+   the parameter as TOS1, and the exception as TOS.
+
+
+.. opcode:: CALL_FUNCTION (argc)
+
+   Calls a function.  The low byte of *argc* indicates the number of positional
+   parameters, the high byte the number of keyword parameters. On the stack, the
+   opcode finds the keyword parameters first.  For each keyword argument, the value
+   is on top of the key.  Below the keyword parameters, the positional parameters
+   are on the stack, with the right-most parameter on top.  Below the parameters,
+   the function object to call is on the stack.
+
+
+.. opcode:: MAKE_FUNCTION (argc)
+
+   Pushes a new function object on the stack.  TOS is the code associated with the
+   function.  The function object is defined to have *argc* default parameters,
+   which are found below TOS.
+
+
+.. opcode:: MAKE_CLOSURE (argc)
+
+   Creates a new function object, sets its *__closure__* slot, and pushes it on the
+   stack.  TOS is the code associated with the function. If the code object has N
+   free variables, the next N items on the stack are the cells for these variables.
+   The function also has *argc* default parameters, where are found before the
+   cells.
+
+
+.. opcode:: BUILD_SLICE (argc)
+
+   .. index:: builtin: slice
+
+   Pushes a slice object on the stack.  *argc* must be 2 or 3.  If it is 2,
+   ``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is
+   pushed. See the ``slice()`` built-in function for more information.
+
+
+.. opcode:: EXTENDED_ARG (ext)
+
+   Prefixes any opcode which has an argument too big to fit into the default two
+   bytes.  *ext* holds two additional bytes which, taken together with the
+   subsequent opcode's argument, comprise a four-byte argument, *ext* being the two
+   most-significant bytes.
+
+
+.. opcode:: CALL_FUNCTION_VAR (argc)
+
+   Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element
+   on the stack contains the variable argument list, followed by keyword and
+   positional arguments.
+
+
+.. opcode:: CALL_FUNCTION_KW (argc)
+
+   Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element
+   on the stack contains the keyword arguments dictionary,  followed by explicit
+   keyword and positional arguments.
+
+
+.. opcode:: CALL_FUNCTION_VAR_KW (argc)
+
+   Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``.  The top
+   element on the stack contains the keyword arguments dictionary, followed by the
+   variable-arguments tuple, followed by explicit keyword and positional arguments.
+
+
+.. opcode:: HAVE_ARGUMENT ()
+
+   This is not really an opcode.  It identifies the dividing line between opcodes
+   which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>=
+   HAVE_ARGUMENT``.
+

Doc/library/distutils.rst

@@ -0,0 +1,30 @@
+
+:mod:`distutils` --- Building and installing Python modules
+===========================================================
+
+.. module:: distutils
+   :synopsis: Support for building and installing Python modules into an existing Python
+              installation.
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+The :mod:`distutils` package provides support for building and installing
+additional modules into a Python installation.  The new modules may be either
+100%-pure Python, or may be extension modules written in C, or may be
+collections of Python packages which include modules coded in both Python and C.
+
+This package is discussed in two separate chapters:
+
+
+.. seealso::
+
+   :ref:`distutils-index`
+      The manual for developers and packagers of Python modules.  This describes how
+      to prepare :mod:`distutils`\ -based packages so that they may be easily
+      installed into an existing Python installation.
+
+   :ref:`install-index`
+      An "administrators" manual which includes information on installing modules into
+      an existing Python installation. You do not need to be a Python programmer to
+      read this manual.
+

Doc/library/dl.rst

@@ -0,0 +1,111 @@
+
+:mod:`dl` --- Call C functions in shared objects
+================================================
+
+.. module:: dl
+   :platform: Unix
+   :synopsis: Call C functions in shared objects.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+.. % ?????????? Anyone????????????
+
+The :mod:`dl` module defines an interface to the :cfunc:`dlopen` function, which
+is the most common interface on Unix platforms for handling dynamically linked
+libraries. It allows the program to call arbitrary functions in such a library.
+
+.. warning::
+
+   The :mod:`dl` module bypasses the Python type system and  error handling. If
+   used incorrectly it may cause segmentation faults, crashes or other incorrect
+   behaviour.
+
+.. note::
+
+   This module will not work unless ``sizeof(int) == sizeof(long) == sizeof(char
+   *)`` If this is not the case, :exc:`SystemError` will be raised on import.
+
+The :mod:`dl` module defines the following function:
+
+
+.. function:: open(name[, mode=RTLD_LAZY])
+
+   Open a shared object file, and return a handle. Mode signifies late binding
+   (:const:`RTLD_LAZY`) or immediate binding (:const:`RTLD_NOW`). Default is
+   :const:`RTLD_LAZY`. Note that some systems do not support :const:`RTLD_NOW`.
+
+   Return value is a :class:`dlobject`.
+
+The :mod:`dl` module defines the following constants:
+
+
+.. data:: RTLD_LAZY
+
+   Useful as an argument to :func:`open`.
+
+
+.. data:: RTLD_NOW
+
+   Useful as an argument to :func:`open`.  Note that on systems which do not
+   support immediate binding, this constant will not appear in the module. For
+   maximum portability, use :func:`hasattr` to determine if the system supports
+   immediate binding.
+
+The :mod:`dl` module defines the following exception:
+
+
+.. exception:: error
+
+   Exception raised when an error has occurred inside the dynamic loading and
+   linking routines.
+
+Example::
+
+   >>> import dl, time
+   >>> a=dl.open('/lib/libc.so.6')
+   >>> a.call('time'), time.time()
+   (929723914, 929723914.498)
+
+This example was tried on a Debian GNU/Linux system, and is a good example of
+the fact that using this module is usually a bad alternative.
+
+
+.. _dl-objects:
+
+Dl Objects
+----------
+
+Dl objects, as returned by :func:`open` above, have the following methods:
+
+
+.. method:: dl.close()
+
+   Free all resources, except the memory.
+
+
+.. method:: dl.sym(name)
+
+   Return the pointer for the function named *name*, as a number, if it exists in
+   the referenced shared object, otherwise ``None``. This is useful in code like::
+
+      >>> if a.sym('time'): 
+      ...     a.call('time')
+      ... else: 
+      ...     time.time()
+
+   (Note that this function will return a non-zero number, as zero is the *NULL*
+   pointer)
+
+
+.. method:: dl.call(name[, arg1[, arg2...]])
+
+   Call the function named *name* in the referenced shared object. The arguments
+   must be either Python integers, which will be  passed as is, Python strings, to
+   which a pointer will be passed,  or ``None``, which will be passed as *NULL*.
+   Note that  strings should only be passed to functions as :ctype:`const char\*`,
+   as Python will not like its string mutated.
+
+   There must be at most 10 arguments, and arguments not given will be treated as
+   ``None``. The function's return value must be a C :ctype:`long`, which is a
+   Python integer.
+

Doc/library/docxmlrpcserver.rst

@@ -0,0 +1,97 @@
+
+:mod:`DocXMLRPCServer` --- Self-documenting XML-RPC server
+==========================================================
+
+.. module:: DocXMLRPCServer
+   :synopsis: Self-documenting XML-RPC server implementation.
+.. moduleauthor:: Brian Quinlan <brianq@activestate.com>
+.. sectionauthor:: Brian Quinlan <brianq@activestate.com>
+
+
+.. versionadded:: 2.3
+
+The :mod:`DocXMLRPCServer` module extends the classes found in
+:mod:`SimpleXMLRPCServer` to serve HTML documentation in response to HTTP GET
+requests. Servers can either be free standing, using :class:`DocXMLRPCServer`,
+or embedded in a CGI environment, using :class:`DocCGIXMLRPCRequestHandler`.
+
+
+.. class:: DocXMLRPCServer(addr[, requestHandler[, logRequests[, allow_none[,  encoding[, bind_and_activate]]]]])
+
+   Create a new server instance. All parameters have the same meaning as for
+   :class:`SimpleXMLRPCServer.SimpleXMLRPCServer`; *requestHandler* defaults to
+   :class:`DocXMLRPCRequestHandler`.
+
+
+.. class:: DocCGIXMLRPCRequestHandler()
+
+   Create a new instance to handle XML-RPC requests in a CGI environment.
+
+
+.. class:: DocXMLRPCRequestHandler()
+
+   Create a new request handler instance. This request handler supports XML-RPC
+   POST requests, documentation GET requests, and modifies logging so that the
+   *logRequests* parameter to the :class:`DocXMLRPCServer` constructor parameter is
+   honored.
+
+
+.. _doc-xmlrpc-servers:
+
+DocXMLRPCServer Objects
+-----------------------
+
+The :class:`DocXMLRPCServer` class is derived from
+:class:`SimpleXMLRPCServer.SimpleXMLRPCServer` and provides a means of creating
+self-documenting, stand alone XML-RPC servers. HTTP POST requests are handled as
+XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style
+HTML documentation. This allows a server to provide its own web-based
+documentation.
+
+
+.. method:: DocXMLRPCServer.set_server_title(server_title)
+
+   Set the title used in the generated HTML documentation. This title will be used
+   inside the HTML "title" element.
+
+
+.. method:: DocXMLRPCServer.set_server_name(server_name)
+
+   Set the name used in the generated HTML documentation. This name will appear at
+   the top of the generated documentation inside a "h1" element.
+
+
+.. method:: DocXMLRPCServer.set_server_documentation(server_documentation)
+
+   Set the description used in the generated HTML documentation. This description
+   will appear as a paragraph, below the server name, in the documentation.
+
+
+DocCGIXMLRPCRequestHandler
+--------------------------
+
+The :class:`DocCGIXMLRPCRequestHandler` class is derived from
+:class:`SimpleXMLRPCServer.CGIXMLRPCRequestHandler` and provides a means of
+creating self-documenting, XML-RPC CGI scripts. HTTP POST requests are handled
+as XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style
+HTML documentation. This allows a server to provide its own web-based
+documentation.
+
+
+.. method:: DocCGIXMLRPCRequestHandler.set_server_title(server_title)
+
+   Set the title used in the generated HTML documentation. This title will be used
+   inside the HTML "title" element.
+
+
+.. method:: DocCGIXMLRPCRequestHandler.set_server_name(server_name)
+
+   Set the name used in the generated HTML documentation. This name will appear at
+   the top of the generated documentation inside a "h1" element.
+
+
+.. method:: DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)
+
+   Set the description used in the generated HTML documentation. This description
+   will appear as a paragraph, below the server name, in the documentation.
+

Doc/library/dumbdbm.rst

@@ -0,0 +1,81 @@
+
+:mod:`dumbdbm` --- Portable DBM implementation
+==============================================
+
+.. module:: dumbdbm
+   :synopsis: Portable implementation of the simple DBM interface.
+
+
+.. index:: single: databases
+
+.. note::
+
+   The :mod:`dumbdbm` module is intended as a last resort fallback for the
+   :mod:`anydbm` module when no more robust module is available. The :mod:`dumbdbm`
+   module is not written for speed and is not nearly as heavily used as the other
+   database modules.
+
+The :mod:`dumbdbm` module provides a persistent dictionary-like interface which
+is written entirely in Python.  Unlike other modules such as :mod:`gdbm` and
+:mod:`bsddb`, no external library is required.  As with other persistent
+mappings, the keys and values must always be strings.
+
+The module defines the following:
+
+
+.. exception:: error
+
+   Raised on dumbdbm-specific errors, such as I/O errors.  :exc:`KeyError` is
+   raised for general mapping errors like specifying an incorrect key.
+
+
+.. function:: open(filename[, flag[, mode]])
+
+   Open a dumbdbm database and return a dumbdbm object.  The *filename* argument is
+   the basename of the database file (without any specific extensions).  When a
+   dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions
+   are created.
+
+   The optional *flag* argument is currently ignored; the database is always opened
+   for update, and will be created if it does not exist.
+
+   The optional *mode* argument is the Unix mode of the file, used only when the
+   database has to be created.  It defaults to octal ``0666`` (and will be modified
+   by the prevailing umask).
+
+   .. versionchanged:: 2.2
+      The *mode* argument was ignored in earlier versions.
+
+
+.. seealso::
+
+   Module :mod:`anydbm`
+      Generic interface to ``dbm``\ -style databases.
+
+   Module :mod:`dbm`
+      Similar interface to the DBM/NDBM library.
+
+   Module :mod:`gdbm`
+      Similar interface to the GNU GDBM library.
+
+   Module :mod:`shelve`
+      Persistence module which stores non-string data.
+
+   Module :mod:`whichdb`
+      Utility module used to determine the type of an existing database.
+
+
+.. _dumbdbm-objects:
+
+Dumbdbm Objects
+---------------
+
+In addition to the methods provided by the :class:`UserDict.DictMixin` class,
+:class:`dumbdbm` objects provide the following methods.
+
+
+.. method:: dumbdbm.sync()
+
+   Synchronize the on-disk directory and data files.  This method is called by the
+   :meth:`sync` method of :class:`Shelve` objects.
+

Doc/library/dummy_thread.rst

@@ -0,0 +1,23 @@
+
+:mod:`dummy_thread` --- Drop-in replacement for the :mod:`thread` module
+========================================================================
+
+.. module:: dummy_thread
+   :synopsis: Drop-in replacement for the thread module.
+
+
+This module provides a duplicate interface to the :mod:`thread` module.  It is
+meant to be imported when the :mod:`thread` module is not provided on a
+platform.
+
+Suggested usage is::
+
+   try:
+       import thread as _thread
+   except ImportError:
+       import dummy_thread as _thread
+
+Be careful to not use this module where deadlock might occur from a thread
+being created that blocks waiting for another thread to be created.  This  often
+occurs with blocking I/O.
+

Doc/library/dummy_threading.rst

@@ -0,0 +1,23 @@
+
+:mod:`dummy_threading` --- Drop-in replacement for the :mod:`threading` module
+==============================================================================
+
+.. module:: dummy_threading
+   :synopsis: Drop-in replacement for the threading module.
+
+
+This module provides a duplicate interface to the :mod:`threading` module.  It
+is meant to be imported when the :mod:`thread` module is not provided on a
+platform.
+
+Suggested usage is::
+
+   try:
+       import threading as _threading
+   except ImportError:
+       import dummy_threading as _threading
+
+Be careful to not use this module where deadlock might occur from a thread
+being created that blocks waiting for another thread to be created.  This  often
+occurs with blocking I/O.
+

Doc/library/easydialogs.rst

@@ -0,0 +1,207 @@
+
+:mod:`EasyDialogs` --- Basic Macintosh dialogs
+==============================================
+
+.. module:: EasyDialogs
+   :platform: Mac
+   :synopsis: Basic Macintosh dialogs.
+
+
+The :mod:`EasyDialogs` module contains some simple dialogs for the Macintosh.
+All routines take an optional resource ID parameter *id* with which one can
+override the :const:`DLOG` resource used for the dialog, provided that the
+dialog items correspond (both type and item number) to those in the default
+:const:`DLOG` resource. See source code for details.
+
+The :mod:`EasyDialogs` module defines the following functions:
+
+
+.. function:: Message(str[, id[, ok]])
+
+   Displays a modal dialog with the message text *str*, which should be at most 255
+   characters long. The button text defaults to "OK", but is set to the string
+   argument *ok* if the latter is supplied. Control is returned when the user
+   clicks the "OK" button.
+
+
+.. function:: AskString(prompt[, default[, id[, ok[, cancel]]]])
+
+   Asks the user to input a string value via a modal dialog. *prompt* is the prompt
+   message, and the optional *default* supplies the initial value for the string
+   (otherwise ``""`` is used). The text of the "OK" and "Cancel" buttons can be
+   changed with the *ok* and *cancel* arguments. All strings can be at most 255
+   bytes long. :func:`AskString` returns the string entered or :const:`None` in
+   case the user cancelled.
+
+
+.. function:: AskPassword(prompt[, default[, id[, ok[, cancel]]]])
+
+   Asks the user to input a string value via a modal dialog. Like
+   :func:`AskString`, but with the text shown as bullets. The arguments have the
+   same meaning as for :func:`AskString`.
+
+
+.. function:: AskYesNoCancel(question[, default[, yes[, no[, cancel[, id]]]]])
+
+   Presents a dialog with prompt *question* and three buttons labelled "Yes", "No",
+   and "Cancel". Returns ``1`` for "Yes", ``0`` for "No" and ``-1`` for "Cancel".
+   The value of *default* (or ``0`` if *default* is not supplied) is returned when
+   the :kbd:`RETURN` key is pressed. The text of the buttons can be changed with
+   the *yes*, *no*, and *cancel* arguments; to prevent a button from appearing,
+   supply ``""`` for the corresponding argument.
+
+
+.. function:: ProgressBar([title[, maxval[, label[, id]]]])
+
+   Displays a modeless progress-bar dialog. This is the constructor for the
+   :class:`ProgressBar` class described below. *title* is the text string displayed
+   (default "Working..."), *maxval* is the value at which progress is complete
+   (default ``0``, indicating that an indeterminate amount of work remains to be
+   done), and *label* is the text that is displayed above the progress bar itself.
+
+
+.. function:: GetArgv([optionlist[ commandlist[, addoldfile[, addnewfile[, addfolder[, id]]]]]])
+
+   Displays a dialog which aids the user in constructing a command-line argument
+   list.  Returns the list in ``sys.argv`` format, suitable for passing as an
+   argument to :func:`getopt.getopt`.  *addoldfile*, *addnewfile*, and *addfolder*
+   are boolean arguments.  When nonzero, they enable the user to insert into the
+   command line paths to an existing file, a (possibly) not-yet-existent file, and
+   a folder, respectively.  (Note: Option arguments must appear in the command line
+   before file and folder arguments in order to be recognized by
+   :func:`getopt.getopt`.)  Arguments containing spaces can be specified by
+   enclosing them within single or double quotes.  A :exc:`SystemExit` exception is
+   raised if the user presses the "Cancel" button.
+
+   *optionlist* is a list that determines a popup menu from which the allowed
+   options are selected.  Its items can take one of two forms: *optstr* or
+   ``(optstr, descr)``.  When present, *descr* is a short descriptive string that
+   is displayed in the dialog while this option is selected in the popup menu.  The
+   correspondence between *optstr*\s and command-line arguments is:
+
+   +----------------------+------------------------------------------+
+   | *optstr* format      | Command-line format                      |
+   +======================+==========================================+
+   | ``x``                | :option:`-x` (short option)              |
+   +----------------------+------------------------------------------+
+   | ``x:`` or ``x=``     | :option:`-x` (short option with value)   |
+   +----------------------+------------------------------------------+
+   | ``xyz``              | :option:`--xyz` (long option)            |
+   +----------------------+------------------------------------------+
+   | ``xyz:`` or ``xyz=`` | :option:`--xyz` (long option with value) |
+   +----------------------+------------------------------------------+
+
+   *commandlist* is a list of items of the form *cmdstr* or ``(cmdstr, descr)``,
+   where *descr* is as above.  The *cmdstr*s will appear in a popup menu.  When
+   chosen, the text of *cmdstr* will be appended to the command line as is, except
+   that a trailing ``':'`` or ``'='`` (if present) will be trimmed off.
+
+   .. versionadded:: 2.0
+
+
+.. function:: AskFileForOpen( [message] [, typeList] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, previewProc] [, filterProc] [, wanted] )
+
+   Post a dialog asking the user for a file to open, and return the file selected
+   or :const:`None` if the user cancelled. *message* is a text message to display,
+   *typeList* is a list of 4-char filetypes allowable, *defaultLocation* is the
+   pathname, :class:`FSSpec` or :class:`FSRef` of the folder to show initially,
+   *location* is the ``(x, y)`` position on the screen where the dialog is shown,
+   *actionButtonLabel* is a string to show instead of "Open" in the OK button,
+   *cancelButtonLabel* is a string to show instead of "Cancel" in the cancel
+   button, *wanted* is the type of value wanted as a return: :class:`str`,
+   :class:`unicode`, :class:`FSSpec`, :class:`FSRef` and subtypes thereof are
+   acceptable.
+
+   .. index:: single: Navigation Services
+
+   For a description of the other arguments please see the Apple Navigation
+   Services documentation and the :mod:`EasyDialogs` source code.
+
+
+.. function:: AskFileForSave( [message] [, savedFileName] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, fileType] [, fileCreator] [, eventProc] [, wanted] )
+
+   Post a dialog asking the user for a file to save to, and return the file
+   selected or :const:`None` if the user cancelled. *savedFileName* is the default
+   for the file name to save to (the return value). See :func:`AskFileForOpen` for
+   a description of the other arguments.
+
+
+.. function:: AskFolder( [message] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, filterProc] [, wanted] )
+
+   Post a dialog asking the user to select a folder, and return the folder selected
+   or :const:`None` if the user cancelled. See :func:`AskFileForOpen` for a
+   description of the arguments.
+
+
+.. seealso::
+
+   `Navigation Services Reference <http://developer.apple.com/documentation/Carbon/Reference/Navigation_Services_Ref/>`_
+      Programmer's reference documentation for the Navigation Services, a part of the
+      Carbon framework.
+
+
+.. _progressbar-objects:
+
+ProgressBar Objects
+-------------------
+
+:class:`ProgressBar` objects provide support for modeless progress-bar dialogs.
+Both determinate (thermometer style) and indeterminate (barber-pole style)
+progress bars are supported.  The bar will be determinate if its maximum value
+is greater than zero; otherwise it will be indeterminate.
+
+.. versionchanged:: 2.2
+   Support for indeterminate-style progress bars was added.
+
+The dialog is displayed immediately after creation. If the dialog's "Cancel"
+button is pressed, or if :kbd:`Cmd-.` or :kbd:`ESC` is typed, the dialog window
+is hidden and :exc:`KeyboardInterrupt` is raised (but note that this response
+does not occur until the progress bar is next updated, typically via a call to
+:meth:`inc` or :meth:`set`).  Otherwise, the bar remains visible until the
+:class:`ProgressBar` object is discarded.
+
+:class:`ProgressBar` objects possess the following attributes and methods:
+
+
+.. attribute:: ProgressBar.curval
+
+   The current value (of type integer or long integer) of the progress bar.  The
+   normal access methods coerce :attr:`curval` between ``0`` and :attr:`maxval`.
+   This attribute should not be altered directly.
+
+
+.. attribute:: ProgressBar.maxval
+
+   The maximum value (of type integer or long integer) of the progress bar; the
+   progress bar (thermometer style) is full when :attr:`curval` equals
+   :attr:`maxval`.  If :attr:`maxval` is ``0``, the bar will be indeterminate
+   (barber-pole).  This attribute should not be altered directly.
+
+
+.. method:: ProgressBar.title([newstr])
+
+   Sets the text in the title bar of the progress dialog to *newstr*.
+
+
+.. method:: ProgressBar.label([newstr])
+
+   Sets the text in the progress box of the progress dialog to *newstr*.
+
+
+.. method:: ProgressBar.set(value[, max])
+
+   Sets the progress bar's :attr:`curval` to *value*, and also :attr:`maxval` to
+   *max* if the latter is provided.  *value* is first coerced between 0 and
+   :attr:`maxval`.  The thermometer bar is updated to reflect the changes,
+   including a change from indeterminate to determinate or vice versa.
+
+
+.. method:: ProgressBar.inc([n])
+
+   Increments the progress bar's :attr:`curval` by *n*, or by ``1`` if *n* is not
+   provided.  (Note that *n* may be negative, in which case the effect is a
+   decrement.)  The progress bar is updated to reflect the change.  If the bar is
+   indeterminate, this causes one "spin" of the barber pole.  The resulting
+   :attr:`curval` is coerced between 0 and :attr:`maxval` if incrementing causes it
+   to fall outside this range.
+

Doc/library/email-examples.rst

@@ -0,0 +1,33 @@
+:mod:`email`: Examples
+----------------------
+
+Here are a few examples of how to use the :mod:`email` package to read, write,
+and send simple email messages, as well as more complex MIME messages.
+
+First, let's see how to create and send a simple text message:
+
+.. literalinclude:: ../includes/email-simple.py
+
+
+Here's an example of how to send a MIME message containing a bunch of family
+pictures that may be residing in a directory:
+
+.. literalinclude:: ../includes/email-mime.py
+
+
+Here's an example of how to send the entire contents of a directory as an email
+message:  [1]_
+
+.. literalinclude:: ../includes/email-dir.py
+
+
+And finally, here's an example of how to unpack a MIME message like the one
+above, into a directory of files:
+
+.. literalinclude:: ../includes/email-unpack.py
+
+
+.. rubric:: Footnotes
+
+.. [1] Thanks to Matthew Dixon Cowles for the original inspiration and examples.
+

Doc/library/email.charset.rst

@@ -0,0 +1,249 @@
+:mod:`email`: Representing character sets
+-----------------------------------------
+
+.. module:: email.charset
+   :synopsis: Character Sets
+
+
+This module provides a class :class:`Charset` for representing character sets
+and character set conversions in email messages, as well as a character set
+registry and several convenience methods for manipulating this registry.
+Instances of :class:`Charset` are used in several other modules within the
+:mod:`email` package.
+
+Import this class from the :mod:`email.charset` module.
+
+.. versionadded:: 2.2.2
+
+
+.. class:: Charset([input_charset])
+
+   Map character sets to their email properties.
+
+   This class provides information about the requirements imposed on email for a
+   specific character set.  It also provides convenience routines for converting
+   between character sets, given the availability of the applicable codecs.  Given
+   a character set, it will do its best to provide information on how to use that
+   character set in an email message in an RFC-compliant way.
+
+   Certain character sets must be encoded with quoted-printable or base64 when used
+   in email headers or bodies.  Certain character sets must be converted outright,
+   and are not allowed in email.
+
+   Optional *input_charset* is as described below; it is always coerced to lower
+   case.  After being alias normalized it is also used as a lookup into the
+   registry of character sets to find out the header encoding, body encoding, and
+   output conversion codec to be used for the character set.  For example, if
+   *input_charset* is ``iso-8859-1``, then headers and bodies will be encoded using
+   quoted-printable and no output conversion codec is necessary.  If
+   *input_charset* is ``euc-jp``, then headers will be encoded with base64, bodies
+   will not be encoded, but output text will be converted from the ``euc-jp``
+   character set to the ``iso-2022-jp`` character set.
+
+:class:`Charset` instances have the following data attributes:
+
+
+.. data:: input_charset
+
+   The initial character set specified.  Common aliases are converted to their
+   *official* email names (e.g. ``latin_1`` is converted to ``iso-8859-1``).
+   Defaults to 7-bit ``us-ascii``.
+
+
+.. data:: header_encoding
+
+   If the character set must be encoded before it can be used in an email header,
+   this attribute will be set to ``Charset.QP`` (for quoted-printable),
+   ``Charset.BASE64`` (for base64 encoding), or ``Charset.SHORTEST`` for the
+   shortest of QP or BASE64 encoding. Otherwise, it will be ``None``.
+
+
+.. data:: body_encoding
+
+   Same as *header_encoding*, but describes the encoding for the mail message's
+   body, which indeed may be different than the header encoding.
+   ``Charset.SHORTEST`` is not allowed for *body_encoding*.
+
+
+.. data:: output_charset
+
+   Some character sets must be converted before they can be used in email headers
+   or bodies.  If the *input_charset* is one of them, this attribute will contain
+   the name of the character set output will be converted to.  Otherwise, it will
+   be ``None``.
+
+
+.. data:: input_codec
+
+   The name of the Python codec used to convert the *input_charset* to Unicode.  If
+   no conversion codec is necessary, this attribute will be ``None``.
+
+
+.. data:: output_codec
+
+   The name of the Python codec used to convert Unicode to the *output_charset*.
+   If no conversion codec is necessary, this attribute will have the same value as
+   the *input_codec*.
+
+:class:`Charset` instances also have the following methods:
+
+
+.. method:: Charset.get_body_encoding()
+
+   Return the content transfer encoding used for body encoding.
+
+   This is either the string ``quoted-printable`` or ``base64`` depending on the
+   encoding used, or it is a function, in which case you should call the function
+   with a single argument, the Message object being encoded.  The function should
+   then set the :mailheader:`Content-Transfer-Encoding` header itself to whatever
+   is appropriate.
+
+   Returns the string ``quoted-printable`` if *body_encoding* is ``QP``, returns
+   the string ``base64`` if *body_encoding* is ``BASE64``, and returns the string
+   ``7bit`` otherwise.
+
+
+.. method:: Charset.convert(s)
+
+   Convert the string *s* from the *input_codec* to the *output_codec*.
+
+
+.. method:: Charset.to_splittable(s)
+
+   Convert a possibly multibyte string to a safely splittable format. *s* is the
+   string to split.
+
+   Uses the *input_codec* to try and convert the string to Unicode, so it can be
+   safely split on character boundaries (even for multibyte characters).
+
+   Returns the string as-is if it isn't known how to convert *s* to Unicode with
+   the *input_charset*.
+
+   Characters that could not be converted to Unicode will be replaced with the
+   Unicode replacement character ``'U+FFFD'``.
+
+
+.. method:: Charset.from_splittable(ustr[, to_output])
+
+   Convert a splittable string back into an encoded string.  *ustr* is a Unicode
+   string to "unsplit".
+
+   This method uses the proper codec to try and convert the string from Unicode
+   back into an encoded format.  Return the string as-is if it is not Unicode, or
+   if it could not be converted from Unicode.
+
+   Characters that could not be converted from Unicode will be replaced with an
+   appropriate character (usually ``'?'``).
+
+   If *to_output* is ``True`` (the default), uses *output_codec* to convert to an
+   encoded format.  If *to_output* is ``False``, it uses *input_codec*.
+
+
+.. method:: Charset.get_output_charset()
+
+   Return the output character set.
+
+   This is the *output_charset* attribute if that is not ``None``, otherwise it is
+   *input_charset*.
+
+
+.. method:: Charset.encoded_header_len()
+
+   Return the length of the encoded header string, properly calculating for
+   quoted-printable or base64 encoding.
+
+
+.. method:: Charset.header_encode(s[, convert])
+
+   Header-encode the string *s*.
+
+   If *convert* is ``True``, the string will be converted from the input charset to
+   the output charset automatically.  This is not useful for multibyte character
+   sets, which have line length issues (multibyte characters must be split on a
+   character, not a byte boundary); use the higher-level :class:`Header` class to
+   deal with these issues (see :mod:`email.header`).  *convert* defaults to
+   ``False``.
+
+   The type of encoding (base64 or quoted-printable) will be based on the
+   *header_encoding* attribute.
+
+
+.. method:: Charset.body_encode(s[, convert])
+
+   Body-encode the string *s*.
+
+   If *convert* is ``True`` (the default), the string will be converted from the
+   input charset to output charset automatically. Unlike :meth:`header_encode`,
+   there are no issues with byte boundaries and multibyte charsets in email bodies,
+   so this is usually pretty safe.
+
+   The type of encoding (base64 or quoted-printable) will be based on the
+   *body_encoding* attribute.
+
+The :class:`Charset` class also provides a number of methods to support standard
+operations and built-in functions.
+
+
+.. method:: Charset.__str__()
+
+   Returns *input_charset* as a string coerced to lower case. :meth:`__repr__` is
+   an alias for :meth:`__str__`.
+
+
+.. method:: Charset.__eq__(other)
+
+   This method allows you to compare two :class:`Charset` instances for equality.
+
+
+.. method:: Header.__ne__(other)
+
+   This method allows you to compare two :class:`Charset` instances for inequality.
+
+The :mod:`email.charset` module also provides the following functions for adding
+new entries to the global character set, alias, and codec registries:
+
+
+.. function:: add_charset(charset[, header_enc[, body_enc[, output_charset]]])
+
+   Add character properties to the global registry.
+
+   *charset* is the input character set, and must be the canonical name of a
+   character set.
+
+   Optional *header_enc* and *body_enc* is either ``Charset.QP`` for
+   quoted-printable, ``Charset.BASE64`` for base64 encoding,
+   ``Charset.SHORTEST`` for the shortest of quoted-printable or base64 encoding,
+   or ``None`` for no encoding.  ``SHORTEST`` is only valid for
+   *header_enc*. The default is ``None`` for no encoding.
+
+   Optional *output_charset* is the character set that the output should be in.
+   Conversions will proceed from input charset, to Unicode, to the output charset
+   when the method :meth:`Charset.convert` is called.  The default is to output in
+   the same character set as the input.
+
+   Both *input_charset* and *output_charset* must have Unicode codec entries in the
+   module's character set-to-codec mapping; use :func:`add_codec` to add codecs the
+   module does not know about.  See the :mod:`codecs` module's documentation for
+   more information.
+
+   The global character set registry is kept in the module global dictionary
+   ``CHARSETS``.
+
+
+.. function:: add_alias(alias, canonical)
+
+   Add a character set alias.  *alias* is the alias name, e.g. ``latin-1``.
+   *canonical* is the character set's canonical name, e.g. ``iso-8859-1``.
+
+   The global charset alias registry is kept in the module global dictionary
+   ``ALIASES``.
+
+
+.. function:: add_codec(charset, codecname)
+
+   Add a codec that map characters in the given character set to and from Unicode.
+
+   *charset* is the canonical name of a character set. *codecname* is the name of a
+   Python codec, as appropriate for the second argument to the :func:`unicode`
+   built-in, or to the :meth:`encode` method of a Unicode string.
+

Doc/library/email.encoders.rst

@@ -0,0 +1,57 @@
+:mod:`email`: Encoders
+----------------------
+
+.. module:: email.encoders
+   :synopsis: Encoders for email message payloads.
+
+
+When creating :class:`Message` objects from scratch, you often need to encode
+the payloads for transport through compliant mail servers. This is especially
+true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages containing
+binary data.
+
+The :mod:`email` package provides some convenient encodings in its
+:mod:`encoders` module.  These encoders are actually used by the
+:class:`MIMEAudio` and :class:`MIMEImage` class constructors to provide default
+encodings.  All encoder functions take exactly one argument, the message object
+to encode.  They usually extract the payload, encode it, and reset the payload
+to this newly encoded value.  They should also set the
+:mailheader:`Content-Transfer-Encoding` header as appropriate.
+
+Here are the encoding functions provided:
+
+
+.. function:: encode_quopri(msg)
+
+   Encodes the payload into quoted-printable form and sets the
+   :mailheader:`Content-Transfer-Encoding` header to ``quoted-printable`` [#]_.
+   This is a good encoding to use when most of your payload is normal printable
+   data, but contains a few unprintable characters.
+
+
+.. function:: encode_base64(msg)
+
+   Encodes the payload into base64 form and sets the
+   :mailheader:`Content-Transfer-Encoding` header to ``base64``.  This is a good
+   encoding to use when most of your payload is unprintable data since it is a more
+   compact form than quoted-printable.  The drawback of base64 encoding is that it
+   renders the text non-human readable.
+
+
+.. function:: encode_7or8bit(msg)
+
+   This doesn't actually modify the message's payload, but it does set the
+   :mailheader:`Content-Transfer-Encoding` header to either ``7bit`` or ``8bit`` as
+   appropriate, based on the payload data.
+
+
+.. function:: encode_noop(msg)
+
+   This does nothing; it doesn't even set the
+   :mailheader:`Content-Transfer-Encoding` header.
+
+.. rubric:: Footnotes
+
+.. [#] Note that encoding with :meth:`encode_quopri` also encodes all tabs and space
+   characters in the data.
+

Doc/library/email.errors.rst

@@ -0,0 +1,91 @@
+:mod:`email`: Exception and Defect classes
+------------------------------------------
+
+.. module:: email.errors
+   :synopsis: The exception classes used by the email package.
+
+
+The following exception classes are defined in the :mod:`email.errors` module:
+
+
+.. exception:: MessageError()
+
+   This is the base class for all exceptions that the :mod:`email` package can
+   raise.  It is derived from the standard :exc:`Exception` class and defines no
+   additional methods.
+
+
+.. exception:: MessageParseError()
+
+   This is the base class for exceptions thrown by the :class:`Parser` class.  It
+   is derived from :exc:`MessageError`.
+
+
+.. exception:: HeaderParseError()
+
+   Raised under some error conditions when parsing the :rfc:`2822` headers of a
+   message, this class is derived from :exc:`MessageParseError`. It can be raised
+   from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
+
+   Situations where it can be raised include finding an envelope header after the
+   first :rfc:`2822` header of the message, finding a continuation line before the
+   first :rfc:`2822` header is found, or finding a line in the headers which is
+   neither a header or a continuation line.
+
+
+.. exception:: BoundaryError()
+
+   Raised under some error conditions when parsing the :rfc:`2822` headers of a
+   message, this class is derived from :exc:`MessageParseError`. It can be raised
+   from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
+
+   Situations where it can be raised include not being able to find the starting or
+   terminating boundary in a :mimetype:`multipart/\*` message when strict parsing
+   is used.
+
+
+.. exception:: MultipartConversionError()
+
+   Raised when a payload is added to a :class:`Message` object using
+   :meth:`add_payload`, but the payload is already a scalar and the message's
+   :mailheader:`Content-Type` main type is not either :mimetype:`multipart` or
+   missing.  :exc:`MultipartConversionError` multiply inherits from
+   :exc:`MessageError` and the built-in :exc:`TypeError`.
+
+   Since :meth:`Message.add_payload` is deprecated, this exception is rarely raised
+   in practice.  However the exception may also be raised if the :meth:`attach`
+   method is called on an instance of a class derived from
+   :class:`MIMENonMultipart` (e.g. :class:`MIMEImage`).
+
+Here's the list of the defects that the :class:`FeedParser` can find while
+parsing messages.  Note that the defects are added to the message where the
+problem was found, so for example, if a message nested inside a
+:mimetype:`multipart/alternative` had a malformed header, that nested message
+object would have a defect, but the containing messages would not.
+
+All defect classes are subclassed from :class:`email.errors.MessageDefect`, but
+this class is *not* an exception!
+
+.. versionadded:: 2.4
+   All the defect classes were added.
+
+* :class:`NoBoundaryInMultipartDefect` -- A message claimed to be a multipart,
+  but had no :mimetype:`boundary` parameter.
+
+* :class:`StartBoundaryNotFoundDefect` -- The start boundary claimed in the
+  :mailheader:`Content-Type` header was never found.
+
+* :class:`FirstHeaderLineIsContinuationDefect` -- The message had a continuation
+  line as its first header line.
+
+* :class:`MisplacedEnvelopeHeaderDefect` - A "Unix From" header was found in the
+  middle of a header block.
+
+* :class:`MalformedHeaderDefect` -- A header was found that was missing a colon,
+  or was otherwise malformed.
+
+* :class:`MultipartInvariantViolationDefect` -- A message claimed to be a
+  :mimetype:`multipart`, but no subparts were found.  Note that when a message has
+  this defect, its :meth:`is_multipart` method may return false even though its
+  content type claims to be :mimetype:`multipart`.
+

Doc/library/email.generator.rst

@@ -0,0 +1,123 @@
+:mod:`email`: Generating MIME documents
+---------------------------------------
+
+.. module:: email.generator
+   :synopsis: Generate flat text email messages from a message structure.
+
+
+One of the most common tasks is to generate the flat text of the email message
+represented by a message object structure.  You will need to do this if you want
+to send your message via the :mod:`smtplib` module or the :mod:`nntplib` module,
+or print the message on the console.  Taking a message object structure and
+producing a flat text document is the job of the :class:`Generator` class.
+
+Again, as with the :mod:`email.parser` module, you aren't limited to the
+functionality of the bundled generator; you could write one from scratch
+yourself.  However the bundled generator knows how to generate most email in a
+standards-compliant way, should handle MIME and non-MIME email messages just
+fine, and is designed so that the transformation from flat text, to a message
+structure via the :class:`Parser` class, and back to flat text, is idempotent
+(the input is identical to the output).
+
+Here are the public methods of the :class:`Generator` class, imported from the
+:mod:`email.generator` module:
+
+
+.. class:: Generator(outfp[, mangle_from_[, maxheaderlen]])
+
+   The constructor for the :class:`Generator` class takes a file-like object called
+   *outfp* for an argument.  *outfp* must support the :meth:`write` method and be
+   usable as the output file in a Python extended print statement.
+
+   Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` character in
+   front of any line in the body that starts exactly as ``From``, i.e. ``From``
+   followed by a space at the beginning of the line.  This is the only guaranteed
+   portable way to avoid having such lines be mistaken for a Unix mailbox format
+   envelope header separator (see `WHY THE CONTENT-LENGTH FORMAT IS BAD
+   <http://www.jwz.org/doc/content-length.html>`_ for details).  *mangle_from_*
+   defaults to ``True``, but you might want to set this to ``False`` if you are not
+   writing Unix mailbox format files.
+
+   Optional *maxheaderlen* specifies the longest length for a non-continued header.
+   When a header line is longer than *maxheaderlen* (in characters, with tabs
+   expanded to 8 spaces), the header will be split as defined in the
+   :mod:`email.header.Header` class.  Set to zero to disable header wrapping.  The
+   default is 78, as recommended (but not required) by :rfc:`2822`.
+
+The other public :class:`Generator` methods are:
+
+
+.. method:: Generator.flatten(msg[, unixfrom])
+
+   Print the textual representation of the message object structure rooted at *msg*
+   to the output file specified when the :class:`Generator` instance was created.
+   Subparts are visited depth-first and the resulting text will be properly MIME
+   encoded.
+
+   Optional *unixfrom* is a flag that forces the printing of the envelope header
+   delimiter before the first :rfc:`2822` header of the root message object.  If
+   the root object has no envelope header, a standard one is crafted.  By default,
+   this is set to ``False`` to inhibit the printing of the envelope delimiter.
+
+   Note that for subparts, no envelope header is ever printed.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Generator.clone(fp)
+
+   Return an independent clone of this :class:`Generator` instance with the exact
+   same options.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Generator.write(s)
+
+   Write the string *s* to the underlying file object, i.e. *outfp* passed to
+   :class:`Generator`'s constructor.  This provides just enough file-like API for
+   :class:`Generator` instances to be used in extended print statements.
+
+As a convenience, see the methods :meth:`Message.as_string` and
+``str(aMessage)``, a.k.a. :meth:`Message.__str__`, which simplify the generation
+of a formatted string representation of a message object.  For more detail, see
+:mod:`email.message`.
+
+The :mod:`email.generator` module also provides a derived class, called
+:class:`DecodedGenerator` which is like the :class:`Generator` base class,
+except that non-\ :mimetype:`text` parts are substituted with a format string
+representing the part.
+
+
+.. class:: DecodedGenerator(outfp[, mangle_from_[, maxheaderlen[, fmt]]])
+
+   This class, derived from :class:`Generator` walks through all the subparts of a
+   message.  If the subpart is of main type :mimetype:`text`, then it prints the
+   decoded payload of the subpart. Optional *_mangle_from_* and *maxheaderlen* are
+   as with the :class:`Generator` base class.
+
+   If the subpart is not of main type :mimetype:`text`, optional *fmt* is a format
+   string that is used instead of the message payload. *fmt* is expanded with the
+   following keywords, ``%(keyword)s`` format:
+
+   * ``type`` -- Full MIME type of the non-\ :mimetype:`text` part
+
+   * ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part
+
+   * ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part
+
+   * ``filename`` -- Filename of the non-\ :mimetype:`text` part
+
+   * ``description`` -- Description associated with the non-\ :mimetype:`text` part
+
+   * ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part
+
+   The default value for *fmt* is ``None``, meaning ::
+
+      [Non-text (%(type)s) part of message omitted, filename %(filename)s]
+
+   .. versionadded:: 2.2.2
+
+.. versionchanged:: 2.5
+   The previously deprecated method :meth:`__call__` was removed.
+

Doc/library/email.header.rst

@@ -0,0 +1,171 @@
+:mod:`email`: Internationalized headers
+---------------------------------------
+
+.. module:: email.header
+   :synopsis: Representing non-ASCII headers
+
+
+:rfc:`2822` is the base standard that describes the format of email messages.
+It derives from the older :rfc:`822` standard which came into widespread use at
+a time when most email was composed of ASCII characters only.  :rfc:`2822` is a
+specification written assuming email contains only 7-bit ASCII characters.
+
+Of course, as email has been deployed worldwide, it has become
+internationalized, such that language specific character sets can now be used in
+email messages.  The base standard still requires email messages to be
+transferred using only 7-bit ASCII characters, so a slew of RFCs have been
+written describing how to encode email containing non-ASCII characters into
+:rfc:`2822`\ -compliant format. These RFCs include :rfc:`2045`, :rfc:`2046`,
+:rfc:`2047`, and :rfc:`2231`. The :mod:`email` package supports these standards
+in its :mod:`email.header` and :mod:`email.charset` modules.
+
+If you want to include non-ASCII characters in your email headers, say in the
+:mailheader:`Subject` or :mailheader:`To` fields, you should use the
+:class:`Header` class and assign the field in the :class:`Message` object to an
+instance of :class:`Header` instead of using a string for the header value.
+Import the :class:`Header` class from the :mod:`email.header` module.  For
+example::
+
+   >>> from email.message import Message
+   >>> from email.header import Header
+   >>> msg = Message()
+   >>> h = Header('p\xf6stal', 'iso-8859-1')
+   >>> msg['Subject'] = h
+   >>> print msg.as_string()
+   Subject: =?iso-8859-1?q?p=F6stal?=
+
+
+
+Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
+character?  We did this by creating a :class:`Header` instance and passing in
+the character set that the byte string was encoded in.  When the subsequent
+:class:`Message` instance was flattened, the :mailheader:`Subject` field was
+properly :rfc:`2047` encoded.  MIME-aware mail readers would show this header
+using the embedded ISO-8859-1 character.
+
+.. versionadded:: 2.2.2
+
+Here is the :class:`Header` class description:
+
+
+.. class:: Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])
+
+   Create a MIME-compliant header that can contain strings in different character
+   sets.
+
+   Optional *s* is the initial header value.  If ``None`` (the default), the
+   initial header value is not set.  You can later append to the header with
+   :meth:`append` method calls.  *s* may be a byte string or a Unicode string, but
+   see the :meth:`append` documentation for semantics.
+
+   Optional *charset* serves two purposes: it has the same meaning as the *charset*
+   argument to the :meth:`append` method.  It also sets the default character set
+   for all subsequent :meth:`append` calls that omit the *charset* argument.  If
+   *charset* is not provided in the constructor (the default), the ``us-ascii``
+   character set is used both as *s*'s initial charset and as the default for
+   subsequent :meth:`append` calls.
+
+   The maximum line length can be specified explicit via *maxlinelen*.  For
+   splitting the first line to a shorter value (to account for the field header
+   which isn't included in *s*, e.g. :mailheader:`Subject`) pass in the name of the
+   field in *header_name*.  The default *maxlinelen* is 76, and the default value
+   for *header_name* is ``None``, meaning it is not taken into account for the
+   first line of a long, split header.
+
+   Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding whitespace,
+   and is usually either a space or a hard tab character. This character will be
+   prepended to continuation lines.
+
+Optional *errors* is passed straight through to the :meth:`append` method.
+
+
+.. method:: Header.append(s[, charset[, errors]])
+
+   Append the string *s* to the MIME header.
+
+   Optional *charset*, if given, should be a :class:`Charset` instance (see
+   :mod:`email.charset`) or the name of a character set, which will be converted to
+   a :class:`Charset` instance.  A value of ``None`` (the default) means that the
+   *charset* given in the constructor is used.
+
+   *s* may be a byte string or a Unicode string.  If it is a byte string (i.e.
+   ``isinstance(s, str)`` is true), then *charset* is the encoding of that byte
+   string, and a :exc:`UnicodeError` will be raised if the string cannot be decoded
+   with that character set.
+
+   If *s* is a Unicode string, then *charset* is a hint specifying the character
+   set of the characters in the string.  In this case, when producing an
+   :rfc:`2822`\ -compliant header using :rfc:`2047` rules, the Unicode string will
+   be encoded using the following charsets in order: ``us-ascii``, the *charset*
+   hint, ``utf-8``.  The first character set to not provoke a :exc:`UnicodeError`
+   is used.
+
+   Optional *errors* is passed through to any :func:`unicode` or
+   :func:`ustr.encode` call, and defaults to "strict".
+
+
+.. method:: Header.encode([splitchars])
+
+   Encode a message header into an RFC-compliant format, possibly wrapping long
+   lines and encapsulating non-ASCII parts in base64 or quoted-printable encodings.
+   Optional *splitchars* is a string containing characters to split long ASCII
+   lines on, in rough support of :rfc:`2822`'s *highest level syntactic breaks*.
+   This doesn't affect :rfc:`2047` encoded lines.
+
+The :class:`Header` class also provides a number of methods to support standard
+operators and built-in functions.
+
+
+.. method:: Header.__str__()
+
+   A synonym for :meth:`Header.encode`.  Useful for ``str(aHeader)``.
+
+
+.. method:: Header.__unicode__()
+
+   A helper for the built-in :func:`unicode` function.  Returns the header as a
+   Unicode string.
+
+
+.. method:: Header.__eq__(other)
+
+   This method allows you to compare two :class:`Header` instances for equality.
+
+
+.. method:: Header.__ne__(other)
+
+   This method allows you to compare two :class:`Header` instances for inequality.
+
+The :mod:`email.header` module also provides the following convenient functions.
+
+
+.. function:: decode_header(header)
+
+   Decode a message header value without converting the character set. The header
+   value is in *header*.
+
+   This function returns a list of ``(decoded_string, charset)`` pairs containing
+   each of the decoded parts of the header.  *charset* is ``None`` for non-encoded
+   parts of the header, otherwise a lower case string containing the name of the
+   character set specified in the encoded string.
+
+   Here's an example::
+
+      >>> from email.header import decode_header
+      >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
+      [('p\xf6stal', 'iso-8859-1')]
+
+
+.. function:: make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])
+
+   Create a :class:`Header` instance from a sequence of pairs as returned by
+   :func:`decode_header`.
+
+   :func:`decode_header` takes a header value string and returns a sequence of
+   pairs of the format ``(decoded_string, charset)`` where *charset* is the name of
+   the character set.
+
+   This function takes one of those sequence of pairs and returns a :class:`Header`
+   instance.  Optional *maxlinelen*, *header_name*, and *continuation_ws* are as in
+   the :class:`Header` constructor.
+

Doc/library/email.iterators.rst

@@ -0,0 +1,65 @@
+:mod:`email`: Iterators
+-----------------------
+
+.. module:: email.iterators
+   :synopsis: Iterate over a  message object tree.
+
+
+Iterating over a message object tree is fairly easy with the
+:meth:`Message.walk` method.  The :mod:`email.iterators` module provides some
+useful higher level iterations over message object trees.
+
+
+.. function:: body_line_iterator(msg[, decode])
+
+   This iterates over all the payloads in all the subparts of *msg*, returning the
+   string payloads line-by-line.  It skips over all the subpart headers, and it
+   skips over any subpart with a payload that isn't a Python string.  This is
+   somewhat equivalent to reading the flat text representation of the message from
+   a file using :meth:`readline`, skipping over all the intervening headers.
+
+   Optional *decode* is passed through to :meth:`Message.get_payload`.
+
+
+.. function:: typed_subpart_iterator(msg[, maintype[, subtype]])
+
+   This iterates over all the subparts of *msg*, returning only those subparts that
+   match the MIME type specified by *maintype* and *subtype*.
+
+   Note that *subtype* is optional; if omitted, then subpart MIME type matching is
+   done only with the main type.  *maintype* is optional too; it defaults to
+   :mimetype:`text`.
+
+   Thus, by default :func:`typed_subpart_iterator` returns each subpart that has a
+   MIME type of :mimetype:`text/\*`.
+
+The following function has been added as a useful debugging tool.  It should
+*not* be considered part of the supported public interface for the package.
+
+
+.. function:: _structure(msg[, fp[, level]])
+
+   Prints an indented representation of the content types of the message object
+   structure.  For example::
+
+      >>> msg = email.message_from_file(somefile)
+      >>> _structure(msg)
+      multipart/mixed
+          text/plain
+          text/plain
+          multipart/digest
+              message/rfc822
+                  text/plain
+              message/rfc822
+                  text/plain
+              message/rfc822
+                  text/plain
+              message/rfc822
+                  text/plain
+              message/rfc822
+                  text/plain
+          text/plain
+
+   Optional *fp* is a file-like object to print the output to.  It must be suitable
+   for Python's extended print statement.  *level* is used internally.
+

Doc/library/email.message.rst

@@ -0,0 +1,548 @@
+:mod:`email`: Representing an email message
+-------------------------------------------
+
+.. module:: email.message
+   :synopsis: The base class representing email messages.
+
+
+The central class in the :mod:`email` package is the :class:`Message` class,
+imported from the :mod:`email.message` module.  It is the base class for the
+:mod:`email` object model.  :class:`Message` provides the core functionality for
+setting and querying header fields, and for accessing message bodies.
+
+Conceptually, a :class:`Message` object consists of *headers* and *payloads*.
+Headers are :rfc:`2822` style field names and values where the field name and
+value are separated by a colon.  The colon is not part of either the field name
+or the field value.
+
+Headers are stored and returned in case-preserving form but are matched
+case-insensitively.  There may also be a single envelope header, also known as
+the *Unix-From* header or the ``From_`` header.  The payload is either a string
+in the case of simple message objects or a list of :class:`Message` objects for
+MIME container documents (e.g. :mimetype:`multipart/\*` and
+:mimetype:`message/rfc822`).
+
+:class:`Message` objects provide a mapping style interface for accessing the
+message headers, and an explicit interface for accessing both the headers and
+the payload.  It provides convenience methods for generating a flat text
+representation of the message object tree, for accessing commonly used header
+parameters, and for recursively walking over the object tree.
+
+Here are the methods of the :class:`Message` class:
+
+
+.. class:: Message()
+
+   The constructor takes no arguments.
+
+
+.. method:: Message.as_string([unixfrom])
+
+   Return the entire message flatten as a string.  When optional *unixfrom* is
+   ``True``, the envelope header is included in the returned string.  *unixfrom*
+   defaults to ``False``.
+
+   Note that this method is provided as a convenience and may not always format the
+   message the way you want.  For example, by default it mangles lines that begin
+   with ``From``.  For more flexibility, instantiate a :class:`Generator` instance
+   and use its :meth:`flatten` method directly.  For example::
+
+      from cStringIO import StringIO
+      from email.generator import Generator
+      fp = StringIO()
+      g = Generator(fp, mangle_from_=False, maxheaderlen=60)
+      g.flatten(msg)
+      text = fp.getvalue()
+
+
+.. method:: Message.__str__()
+
+   Equivalent to ``as_string(unixfrom=True)``.
+
+
+.. method:: Message.is_multipart()
+
+   Return ``True`` if the message's payload is a list of sub-\ :class:`Message`
+   objects, otherwise return ``False``.  When :meth:`is_multipart` returns False,
+   the payload should be a string object.
+
+
+.. method:: Message.set_unixfrom(unixfrom)
+
+   Set the message's envelope header to *unixfrom*, which should be a string.
+
+
+.. method:: Message.get_unixfrom()
+
+   Return the message's envelope header.  Defaults to ``None`` if the envelope
+   header was never set.
+
+
+.. method:: Message.attach(payload)
+
+   Add the given *payload* to the current payload, which must be ``None`` or a list
+   of :class:`Message` objects before the call. After the call, the payload will
+   always be a list of :class:`Message` objects.  If you want to set the payload to
+   a scalar object (e.g. a string), use :meth:`set_payload` instead.
+
+
+.. method:: Message.get_payload([i[, decode]])
+
+   Return a reference the current payload, which will be a list of :class:`Message`
+   objects when :meth:`is_multipart` is ``True``, or a string when
+   :meth:`is_multipart` is ``False``.  If the payload is a list and you mutate the
+   list object, you modify the message's payload in place.
+
+   With optional argument *i*, :meth:`get_payload` will return the *i*-th element
+   of the payload, counting from zero, if :meth:`is_multipart` is ``True``.  An
+   :exc:`IndexError` will be raised if *i* is less than 0 or greater than or equal
+   to the number of items in the payload.  If the payload is a string (i.e.
+   :meth:`is_multipart` is ``False``) and *i* is given, a :exc:`TypeError` is
+   raised.
+
+   Optional *decode* is a flag indicating whether the payload should be decoded or
+   not, according to the :mailheader:`Content-Transfer-Encoding` header. When
+   ``True`` and the message is not a multipart, the payload will be decoded if this
+   header's value is ``quoted-printable`` or ``base64``.  If some other encoding is
+   used, or :mailheader:`Content-Transfer-Encoding` header is missing, or if the
+   payload has bogus base64 data, the payload is returned as-is (undecoded).  If
+   the message is a multipart and the *decode* flag is ``True``, then ``None`` is
+   returned.  The default for *decode* is ``False``.
+
+
+.. method:: Message.set_payload(payload[, charset])
+
+   Set the entire message object's payload to *payload*.  It is the client's
+   responsibility to ensure the payload invariants.  Optional *charset* sets the
+   message's default character set; see :meth:`set_charset` for details.
+
+   .. versionchanged:: 2.2.2
+      *charset* argument added.
+
+
+.. method:: Message.set_charset(charset)
+
+   Set the character set of the payload to *charset*, which can either be a
+   :class:`Charset` instance (see :mod:`email.charset`), a string naming a
+   character set, or ``None``.  If it is a string, it will be converted to a
+   :class:`Charset` instance.  If *charset* is ``None``, the ``charset`` parameter
+   will be removed from the :mailheader:`Content-Type` header. Anything else will
+   generate a :exc:`TypeError`.
+
+   The message will be assumed to be of type :mimetype:`text/\*` encoded with
+   *charset.input_charset*.  It will be converted to *charset.output_charset* and
+   encoded properly, if needed, when generating the plain text representation of
+   the message.  MIME headers (:mailheader:`MIME-Version`,
+   :mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will be
+   added as needed.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_charset()
+
+   Return the :class:`Charset` instance associated with the message's payload.
+
+   .. versionadded:: 2.2.2
+
+The following methods implement a mapping-like interface for accessing the
+message's :rfc:`2822` headers.  Note that there are some semantic differences
+between these methods and a normal mapping (i.e. dictionary) interface.  For
+example, in a dictionary there are no duplicate keys, but here there may be
+duplicate message headers.  Also, in dictionaries there is no guaranteed order
+to the keys returned by :meth:`keys`, but in a :class:`Message` object, headers
+are always returned in the order they appeared in the original message, or were
+added to the message later.  Any header deleted and then re-added are always
+appended to the end of the header list.
+
+These semantic differences are intentional and are biased toward maximal
+convenience.
+
+Note that in all cases, any envelope header present in the message is not
+included in the mapping interface.
+
+
+.. method:: Message.__len__()
+
+   Return the total number of headers, including duplicates.
+
+
+.. method:: Message.__contains__(name)
+
+   Return true if the message object has a field named *name*. Matching is done
+   case-insensitively and *name* should not include the trailing colon.  Used for
+   the ``in`` operator, e.g.::
+
+      if 'message-id' in myMessage:
+          print 'Message-ID:', myMessage['message-id']
+
+
+.. method:: Message.__getitem__(name)
+
+   Return the value of the named header field.  *name* should not include the colon
+   field separator.  If the header is missing, ``None`` is returned; a
+   :exc:`KeyError` is never raised.
+
+   Note that if the named field appears more than once in the message's headers,
+   exactly which of those field values will be returned is undefined.  Use the
+   :meth:`get_all` method to get the values of all the extant named headers.
+
+
+.. method:: Message.__setitem__(name, val)
+
+   Add a header to the message with field name *name* and value *val*.  The field
+   is appended to the end of the message's existing fields.
+
+   Note that this does *not* overwrite or delete any existing header with the same
+   name.  If you want to ensure that the new header is the only one present in the
+   message with field name *name*, delete the field first, e.g.::
+
+      del msg['subject']
+      msg['subject'] = 'Python roolz!'
+
+
+.. method:: Message.__delitem__(name)
+
+   Delete all occurrences of the field with name *name* from the message's headers.
+   No exception is raised if the named field isn't present in the headers.
+
+
+.. method:: Message.has_key(name)
+
+   Return true if the message contains a header field named *name*, otherwise
+   return false.
+
+
+.. method:: Message.keys()
+
+   Return a list of all the message's header field names.
+
+
+.. method:: Message.values()
+
+   Return a list of all the message's field values.
+
+
+.. method:: Message.items()
+
+   Return a list of 2-tuples containing all the message's field headers and values.
+
+
+.. method:: Message.get(name[, failobj])
+
+   Return the value of the named header field.  This is identical to
+   :meth:`__getitem__` except that optional *failobj* is returned if the named
+   header is missing (defaults to ``None``).
+
+Here are some additional useful methods:
+
+
+.. method:: Message.get_all(name[, failobj])
+
+   Return a list of all the values for the field named *name*. If there are no such
+   named headers in the message, *failobj* is returned (defaults to ``None``).
+
+
+.. method:: Message.add_header(_name, _value, **_params)
+
+   Extended header setting.  This method is similar to :meth:`__setitem__` except
+   that additional header parameters can be provided as keyword arguments.  *_name*
+   is the header field to add and *_value* is the *primary* value for the header.
+
+   For each item in the keyword argument dictionary *_params*, the key is taken as
+   the parameter name, with underscores converted to dashes (since dashes are
+   illegal in Python identifiers).  Normally, the parameter will be added as
+   ``key="value"`` unless the value is ``None``, in which case only the key will be
+   added.
+
+   Here's an example::
+
+      msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
+
+   This will add a header that looks like ::
+
+      Content-Disposition: attachment; filename="bud.gif"
+
+
+.. method:: Message.replace_header(_name, _value)
+
+   Replace a header.  Replace the first header found in the message that matches
+   *_name*, retaining header order and field name case.  If no matching header was
+   found, a :exc:`KeyError` is raised.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_content_type()
+
+   Return the message's content type.  The returned string is coerced to lower case
+   of the form :mimetype:`maintype/subtype`.  If there was no
+   :mailheader:`Content-Type` header in the message the default type as given by
+   :meth:`get_default_type` will be returned.  Since according to :rfc:`2045`,
+   messages always have a default type, :meth:`get_content_type` will always return
+   a value.
+
+   :rfc:`2045` defines a message's default type to be :mimetype:`text/plain` unless
+   it appears inside a :mimetype:`multipart/digest` container, in which case it
+   would be :mimetype:`message/rfc822`.  If the :mailheader:`Content-Type` header
+   has an invalid type specification, :rfc:`2045` mandates that the default type be
+   :mimetype:`text/plain`.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_content_maintype()
+
+   Return the message's main content type.  This is the :mimetype:`maintype` part
+   of the string returned by :meth:`get_content_type`.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_content_subtype()
+
+   Return the message's sub-content type.  This is the :mimetype:`subtype` part of
+   the string returned by :meth:`get_content_type`.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_default_type()
+
+   Return the default content type.  Most messages have a default content type of
+   :mimetype:`text/plain`, except for messages that are subparts of
+   :mimetype:`multipart/digest` containers.  Such subparts have a default content
+   type of :mimetype:`message/rfc822`.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Message.set_default_type(ctype)
+
+   Set the default content type.  *ctype* should either be :mimetype:`text/plain`
+   or :mimetype:`message/rfc822`, although this is not enforced.  The default
+   content type is not stored in the :mailheader:`Content-Type` header.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_params([failobj[, header[, unquote]]])
+
+   Return the message's :mailheader:`Content-Type` parameters, as a list.  The
+   elements of the returned list are 2-tuples of key/value pairs, as split on the
+   ``'='`` sign.  The left hand side of the ``'='`` is the key, while the right
+   hand side is the value.  If there is no ``'='`` sign in the parameter the value
+   is the empty string, otherwise the value is as described in :meth:`get_param`
+   and is unquoted if optional *unquote* is ``True`` (the default).
+
+   Optional *failobj* is the object to return if there is no
+   :mailheader:`Content-Type` header.  Optional *header* is the header to search
+   instead of :mailheader:`Content-Type`.
+
+   .. versionchanged:: 2.2.2
+      *unquote* argument added.
+
+
+.. method:: Message.get_param(param[, failobj[, header[, unquote]]])
+
+   Return the value of the :mailheader:`Content-Type` header's parameter *param* as
+   a string.  If the message has no :mailheader:`Content-Type` header or if there
+   is no such parameter, then *failobj* is returned (defaults to ``None``).
+
+   Optional *header* if given, specifies the message header to use instead of
+   :mailheader:`Content-Type`.
+
+   Parameter keys are always compared case insensitively.  The return value can
+   either be a string, or a 3-tuple if the parameter was :rfc:`2231` encoded.  When
+   it's a 3-tuple, the elements of the value are of the form ``(CHARSET, LANGUAGE,
+   VALUE)``.  Note that both ``CHARSET`` and ``LANGUAGE`` can be ``None``, in which
+   case you should consider ``VALUE`` to be encoded in the ``us-ascii`` charset.
+   You can usually ignore ``LANGUAGE``.
+
+   If your application doesn't care whether the parameter was encoded as in
+   :rfc:`2231`, you can collapse the parameter value by calling
+   :func:`email.Utils.collapse_rfc2231_value`, passing in the return value from
+   :meth:`get_param`.  This will return a suitably decoded Unicode string whn the
+   value is a tuple, or the original string unquoted if it isn't.  For example::
+
+      rawparam = msg.get_param('foo')
+      param = email.Utils.collapse_rfc2231_value(rawparam)
+
+   In any case, the parameter value (either the returned string, or the ``VALUE``
+   item in the 3-tuple) is always unquoted, unless *unquote* is set to ``False``.
+
+   .. versionchanged:: 2.2.2
+      *unquote* argument added, and 3-tuple return value possible.
+
+
+.. method:: Message.set_param(param, value[, header[, requote[, charset[, language]]]])
+
+   Set a parameter in the :mailheader:`Content-Type` header.  If the parameter
+   already exists in the header, its value will be replaced with *value*.  If the
+   :mailheader:`Content-Type` header as not yet been defined for this message, it
+   will be set to :mimetype:`text/plain` and the new parameter value will be
+   appended as per :rfc:`2045`.
+
+   Optional *header* specifies an alternative header to :mailheader:`Content-Type`,
+   and all parameters will be quoted as necessary unless optional *requote* is
+   ``False`` (the default is ``True``).
+
+   If optional *charset* is specified, the parameter will be encoded according to
+   :rfc:`2231`. Optional *language* specifies the RFC 2231 language, defaulting to
+   the empty string.  Both *charset* and *language* should be strings.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Message.del_param(param[, header[, requote]])
+
+   Remove the given parameter completely from the :mailheader:`Content-Type`
+   header.  The header will be re-written in place without the parameter or its
+   value.  All values will be quoted as necessary unless *requote* is ``False``
+   (the default is ``True``).  Optional *header* specifies an alternative to
+   :mailheader:`Content-Type`.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Message.set_type(type[, header][, requote])
+
+   Set the main type and subtype for the :mailheader:`Content-Type` header. *type*
+   must be a string in the form :mimetype:`maintype/subtype`, otherwise a
+   :exc:`ValueError` is raised.
+
+   This method replaces the :mailheader:`Content-Type` header, keeping all the
+   parameters in place.  If *requote* is ``False``, this leaves the existing
+   header's quoting as is, otherwise the parameters will be quoted (the default).
+
+   An alternative header can be specified in the *header* argument. When the
+   :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version` header is
+   also added.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_filename([failobj])
+
+   Return the value of the ``filename`` parameter of the
+   :mailheader:`Content-Disposition` header of the message.  If the header does not
+   have a ``filename`` parameter, this method falls back to looking for the
+   ``name`` parameter.  If neither is found, or the header is missing, then
+   *failobj* is returned.  The returned string will always be unquoted as per
+   :meth:`Utils.unquote`.
+
+
+.. method:: Message.get_boundary([failobj])
+
+   Return the value of the ``boundary`` parameter of the :mailheader:`Content-Type`
+   header of the message, or *failobj* if either the header is missing, or has no
+   ``boundary`` parameter.  The returned string will always be unquoted as per
+   :meth:`Utils.unquote`.
+
+
+.. method:: Message.set_boundary(boundary)
+
+   Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
+   *boundary*.  :meth:`set_boundary` will always quote *boundary* if necessary.  A
+   :exc:`HeaderParseError` is raised if the message object has no
+   :mailheader:`Content-Type` header.
+
+   Note that using this method is subtly different than deleting the old
+   :mailheader:`Content-Type` header and adding a new one with the new boundary via
+   :meth:`add_header`, because :meth:`set_boundary` preserves the order of the
+   :mailheader:`Content-Type` header in the list of headers. However, it does *not*
+   preserve any continuation lines which may have been present in the original
+   :mailheader:`Content-Type` header.
+
+
+.. method:: Message.get_content_charset([failobj])
+
+   Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
+   coerced to lower case.  If there is no :mailheader:`Content-Type` header, or if
+   that header has no ``charset`` parameter, *failobj* is returned.
+
+   Note that this method differs from :meth:`get_charset` which returns the
+   :class:`Charset` instance for the default encoding of the message body.
+
+   .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_charsets([failobj])
+
+   Return a list containing the character set names in the message.  If the message
+   is a :mimetype:`multipart`, then the list will contain one element for each
+   subpart in the payload, otherwise, it will be a list of length 1.
+
+   Each item in the list will be a string which is the value of the ``charset``
+   parameter in the :mailheader:`Content-Type` header for the represented subpart.
+   However, if the subpart has no :mailheader:`Content-Type` header, no ``charset``
+   parameter, or is not of the :mimetype:`text` main MIME type, then that item in
+   the returned list will be *failobj*.
+
+
+.. method:: Message.walk()
+
+   The :meth:`walk` method is an all-purpose generator which can be used to iterate
+   over all the parts and subparts of a message object tree, in depth-first
+   traversal order.  You will typically use :meth:`walk` as the iterator in a
+   ``for`` loop; each iteration returns the next subpart.
+
+   Here's an example that prints the MIME type of every part of a multipart message
+   structure::
+
+      >>> for part in msg.walk():
+      ...     print part.get_content_type()
+      multipart/report
+      text/plain
+      message/delivery-status
+      text/plain
+      text/plain
+      message/rfc822
+
+.. versionchanged:: 2.5
+   The previously deprecated methods :meth:`get_type`, :meth:`get_main_type`, and
+   :meth:`get_subtype` were removed.
+
+:class:`Message` objects can also optionally contain two instance attributes,
+which can be used when generating the plain text of a MIME message.
+
+
+.. data:: preamble
+
+   The format of a MIME document allows for some text between the blank line
+   following the headers, and the first multipart boundary string. Normally, this
+   text is never visible in a MIME-aware mail reader because it falls outside the
+   standard MIME armor.  However, when viewing the raw text of the message, or when
+   viewing the message in a non-MIME aware reader, this text can become visible.
+
+   The *preamble* attribute contains this leading extra-armor text for MIME
+   documents.  When the :class:`Parser` discovers some text after the headers but
+   before the first boundary string, it assigns this text to the message's
+   *preamble* attribute.  When the :class:`Generator` is writing out the plain text
+   representation of a MIME message, and it finds the message has a *preamble*
+   attribute, it will write this text in the area between the headers and the first
+   boundary.  See :mod:`email.parser` and :mod:`email.generator` for details.
+
+   Note that if the message object has no preamble, the *preamble* attribute will
+   be ``None``.
+
+
+.. data:: epilogue
+
+   The *epilogue* attribute acts the same way as the *preamble* attribute, except
+   that it contains text that appears between the last boundary and the end of the
+   message.
+
+   .. versionchanged:: 2.5
+      You do not need to set the epilogue to the empty string in order for the
+      :class:`Generator` to print a newline at the end of the file.
+
+
+.. data:: defects
+
+   The *defects* attribute contains a list of all the problems found when parsing
+   this message.  See :mod:`email.errors` for a detailed description of the
+   possible parsing defects.
+
+   .. versionadded:: 2.4
+

Doc/library/email.mime.rst

@@ -0,0 +1,175 @@
+:mod:`email`: Creating email and MIME objects from scratch
+----------------------------------------------------------
+
+.. module:: email.mime
+   :synopsis: Build MIME messages. 
+
+
+Ordinarily, you get a message object structure by passing a file or some text to
+a parser, which parses the text and returns the root message object.  However
+you can also build a complete message structure from scratch, or even individual
+:class:`Message` objects by hand.  In fact, you can also take an existing
+structure and add new :class:`Message` objects, move them around, etc.  This
+makes a very convenient interface for slicing-and-dicing MIME messages.
+
+You can create a new object structure by creating :class:`Message` instances,
+adding attachments and all the appropriate headers manually.  For MIME messages
+though, the :mod:`email` package provides some convenient subclasses to make
+things easier.
+
+Here are the classes:
+
+
+.. class:: MIMEBase(_maintype, _subtype, **_params)
+
+   Module: :mod:`email.mime.base`
+
+   This is the base class for all the MIME-specific subclasses of :class:`Message`.
+   Ordinarily you won't create instances specifically of :class:`MIMEBase`,
+   although you could.  :class:`MIMEBase` is provided primarily as a convenient
+   base class for more specific MIME-aware subclasses.
+
+   *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
+   or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
+   type  (e.g. :mimetype:`plain` or :mimetype:`gif`).  *_params* is a parameter
+   key/value dictionary and is passed directly to :meth:`Message.add_header`.
+
+   The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
+   (based on *_maintype*, *_subtype*, and *_params*), and a
+   :mailheader:`MIME-Version` header (always set to ``1.0``).
+
+
+.. class:: MIMENonMultipart()
+
+   Module: :mod:`email.mime.nonmultipart`
+
+   A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
+   messages that are not :mimetype:`multipart`.  The primary purpose of this class
+   is to prevent the use of the :meth:`attach` method, which only makes sense for
+   :mimetype:`multipart` messages.  If :meth:`attach` is called, a
+   :exc:`MultipartConversionError` exception is raised.
+
+   .. versionadded:: 2.2.2
+
+
+.. class:: MIMEMultipart([subtype[, boundary[, _subparts[, _params]]]])
+
+   Module: :mod:`email.mime.multipart`
+
+   A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
+   messages that are :mimetype:`multipart`.  Optional *_subtype* defaults to
+   :mimetype:`mixed`, but can be used to specify the subtype of the message.  A
+   :mailheader:`Content-Type` header of :mimetype:`multipart/`*_subtype* will be
+   added to the message object.  A :mailheader:`MIME-Version` header will also be
+   added.
+
+   Optional *boundary* is the multipart boundary string.  When ``None`` (the
+   default), the boundary is calculated when needed.
+
+   *_subparts* is a sequence of initial subparts for the payload.  It must be
+   possible to convert this sequence to a list.  You can always attach new subparts
+   to the message by using the :meth:`Message.attach` method.
+
+   Additional parameters for the :mailheader:`Content-Type` header are taken from
+   the keyword arguments, or passed into the *_params* argument, which is a keyword
+   dictionary.
+
+   .. versionadded:: 2.2.2
+
+
+.. class:: MIMEApplication(_data[, _subtype[, _encoder[, **_params]]])
+
+   Module: :mod:`email.mime.application`
+
+   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEApplication` class is
+   used to represent MIME message objects of major type :mimetype:`application`.
+   *_data* is a string containing the raw byte data.  Optional *_subtype* specifies
+   the MIME subtype and defaults to :mimetype:`octet-stream`.
+
+   Optional *_encoder* is a callable (i.e. function) which will perform the actual
+   encoding of the data for transport.  This callable takes one argument, which is
+   the :class:`MIMEApplication` instance. It should use :meth:`get_payload` and
+   :meth:`set_payload` to change the payload to encoded form.  It should also add
+   any :mailheader:`Content-Transfer-Encoding` or other headers to the message
+   object as necessary.  The default encoding is base64.  See the
+   :mod:`email.encoders` module for a list of the built-in encoders.
+
+   *_params* are passed straight through to the base class constructor.
+
+   .. versionadded:: 2.5
+
+
+.. class:: MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])
+
+   Module: :mod:`email.mime.audio`
+
+   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEAudio` class is used to
+   create MIME message objects of major type :mimetype:`audio`. *_audiodata* is a
+   string containing the raw audio data.  If this data can be decoded by the
+   standard Python module :mod:`sndhdr`, then the subtype will be automatically
+   included in the :mailheader:`Content-Type` header.  Otherwise you can explicitly
+   specify the audio subtype via the *_subtype* parameter.  If the minor type could
+   not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.
+
+   Optional *_encoder* is a callable (i.e. function) which will perform the actual
+   encoding of the audio data for transport.  This callable takes one argument,
+   which is the :class:`MIMEAudio` instance. It should use :meth:`get_payload` and
+   :meth:`set_payload` to change the payload to encoded form.  It should also add
+   any :mailheader:`Content-Transfer-Encoding` or other headers to the message
+   object as necessary.  The default encoding is base64.  See the
+   :mod:`email.encoders` module for a list of the built-in encoders.
+
+   *_params* are passed straight through to the base class constructor.
+
+
+.. class:: MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]])
+
+   Module: :mod:`email.mime.image`
+
+   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEImage` class is used to
+   create MIME message objects of major type :mimetype:`image`. *_imagedata* is a
+   string containing the raw image data.  If this data can be decoded by the
+   standard Python module :mod:`imghdr`, then the subtype will be automatically
+   included in the :mailheader:`Content-Type` header.  Otherwise you can explicitly
+   specify the image subtype via the *_subtype* parameter.  If the minor type could
+   not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.
+
+   Optional *_encoder* is a callable (i.e. function) which will perform the actual
+   encoding of the image data for transport.  This callable takes one argument,
+   which is the :class:`MIMEImage` instance. It should use :meth:`get_payload` and
+   :meth:`set_payload` to change the payload to encoded form.  It should also add
+   any :mailheader:`Content-Transfer-Encoding` or other headers to the message
+   object as necessary.  The default encoding is base64.  See the
+   :mod:`email.encoders` module for a list of the built-in encoders.
+
+   *_params* are passed straight through to the :class:`MIMEBase` constructor.
+
+
+.. class:: MIMEMessage(_msg[, _subtype])
+
+   Module: :mod:`email.mime.message`
+
+   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEMessage` class is used
+   to create MIME objects of main type :mimetype:`message`. *_msg* is used as the
+   payload, and must be an instance of class :class:`Message` (or a subclass
+   thereof), otherwise a :exc:`TypeError` is raised.
+
+   Optional *_subtype* sets the subtype of the message; it defaults to
+   :mimetype:`rfc822`.
+
+
+.. class:: MIMEText(_text[, _subtype[, _charset]])
+
+   Module: :mod:`email.mime.text`
+
+   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEText` class is used to
+   create MIME objects of major type :mimetype:`text`. *_text* is the string for
+   the payload.  *_subtype* is the minor type and defaults to :mimetype:`plain`.
+   *_charset* is the character set of the text and is passed as a parameter to the
+   :class:`MIMENonMultipart` constructor; it defaults to ``us-ascii``.  No guessing
+   or encoding is performed on the text data.
+
+   .. versionchanged:: 2.4
+      The previously deprecated *_encoding* argument has been removed.  Encoding
+      happens implicitly based on the *_charset* argument.
+

Doc/library/email.parser.rst

@@ -0,0 +1,220 @@
+:mod:`email`: Parsing email messages
+------------------------------------
+
+.. module:: email.parser
+   :synopsis: Parse flat text email messages to produce a message object structure.
+
+
+Message object structures can be created in one of two ways: they can be created
+from whole cloth by instantiating :class:`Message` objects and stringing them
+together via :meth:`attach` and :meth:`set_payload` calls, or they can be
+created by parsing a flat text representation of the email message.
+
+The :mod:`email` package provides a standard parser that understands most email
+document structures, including MIME documents.  You can pass the parser a string
+or a file object, and the parser will return to you the root :class:`Message`
+instance of the object structure.  For simple, non-MIME messages the payload of
+this root object will likely be a string containing the text of the message.
+For MIME messages, the root object will return ``True`` from its
+:meth:`is_multipart` method, and the subparts can be accessed via the
+:meth:`get_payload` and :meth:`walk` methods.
+
+There are actually two parser interfaces available for use, the classic
+:class:`Parser` API and the incremental :class:`FeedParser` API.  The classic
+:class:`Parser` API is fine if you have the entire text of the message in memory
+as a string, or if the entire message lives in a file on the file system.
+:class:`FeedParser` is more appropriate for when you're reading the message from
+a stream which might block waiting for more input (e.g. reading an email message
+from a socket).  The :class:`FeedParser` can consume and parse the message
+incrementally, and only returns the root object when you close the parser [#]_.
+
+Note that the parser can be extended in limited ways, and of course you can
+implement your own parser completely from scratch.  There is no magical
+connection between the :mod:`email` package's bundled parser and the
+:class:`Message` class, so your custom parser can create message object trees
+any way it finds necessary.
+
+
+FeedParser API
+^^^^^^^^^^^^^^
+
+.. versionadded:: 2.4
+
+The :class:`FeedParser`, imported from the :mod:`email.feedparser` module,
+provides an API that is conducive to incremental parsing of email messages, such
+as would be necessary when reading the text of an email message from a source
+that can block (e.g. a socket).  The :class:`FeedParser` can of course be used
+to parse an email message fully contained in a string or a file, but the classic
+:class:`Parser` API may be more convenient for such use cases.  The semantics
+and results of the two parser APIs are identical.
+
+The :class:`FeedParser`'s API is simple; you create an instance, feed it a bunch
+of text until there's no more to feed it, then close the parser to retrieve the
+root message object.  The :class:`FeedParser` is extremely accurate when parsing
+standards-compliant messages, and it does a very good job of parsing
+non-compliant messages, providing information about how a message was deemed
+broken.  It will populate a message object's *defects* attribute with a list of
+any problems it found in a message.  See the :mod:`email.errors` module for the
+list of defects that it can find.
+
+Here is the API for the :class:`FeedParser`:
+
+
+.. class:: FeedParser([_factory])
+
+   Create a :class:`FeedParser` instance.  Optional *_factory* is a no-argument
+   callable that will be called whenever a new message object is needed.  It
+   defaults to the :class:`email.message.Message` class.
+
+
+.. method:: FeedParser.feed(data)
+
+   Feed the :class:`FeedParser` some more data.  *data* should be a string
+   containing one or more lines.  The lines can be partial and the
+   :class:`FeedParser` will stitch such partial lines together properly.  The lines
+   in the string can have any of the common three line endings, carriage return,
+   newline, or carriage return and newline (they can even be mixed).
+
+
+.. method:: FeedParser.close()
+
+   Closing a :class:`FeedParser` completes the parsing of all previously fed data,
+   and returns the root message object.  It is undefined what happens if you feed
+   more data to a closed :class:`FeedParser`.
+
+
+Parser class API
+^^^^^^^^^^^^^^^^
+
+The :class:`Parser` class, imported from the :mod:`email.parser` module,
+provides an API that can be used to parse a message when the complete contents
+of the message are available in a string or file.  The :mod:`email.parser`
+module also provides a second class, called :class:`HeaderParser` which can be
+used if you're only interested in the headers of the message.
+:class:`HeaderParser` can be much faster in these situations, since it does not
+attempt to parse the message body, instead setting the payload to the raw body
+as a string. :class:`HeaderParser` has the same API as the :class:`Parser`
+class.
+
+
+.. class:: Parser([_class])
+
+   The constructor for the :class:`Parser` class takes an optional argument
+   *_class*.  This must be a callable factory (such as a function or a class), and
+   it is used whenever a sub-message object needs to be created.  It defaults to
+   :class:`Message` (see :mod:`email.message`).  The factory will be called without
+   arguments.
+
+   The optional *strict* flag is ignored.
+
+   .. deprecated:: 2.4
+      Because the :class:`Parser` class is a backward compatible API wrapper
+      around the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is
+      effectively non-strict.  You should simply stop passing a *strict* flag to
+      the :class:`Parser` constructor.
+
+   .. versionchanged:: 2.2.2
+      The *strict* flag was added.
+
+   .. versionchanged:: 2.4
+      The *strict* flag was deprecated.
+
+The other public :class:`Parser` methods are:
+
+
+.. method:: Parser.parse(fp[, headersonly])
+
+   Read all the data from the file-like object *fp*, parse the resulting text, and
+   return the root message object.  *fp* must support both the :meth:`readline` and
+   the :meth:`read` methods on file-like objects.
+
+   The text contained in *fp* must be formatted as a block of :rfc:`2822` style
+   headers and header continuation lines, optionally preceded by a envelope
+   header.  The header block is terminated either by the end of the data or by a
+   blank line.  Following the header block is the body of the message (which may
+   contain MIME-encoded subparts).
+
+   Optional *headersonly* is as with the :meth:`parse` method.
+
+   .. versionchanged:: 2.2.2
+      The *headersonly* flag was added.
+
+
+.. method:: Parser.parsestr(text[, headersonly])
+
+   Similar to the :meth:`parse` method, except it takes a string object instead of
+   a file-like object.  Calling this method on a string is exactly equivalent to
+   wrapping *text* in a :class:`StringIO` instance first and calling :meth:`parse`.
+
+   Optional *headersonly* is a flag specifying whether to stop parsing after
+   reading the headers or not.  The default is ``False``, meaning it parses the
+   entire contents of the file.
+
+   .. versionchanged:: 2.2.2
+      The *headersonly* flag was added.
+
+Since creating a message object structure from a string or a file object is such
+a common task, two functions are provided as a convenience.  They are available
+in the top-level :mod:`email` package namespace.
+
+
+.. function:: message_from_string(s[, _class[, strict]])
+
+   Return a message object structure from a string.  This is exactly equivalent to
+   ``Parser().parsestr(s)``.  Optional *_class* and *strict* are interpreted as
+   with the :class:`Parser` class constructor.
+
+   .. versionchanged:: 2.2.2
+      The *strict* flag was added.
+
+
+.. function:: message_from_file(fp[, _class[, strict]])
+
+   Return a message object structure tree from an open file object.  This is
+   exactly equivalent to ``Parser().parse(fp)``.  Optional *_class* and *strict*
+   are interpreted as with the :class:`Parser` class constructor.
+
+   .. versionchanged:: 2.2.2
+      The *strict* flag was added.
+
+Here's an example of how you might use this at an interactive Python prompt::
+
+   >>> import email
+   >>> msg = email.message_from_string(myString)
+
+
+Additional notes
+^^^^^^^^^^^^^^^^
+
+Here are some notes on the parsing semantics:
+
+* Most non-\ :mimetype:`multipart` type messages are parsed as a single message
+  object with a string payload.  These objects will return ``False`` for
+  :meth:`is_multipart`.  Their :meth:`get_payload` method will return a string
+  object.
+
+* All :mimetype:`multipart` type messages will be parsed as a container message
+  object with a list of sub-message objects for their payload.  The outer
+  container message will return ``True`` for :meth:`is_multipart` and their
+  :meth:`get_payload` method will return the list of :class:`Message` subparts.
+
+* Most messages with a content type of :mimetype:`message/\*` (e.g.
+  :mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be
+  parsed as container object containing a list payload of length 1.  Their
+  :meth:`is_multipart` method will return ``True``.  The single element in the
+  list payload will be a sub-message object.
+
+* Some non-standards compliant messages may not be internally consistent about
+  their :mimetype:`multipart`\ -edness.  Such messages may have a
+  :mailheader:`Content-Type` header of type :mimetype:`multipart`, but their
+  :meth:`is_multipart` method may return ``False``.  If such messages were parsed
+  with the :class:`FeedParser`, they will have an instance of the
+  :class:`MultipartInvariantViolationDefect` class in their *defects* attribute
+  list.  See :mod:`email.errors` for details.
+
+.. rubric:: Footnotes
+
+.. [#] As of email package version 3.0, introduced in Python 2.4, the classic
+   :class:`Parser` was re-implemented in terms of the :class:`FeedParser`, so the
+   semantics and results are identical between the two parsers.
+

Doc/library/email.rst

@@ -0,0 +1,324 @@
+.. % Copyright (C) 2001-2007 Python Software Foundation
+.. % Author: barry@python.org (Barry Warsaw)
+
+
+:mod:`email` --- An email and MIME handling package
+===================================================
+
+.. module:: email
+   :synopsis: Package supporting the parsing, manipulating, and generating email messages,
+              including MIME documents.
+.. moduleauthor:: Barry A. Warsaw <barry@python.org>
+.. sectionauthor:: Barry A. Warsaw <barry@python.org>
+
+
+.. versionadded:: 2.2
+
+The :mod:`email` package is a library for managing email messages, including
+MIME and other :rfc:`2822`\ -based message documents.  It subsumes most of the
+functionality in several older standard modules such as :mod:`rfc822`,
+:mod:`mimetools`, :mod:`multifile`, and other non-standard packages such as
+:mod:`mimecntl`.  It is specifically *not* designed to do any sending of email
+messages to SMTP (:rfc:`2821`), NNTP, or other servers; those are functions of
+modules such as :mod:`smtplib` and :mod:`nntplib`. The :mod:`email` package
+attempts to be as RFC-compliant as possible, supporting in addition to
+:rfc:`2822`, such MIME-related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`,
+and :rfc:`2231`.
+
+The primary distinguishing feature of the :mod:`email` package is that it splits
+the parsing and generating of email messages from the internal *object model*
+representation of email.  Applications using the :mod:`email` package deal
+primarily with objects; you can add sub-objects to messages, remove sub-objects
+from messages, completely re-arrange the contents, etc.  There is a separate
+parser and a separate generator which handles the transformation from flat text
+to the object model, and then back to flat text again.  There are also handy
+subclasses for some common MIME object types, and a few miscellaneous utilities
+that help with such common tasks as extracting and parsing message field values,
+creating RFC-compliant dates, etc.
+
+The following sections describe the functionality of the :mod:`email` package.
+The ordering follows a progression that should be common in applications: an
+email message is read as flat text from a file or other source, the text is
+parsed to produce the object structure of the email message, this structure is
+manipulated, and finally, the object tree is rendered back into flat text.
+
+It is perfectly feasible to create the object structure out of whole cloth ---
+i.e. completely from scratch.  From there, a similar progression can be taken as
+above.
+
+Also included are detailed specifications of all the classes and modules that
+the :mod:`email` package provides, the exception classes you might encounter
+while using the :mod:`email` package, some auxiliary utilities, and a few
+examples.  For users of the older :mod:`mimelib` package, or previous versions
+of the :mod:`email` package, a section on differences and porting is provided.
+
+Contents of the :mod:`email` package documentation:
+
+.. toctree::
+
+   email.message.rst
+   email.parser.rst
+   email.generator.rst
+   email.mime.rst
+   email.header.rst
+   email.charset.rst
+   email.encoders.rst
+   email.errors.rst
+   email.util.rst
+   email.iterators.rst
+   email-examples.rst
+
+
+.. seealso::
+
+   Module :mod:`smtplib`
+      SMTP protocol client
+
+   Module :mod:`nntplib`
+      NNTP protocol client
+
+
+.. _email-pkg-history:
+
+Package History
+---------------
+
+This table describes the release history of the email package, corresponding to
+the version of Python that the package was released with.  For purposes of this
+document, when you see a note about change or added versions, these refer to the
+Python version the change was made in, *not* the email package version.  This
+table also describes the Python compatibility of each version of the package.
+
++---------------+------------------------------+-----------------------+
+| email version | distributed with             | compatible with       |
++===============+==============================+=======================+
+| :const:`1.x`  | Python 2.2.0 to Python 2.2.1 | *no longer supported* |
++---------------+------------------------------+-----------------------+
+| :const:`2.5`  | Python 2.2.2+ and Python 2.3 | Python 2.1 to 2.5     |
++---------------+------------------------------+-----------------------+
+| :const:`3.0`  | Python 2.4                   | Python 2.3 to 2.5     |
++---------------+------------------------------+-----------------------+
+| :const:`4.0`  | Python 2.5                   | Python 2.3 to 2.5     |
++---------------+------------------------------+-----------------------+
+
+Here are the major differences between :mod:`email` version 4 and version 3:
+
+* All modules have been renamed according to :pep:`8` standards.  For example,
+  the version 3 module :mod:`email.Message` was renamed to :mod:`email.message` in
+  version 4.
+
+* A new subpackage :mod:`email.mime` was added and all the version 3
+  :mod:`email.MIME\*` modules were renamed and situated into the :mod:`email.mime`
+  subpackage.  For example, the version 3 module :mod:`email.MIMEText` was renamed
+  to :mod:`email.mime.text`.
+
+  *Note that the version 3 names will continue to work until Python 2.6*.
+
+* The :mod:`email.mime.application` module was added, which contains the
+  :class:`MIMEApplication` class.
+
+* Methods that were deprecated in version 3 have been removed.  These include
+  :meth:`Generator.__call__`, :meth:`Message.get_type`,
+  :meth:`Message.get_main_type`, :meth:`Message.get_subtype`.
+
+* Fixes have been added for :rfc:`2231` support which can change some of the
+  return types for :func:`Message.get_param` and friends.  Under some
+  circumstances, values which used to return a 3-tuple now return simple strings
+  (specifically, if all extended parameter segments were unencoded, there is no
+  language and charset designation expected, so the return type is now a simple
+  string).  Also, %-decoding used to be done for both encoded and unencoded
+  segments; this decoding is now done only for encoded segments.
+
+Here are the major differences between :mod:`email` version 3 and version 2:
+
+* The :class:`FeedParser` class was introduced, and the :class:`Parser` class
+  was implemented in terms of the :class:`FeedParser`.  All parsing therefore is
+  non-strict, and parsing will make a best effort never to raise an exception.
+  Problems found while parsing messages are stored in the message's *defect*
+  attribute.
+
+* All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2
+  have been removed.  These include the *_encoder* argument to the
+  :class:`MIMEText` constructor, the :meth:`Message.add_payload` method, the
+  :func:`Utils.dump_address_pair` function, and the functions :func:`Utils.decode`
+  and :func:`Utils.encode`.
+
+* New :exc:`DeprecationWarning`\ s have been added to:
+  :meth:`Generator.__call__`, :meth:`Message.get_type`,
+  :meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict*
+  argument to the :class:`Parser` class.  These are expected to be removed in
+  future versions.
+
+* Support for Pythons earlier than 2.3 has been removed.
+
+Here are the differences between :mod:`email` version 2 and version 1:
+
+* The :mod:`email.Header` and :mod:`email.Charset` modules have been added.
+
+* The pickle format for :class:`Message` instances has changed. Since this was
+  never (and still isn't) formally defined, this isn't considered a backward
+  incompatibility.  However if your application pickles and unpickles
+  :class:`Message` instances, be aware that in :mod:`email` version 2,
+  :class:`Message` instances now have private variables *_charset* and
+  *_default_type*.
+
+* Several methods in the :class:`Message` class have been deprecated, or their
+  signatures changed.  Also, many new methods have been added.  See the
+  documentation for the :class:`Message` class for details.  The changes should be
+  completely backward compatible.
+
+* The object structure has changed in the face of :mimetype:`message/rfc822`
+  content types.  In :mod:`email` version 1, such a type would be represented by a
+  scalar payload, i.e. the container message's :meth:`is_multipart` returned
+  false, :meth:`get_payload` was not a list object, but a single :class:`Message`
+  instance.
+
+  This structure was inconsistent with the rest of the package, so the object
+  representation for :mimetype:`message/rfc822` content types was changed.  In
+  :mod:`email` version 2, the container *does* return ``True`` from
+  :meth:`is_multipart`, and :meth:`get_payload` returns a list containing a single
+  :class:`Message` item.
+
+  Note that this is one place that backward compatibility could not be completely
+  maintained.  However, if you're already testing the return type of
+  :meth:`get_payload`, you should be fine.  You just need to make sure your code
+  doesn't do a :meth:`set_payload` with a :class:`Message` instance on a container
+  with a content type of :mimetype:`message/rfc822`.
+
+* The :class:`Parser` constructor's *strict* argument was added, and its
+  :meth:`parse` and :meth:`parsestr` methods grew a *headersonly* argument.  The
+  *strict* flag was also added to functions :func:`email.message_from_file` and
+  :func:`email.message_from_string`.
+
+* :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten`
+  instead.  The :class:`Generator` class has also grown the :meth:`clone` method.
+
+* The :class:`DecodedGenerator` class in the :mod:`email.Generator` module was
+  added.
+
+* The intermediate base classes :class:`MIMENonMultipart` and
+  :class:`MIMEMultipart` have been added, and interposed in the class hierarchy
+  for most of the other MIME-related derived classes.
+
+* The *_encoder* argument to the :class:`MIMEText` constructor has been
+  deprecated.  Encoding  now happens implicitly based on the *_charset* argument.
+
+* The following functions in the :mod:`email.Utils` module have been deprecated:
+  :func:`dump_address_pairs`, :func:`decode`, and :func:`encode`.  The following
+  functions have been added to the module: :func:`make_msgid`,
+  :func:`decode_rfc2231`, :func:`encode_rfc2231`, and :func:`decode_params`.
+
+* The non-public function :func:`email.Iterators._structure` was added.
+
+
+Differences from :mod:`mimelib`
+-------------------------------
+
+The :mod:`email` package was originally prototyped as a separate library called
+`mimelib <http://mimelib.sf.net/>`_. Changes have been made so that method names
+are more consistent, and some methods or modules have either been added or
+removed.  The semantics of some of the methods have also changed.  For the most
+part, any functionality available in :mod:`mimelib` is still available in the
+:mod:`email` package, albeit often in a different way.  Backward compatibility
+between the :mod:`mimelib` package and the :mod:`email` package was not a
+priority.
+
+Here is a brief description of the differences between the :mod:`mimelib` and
+the :mod:`email` packages, along with hints on how to port your applications.
+
+Of course, the most visible difference between the two packages is that the
+package name has been changed to :mod:`email`.  In addition, the top-level
+package has the following differences:
+
+* :func:`messageFromString` has been renamed to :func:`message_from_string`.
+
+* :func:`messageFromFile` has been renamed to :func:`message_from_file`.
+
+The :class:`Message` class has the following differences:
+
+* The method :meth:`asString` was renamed to :meth:`as_string`.
+
+* The method :meth:`ismultipart` was renamed to :meth:`is_multipart`.
+
+* The :meth:`get_payload` method has grown a *decode* optional argument.
+
+* The method :meth:`getall` was renamed to :meth:`get_all`.
+
+* The method :meth:`addheader` was renamed to :meth:`add_header`.
+
+* The method :meth:`gettype` was renamed to :meth:`get_type`.
+
+* The method :meth:`getmaintype` was renamed to :meth:`get_main_type`.
+
+* The method :meth:`getsubtype` was renamed to :meth:`get_subtype`.
+
+* The method :meth:`getparams` was renamed to :meth:`get_params`. Also, whereas
+  :meth:`getparams` returned a list of strings, :meth:`get_params` returns a list
+  of 2-tuples, effectively the key/value pairs of the parameters, split on the
+  ``'='`` sign.
+
+* The method :meth:`getparam` was renamed to :meth:`get_param`.
+
+* The method :meth:`getcharsets` was renamed to :meth:`get_charsets`.
+
+* The method :meth:`getfilename` was renamed to :meth:`get_filename`.
+
+* The method :meth:`getboundary` was renamed to :meth:`get_boundary`.
+
+* The method :meth:`setboundary` was renamed to :meth:`set_boundary`.
+
+* The method :meth:`getdecodedpayload` was removed.  To get similar
+  functionality, pass the value 1 to the *decode* flag of the get_payload()
+  method.
+
+* The method :meth:`getpayloadastext` was removed.  Similar functionality is
+  supported by the :class:`DecodedGenerator` class in the :mod:`email.generator`
+  module.
+
+* The method :meth:`getbodyastext` was removed.  You can get similar
+  functionality by creating an iterator with :func:`typed_subpart_iterator` in the
+  :mod:`email.iterators` module.
+
+The :class:`Parser` class has no differences in its public interface. It does
+have some additional smarts to recognize :mimetype:`message/delivery-status`
+type messages, which it represents as a :class:`Message` instance containing
+separate :class:`Message` subparts for each header block in the delivery status
+notification [#]_.
+
+The :class:`Generator` class has no differences in its public interface.  There
+is a new class in the :mod:`email.generator` module though, called
+:class:`DecodedGenerator` which provides most of the functionality previously
+available in the :meth:`Message.getpayloadastext` method.
+
+The following modules and classes have been changed:
+
+* The :class:`MIMEBase` class constructor arguments *_major* and *_minor* have
+  changed to *_maintype* and *_subtype* respectively.
+
+* The ``Image`` class/module has been renamed to ``MIMEImage``.  The *_minor*
+  argument has been renamed to *_subtype*.
+
+* The ``Text`` class/module has been renamed to ``MIMEText``.  The *_minor*
+  argument has been renamed to *_subtype*.
+
+* The ``MessageRFC822`` class/module has been renamed to ``MIMEMessage``.  Note
+  that an earlier version of :mod:`mimelib` called this class/module ``RFC822``,
+  but that clashed with the Python standard library module :mod:`rfc822` on some
+  case-insensitive file systems.
+
+  Also, the :class:`MIMEMessage` class now represents any kind of MIME message
+  with main type :mimetype:`message`.  It takes an optional argument *_subtype*
+  which is used to set the MIME subtype.  *_subtype* defaults to
+  :mimetype:`rfc822`.
+
+:mod:`mimelib` provided some utility functions in its :mod:`address` and
+:mod:`date` modules.  All of these functions have been moved to the
+:mod:`email.utils` module.
+
+The ``MsgReader`` class/module has been removed.  Its functionality is most
+closely supported in the :func:`body_line_iterator` function in the
+:mod:`email.iterators` module.
+
+.. rubric:: Footnotes
+
+.. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`.

Doc/library/email.util.rst

@@ -0,0 +1,166 @@
+:mod:`email`: Miscellaneous utilities
+-------------------------------------
+
+.. module:: email.utils
+   :synopsis: Miscellaneous email package utilities.
+
+
+There are several useful utilities provided in the :mod:`email.utils` module:
+
+
+.. function:: quote(str)
+
+   Return a new string with backslashes in *str* replaced by two backslashes, and
+   double quotes replaced by backslash-double quote.
+
+
+.. function:: unquote(str)
+
+   Return a new string which is an *unquoted* version of *str*. If *str* ends and
+   begins with double quotes, they are stripped off.  Likewise if *str* ends and
+   begins with angle brackets, they are stripped off.
+
+
+.. function:: parseaddr(address)
+
+   Parse address -- which should be the value of some address-containing field such
+   as :mailheader:`To` or :mailheader:`Cc` -- into its constituent *realname* and
+   *email address* parts.  Returns a tuple of that information, unless the parse
+   fails, in which case a 2-tuple of ``('', '')`` is returned.
+
+
+.. function:: formataddr(pair)
+
+   The inverse of :meth:`parseaddr`, this takes a 2-tuple of the form ``(realname,
+   email_address)`` and returns the string value suitable for a :mailheader:`To` or
+   :mailheader:`Cc` header.  If the first element of *pair* is false, then the
+   second element is returned unmodified.
+
+
+.. function:: getaddresses(fieldvalues)
+
+   This method returns a list of 2-tuples of the form returned by ``parseaddr()``.
+   *fieldvalues* is a sequence of header field values as might be returned by
+   :meth:`Message.get_all`.  Here's a simple example that gets all the recipients
+   of a message::
+
+      from email.utils import getaddresses
+
+      tos = msg.get_all('to', [])
+      ccs = msg.get_all('cc', [])
+      resent_tos = msg.get_all('resent-to', [])
+      resent_ccs = msg.get_all('resent-cc', [])
+      all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
+
+
+.. function:: parsedate(date)
+
+   Attempts to parse a date according to the rules in :rfc:`2822`. however, some
+   mailers don't follow that format as specified, so :func:`parsedate` tries to
+   guess correctly in such cases.  *date* is a string containing an :rfc:`2822`
+   date, such as  ``"Mon, 20 Nov 1995 19:12:08 -0500"``.  If it succeeds in parsing
+   the date, :func:`parsedate` returns a 9-tuple that can be passed directly to
+   :func:`time.mktime`; otherwise ``None`` will be returned.  Note that indexes 6,
+   7, and 8 of the result tuple are not usable.
+
+
+.. function:: parsedate_tz(date)
+
+   Performs the same function as :func:`parsedate`, but returns either ``None`` or
+   a 10-tuple; the first 9 elements make up a tuple that can be passed directly to
+   :func:`time.mktime`, and the tenth is the offset of the date's timezone from UTC
+   (which is the official term for Greenwich Mean Time) [#]_.  If the input string
+   has no timezone, the last element of the tuple returned is ``None``.  Note that
+   indexes 6, 7, and 8 of the result tuple are not usable.
+
+
+.. function:: mktime_tz(tuple)
+
+   Turn a 10-tuple as returned by :func:`parsedate_tz` into a UTC timestamp.  It
+   the timezone item in the tuple is ``None``, assume local time.  Minor
+   deficiency: :func:`mktime_tz` interprets the first 8 elements of *tuple* as a
+   local time and then compensates for the timezone difference.  This may yield a
+   slight error around changes in daylight savings time, though not worth worrying
+   about for common use.
+
+
+.. function:: formatdate([timeval[, localtime][, usegmt]])
+
+   Returns a date string as per :rfc:`2822`, e.g.::
+
+      Fri, 09 Nov 2001 01:08:47 -0000
+
+   Optional *timeval* if given is a floating point time value as accepted by
+   :func:`time.gmtime` and :func:`time.localtime`, otherwise the current time is
+   used.
+
+   Optional *localtime* is a flag that when ``True``, interprets *timeval*, and
+   returns a date relative to the local timezone instead of UTC, properly taking
+   daylight savings time into account. The default is ``False`` meaning UTC is
+   used.
+
+   Optional *usegmt* is a flag that when ``True``, outputs a  date string with the
+   timezone as an ascii string ``GMT``, rather than a numeric ``-0000``. This is
+   needed for some protocols (such as HTTP). This only applies when *localtime* is
+   ``False``.
+
+   .. versionadded:: 2.4
+
+
+.. function:: make_msgid([idstring])
+
+   Returns a string suitable for an :rfc:`2822`\ -compliant
+   :mailheader:`Message-ID` header.  Optional *idstring* if given, is a string used
+   to strengthen the uniqueness of the message id.
+
+
+.. function:: decode_rfc2231(s)
+
+   Decode the string *s* according to :rfc:`2231`.
+
+
+.. function:: encode_rfc2231(s[, charset[, language]])
+
+   Encode the string *s* according to :rfc:`2231`.  Optional *charset* and
+   *language*, if given is the character set name and language name to use.  If
+   neither is given, *s* is returned as-is.  If *charset* is given but *language*
+   is not, the string is encoded using the empty string for *language*.
+
+
+.. function:: collapse_rfc2231_value(value[, errors[, fallback_charset]])
+
+   When a header parameter is encoded in :rfc:`2231` format,
+   :meth:`Message.get_param` may return a 3-tuple containing the character set,
+   language, and value.  :func:`collapse_rfc2231_value` turns this into a unicode
+   string.  Optional *errors* is passed to the *errors* argument of the built-in
+   :func:`unicode` function; it defaults to ``replace``.  Optional
+   *fallback_charset* specifies the character set to use if the one in the
+   :rfc:`2231` header is not known by Python; it defaults to ``us-ascii``.
+
+   For convenience, if the *value* passed to :func:`collapse_rfc2231_value` is not
+   a tuple, it should be a string and it is returned unquoted.
+
+
+.. function:: decode_params(params)
+
+   Decode parameters list according to :rfc:`2231`.  *params* is a sequence of
+   2-tuples containing elements of the form ``(content-type, string-value)``.
+
+.. versionchanged:: 2.4
+   The :func:`dump_address_pair` function has been removed; use :func:`formataddr`
+   instead.
+
+.. versionchanged:: 2.4
+   The :func:`decode` function has been removed; use the
+   :meth:`Header.decode_header` method instead.
+
+.. versionchanged:: 2.4
+   The :func:`encode` function has been removed; use the :meth:`Header.encode`
+   method instead.
+
+.. rubric:: Footnotes
+
+.. [#] Note that the sign of the timezone offset is the opposite of the sign of the
+   ``time.timezone`` variable for the same timezone; the latter variable follows
+   the POSIX standard while this module follows :rfc:`2822`.
+

Doc/library/errno.rst

@@ -0,0 +1,636 @@
+
+:mod:`errno` --- Standard errno system symbols
+==============================================
+
+.. module:: errno
+   :synopsis: Standard errno system symbols.
+
+
+This module makes available standard ``errno`` system symbols. The value of each
+symbol is the corresponding integer value. The names and descriptions are
+borrowed from :file:`linux/include/errno.h`, which should be pretty
+all-inclusive.
+
+
+.. data:: errorcode
+
+   Dictionary providing a mapping from the errno value to the string name in the
+   underlying system.  For instance, ``errno.errorcode[errno.EPERM]`` maps to
+   ``'EPERM'``.
+
+To translate a numeric error code to an error message, use :func:`os.strerror`.
+
+Of the following list, symbols that are not used on the current platform are not
+defined by the module.  The specific list of defined symbols is available as
+``errno.errorcode.keys()``.  Symbols available can include:
+
+
+.. data:: EPERM
+
+   Operation not permitted
+
+
+.. data:: ENOENT
+
+   No such file or directory
+
+
+.. data:: ESRCH
+
+   No such process
+
+
+.. data:: EINTR
+
+   Interrupted system call
+
+
+.. data:: EIO
+
+   I/O error
+
+
+.. data:: ENXIO
+
+   No such device or address
+
+
+.. data:: E2BIG
+
+   Arg list too long
+
+
+.. data:: ENOEXEC
+
+   Exec format error
+
+
+.. data:: EBADF
+
+   Bad file number
+
+
+.. data:: ECHILD
+
+   No child processes
+
+
+.. data:: EAGAIN
+
+   Try again
+
+
+.. data:: ENOMEM
+
+   Out of memory
+
+
+.. data:: EACCES
+
+   Permission denied
+
+
+.. data:: EFAULT
+
+   Bad address
+
+
+.. data:: ENOTBLK
+
+   Block device required
+
+
+.. data:: EBUSY
+
+   Device or resource busy
+
+
+.. data:: EEXIST
+
+   File exists
+
+
+.. data:: EXDEV
+
+   Cross-device link
+
+
+.. data:: ENODEV
+
+   No such device
+
+
+.. data:: ENOTDIR
+
+   Not a directory
+
+
+.. data:: EISDIR
+
+   Is a directory
+
+
+.. data:: EINVAL
+
+   Invalid argument
+
+
+.. data:: ENFILE
+
+   File table overflow
+
+
+.. data:: EMFILE
+
+   Too many open files
+
+
+.. data:: ENOTTY
+
+   Not a typewriter
+
+
+.. data:: ETXTBSY
+
+   Text file busy
+
+
+.. data:: EFBIG
+
+   File too large
+
+
+.. data:: ENOSPC
+
+   No space left on device
+
+
+.. data:: ESPIPE
+
+   Illegal seek
+
+
+.. data:: EROFS
+
+   Read-only file system
+
+
+.. data:: EMLINK
+
+   Too many links
+
+
+.. data:: EPIPE
+
+   Broken pipe
+
+
+.. data:: EDOM
+
+   Math argument out of domain of func
+
+
+.. data:: ERANGE
+
+   Math result not representable
+
+
+.. data:: EDEADLK
+
+   Resource deadlock would occur
+
+
+.. data:: ENAMETOOLONG
+
+   File name too long
+
+
+.. data:: ENOLCK
+
+   No record locks available
+
+
+.. data:: ENOSYS
+
+   Function not implemented
+
+
+.. data:: ENOTEMPTY
+
+   Directory not empty
+
+
+.. data:: ELOOP
+
+   Too many symbolic links encountered
+
+
+.. data:: EWOULDBLOCK
+
+   Operation would block
+
+
+.. data:: ENOMSG
+
+   No message of desired type
+
+
+.. data:: EIDRM
+
+   Identifier removed
+
+
+.. data:: ECHRNG
+
+   Channel number out of range
+
+
+.. data:: EL2NSYNC
+
+   Level 2 not synchronized
+
+
+.. data:: EL3HLT
+
+   Level 3 halted
+
+
+.. data:: EL3RST
+
+   Level 3 reset
+
+
+.. data:: ELNRNG
+
+   Link number out of range
+
+
+.. data:: EUNATCH
+
+   Protocol driver not attached
+
+
+.. data:: ENOCSI
+
+   No CSI structure available
+
+
+.. data:: EL2HLT
+
+   Level 2 halted
+
+
+.. data:: EBADE
+
+   Invalid exchange
+
+
+.. data:: EBADR
+
+   Invalid request descriptor
+
+
+.. data:: EXFULL
+
+   Exchange full
+
+
+.. data:: ENOANO
+
+   No anode
+
+
+.. data:: EBADRQC
+
+   Invalid request code
+
+
+.. data:: EBADSLT
+
+   Invalid slot
+
+
+.. data:: EDEADLOCK
+
+   File locking deadlock error
+
+
+.. data:: EBFONT
+
+   Bad font file format
+
+
+.. data:: ENOSTR
+
+   Device not a stream
+
+
+.. data:: ENODATA
+
+   No data available
+
+
+.. data:: ETIME
+
+   Timer expired
+
+
+.. data:: ENOSR
+
+   Out of streams resources
+
+
+.. data:: ENONET
+
+   Machine is not on the network
+
+
+.. data:: ENOPKG
+
+   Package not installed
+
+
+.. data:: EREMOTE
+
+   Object is remote
+
+
+.. data:: ENOLINK
+
+   Link has been severed
+
+
+.. data:: EADV
+
+   Advertise error
+
+
+.. data:: ESRMNT
+
+   Srmount error
+
+
+.. data:: ECOMM
+
+   Communication error on send
+
+
+.. data:: EPROTO
+
+   Protocol error
+
+
+.. data:: EMULTIHOP
+
+   Multihop attempted
+
+
+.. data:: EDOTDOT
+
+   RFS specific error
+
+
+.. data:: EBADMSG
+
+   Not a data message
+
+
+.. data:: EOVERFLOW
+
+   Value too large for defined data type
+
+
+.. data:: ENOTUNIQ
+
+   Name not unique on network
+
+
+.. data:: EBADFD
+
+   File descriptor in bad state
+
+
+.. data:: EREMCHG
+
+   Remote address changed
+
+
+.. data:: ELIBACC
+
+   Can not access a needed shared library
+
+
+.. data:: ELIBBAD
+
+   Accessing a corrupted shared library
+
+
+.. data:: ELIBSCN
+
+   .lib section in a.out corrupted
+
+
+.. data:: ELIBMAX
+
+   Attempting to link in too many shared libraries
+
+
+.. data:: ELIBEXEC
+
+   Cannot exec a shared library directly
+
+
+.. data:: EILSEQ
+
+   Illegal byte sequence
+
+
+.. data:: ERESTART
+
+   Interrupted system call should be restarted
+
+
+.. data:: ESTRPIPE
+
+   Streams pipe error
+
+
+.. data:: EUSERS
+
+   Too many users
+
+
+.. data:: ENOTSOCK
+
+   Socket operation on non-socket
+
+
+.. data:: EDESTADDRREQ
+
+   Destination address required
+
+
+.. data:: EMSGSIZE
+
+   Message too long
+
+
+.. data:: EPROTOTYPE
+
+   Protocol wrong type for socket
+
+
+.. data:: ENOPROTOOPT
+
+   Protocol not available
+
+
+.. data:: EPROTONOSUPPORT
+
+   Protocol not supported
+
+
+.. data:: ESOCKTNOSUPPORT
+
+   Socket type not supported
+
+
+.. data:: EOPNOTSUPP
+
+   Operation not supported on transport endpoint
+
+
+.. data:: EPFNOSUPPORT
+
+   Protocol family not supported
+
+
+.. data:: EAFNOSUPPORT
+
+   Address family not supported by protocol
+
+
+.. data:: EADDRINUSE
+
+   Address already in use
+
+
+.. data:: EADDRNOTAVAIL
+
+   Cannot assign requested address
+
+
+.. data:: ENETDOWN
+
+   Network is down
+
+
+.. data:: ENETUNREACH
+
+   Network is unreachable
+
+
+.. data:: ENETRESET
+
+   Network dropped connection because of reset
+
+
+.. data:: ECONNABORTED
+
+   Software caused connection abort
+
+
+.. data:: ECONNRESET
+
+   Connection reset by peer
+
+
+.. data:: ENOBUFS
+
+   No buffer space available
+
+
+.. data:: EISCONN
+
+   Transport endpoint is already connected
+
+
+.. data:: ENOTCONN
+
+   Transport endpoint is not connected
+
+
+.. data:: ESHUTDOWN
+
+   Cannot send after transport endpoint shutdown
+
+
+.. data:: ETOOMANYREFS
+
+   Too many references: cannot splice
+
+
+.. data:: ETIMEDOUT
+
+   Connection timed out
+
+
+.. data:: ECONNREFUSED
+
+   Connection refused
+
+
+.. data:: EHOSTDOWN
+
+   Host is down
+
+
+.. data:: EHOSTUNREACH
+
+   No route to host
+
+
+.. data:: EALREADY
+
+   Operation already in progress
+
+
+.. data:: EINPROGRESS
+
+   Operation now in progress
+
+
+.. data:: ESTALE
+
+   Stale NFS file handle
+
+
+.. data:: EUCLEAN
+
+   Structure needs cleaning
+
+
+.. data:: ENOTNAM
+
+   Not a XENIX named type file
+
+
+.. data:: ENAVAIL
+
+   No XENIX semaphores available
+
+
+.. data:: EISNAM
+
+   Is a named type file
+
+
+.. data:: EREMOTEIO
+
+   Remote I/O error
+
+
+.. data:: EDQUOT
+
+   Quota exceeded
+

Doc/library/exceptions.rst

@@ -0,0 +1,475 @@
+.. _bltin-exceptions:
+
+Built-in Exceptions
+===================
+
+.. module:: exceptions
+   :synopsis: Standard exception classes.
+
+
+Exceptions should be class objects.   The exceptions are defined in the module
+:mod:`exceptions`.  This module never needs to be imported explicitly: the
+exceptions are provided in the built-in namespace as well as the
+:mod:`exceptions` module.
+
+.. index::
+   statement: try
+   statement: except
+
+For class exceptions, in a :keyword:`try` statement with an :keyword:`except`
+clause that mentions a particular class, that clause also handles any exception
+classes derived from that class (but not exception classes from which *it* is
+derived).  Two exception classes that are not related via subclassing are never
+equivalent, even if they have the same name.
+
+.. index:: statement: raise
+
+The built-in exceptions listed below can be generated by the interpreter or
+built-in functions.  Except where mentioned, they have an "associated value"
+indicating the detailed cause of the error. This may be a string or a tuple
+containing several items of information (e.g., an error code and a string
+explaining the code). The associated value is the second argument to the
+:keyword:`raise` statement.  If the exception class is derived from the standard
+root class :exc:`BaseException`, the associated value is present as the
+exception instance's :attr:`args` attribute.
+
+User code can raise built-in exceptions.  This can be used to test an exception
+handler or to report an error condition "just like" the situation in which the
+interpreter raises the same exception; but beware that there is nothing to
+prevent user code from raising an inappropriate error.
+
+The built-in exception classes can be sub-classed to define new exceptions;
+programmers are encouraged to at least derive new exceptions from the
+:exc:`Exception` class and not :exc:`BaseException`.  More information on
+defining exceptions is available in the Python Tutorial under
+:ref:`tut-userexceptions`.
+
+The following exceptions are only used as base classes for other exceptions.
+
+
+.. exception:: BaseException
+
+   The base class for all built-in exceptions.  It is not meant to be directly
+   inherited by user-defined classes (for that use :exc:`Exception`).  If
+   :func:`str` or :func:`unicode` is called on an instance of this class, the
+   representation of the argument(s) to the instance are returned or the emptry
+   string when there were no arguments.  All arguments are  stored in :attr:`args`
+   as a tuple.
+
+   .. versionadded:: 2.5
+
+
+.. exception:: Exception
+
+   All built-in, non-system-exiting exceptions are derived from this class.  All
+   user-defined exceptions should also be derived from this class.
+
+   .. versionchanged:: 2.5
+      Changed to inherit from :exc:`BaseException`.
+
+
+.. exception:: ArithmeticError
+
+   The base class for those built-in exceptions that are raised for various
+   arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`,
+   :exc:`FloatingPointError`.
+
+
+.. exception:: LookupError
+
+   The base class for the exceptions that are raised when a key or index used on a
+   mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`.  This can be
+   raised directly by :func:`sys.setdefaultencoding`.
+
+
+.. exception:: EnvironmentError
+
+   The base class for exceptions that can occur outside the Python system:
+   :exc:`IOError`, :exc:`OSError`.  When exceptions of this type are created with a
+   2-tuple, the first item is available on the instance's :attr:`errno` attribute
+   (it is assumed to be an error number), and the second item is available on the
+   :attr:`strerror` attribute (it is usually the associated error message).  The
+   tuple itself is also available on the :attr:`args` attribute.
+
+   .. versionadded:: 1.5.2
+
+   When an :exc:`EnvironmentError` exception is instantiated with a 3-tuple, the
+   first two items are available as above, while the third item is available on the
+   :attr:`filename` attribute.  However, for backwards compatibility, the
+   :attr:`args` attribute contains only a 2-tuple of the first two constructor
+   arguments.
+
+   The :attr:`filename` attribute is ``None`` when this exception is created with
+   other than 3 arguments.  The :attr:`errno` and :attr:`strerror` attributes are
+   also ``None`` when the instance was created with other than 2 or 3 arguments.
+   In this last case, :attr:`args` contains the verbatim constructor arguments as a
+   tuple.
+
+The following exceptions are the exceptions that are actually raised.
+
+
+.. exception:: AssertionError
+
+   .. index:: statement: assert
+
+   Raised when an :keyword:`assert` statement fails.
+
+
+.. exception:: AttributeError
+
+   Raised when an attribute reference or assignment fails.  (When an object does
+   not support attribute references or attribute assignments at all,
+   :exc:`TypeError` is raised.)
+
+   .. % xref to attribute reference?
+
+
+.. exception:: EOFError
+
+   Raised when attempting to read beyond the end of a file. (N.B.: the :meth:`read`
+   and :meth:`readline` methods of file objects return an empty string when they
+   hit EOF.)
+
+   .. % XXXJH xrefs here
+   .. % XXXJH xrefs here
+
+
+.. exception:: FloatingPointError
+
+   Raised when a floating point operation fails.  This exception is always defined,
+   but can only be raised when Python is configured with the
+   :option:`--with-fpectl` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
+   defined in the :file:`pyconfig.h` file.
+
+
+.. exception:: GeneratorExit
+
+   Raise when a generator's :meth:`close` method is called.
+
+   .. versionadded:: 2.5
+
+   .. versionchanged:: 3.0
+      Changed to inherit from Exception instead of StandardError.
+
+
+.. exception:: IOError
+
+   Raised when an I/O operation (such as a :keyword:`print` statement, the built-in
+   :func:`open` function or a method of a file object) fails for an I/O-related
+   reason, e.g., "file not found" or "disk full".
+
+   .. % XXXJH xrefs here
+
+   This class is derived from :exc:`EnvironmentError`.  See the discussion above
+   for more information on exception instance attributes.
+
+
+.. exception:: ImportError
+
+   Raised when an :keyword:`import` statement fails to find the module definition
+   or when a ``from ... import`` fails to find a name that is to be imported.
+
+   .. % XXXJH xref to import statement?
+
+
+.. exception:: IndexError
+
+   Raised when a sequence subscript is out of range.  (Slice indices are silently
+   truncated to fall in the allowed range; if an index is not a plain integer,
+   :exc:`TypeError` is raised.)
+
+   .. % XXXJH xref to sequences
+
+
+.. exception:: KeyError
+
+   Raised when a mapping (dictionary) key is not found in the set of existing keys.
+
+   .. % XXXJH xref to mapping objects?
+
+
+.. exception:: KeyboardInterrupt
+
+   Raised when the user hits the interrupt key (normally :kbd:`Control-C` or
+   :kbd:`Delete`).  During execution, a check for interrupts is made regularly. The
+   exception inherits from :exc:`BaseException` so as to not be accidentally caught
+   by code that catches :exc:`Exception` and thus prevent the interpreter from
+   exiting.
+
+   .. % XXX(hylton) xrefs here
+
+   .. versionchanged:: 2.5
+      Changed to inherit from :exc:`BaseException`.
+
+
+.. exception:: MemoryError
+
+   Raised when an operation runs out of memory but the situation may still be
+   rescued (by deleting some objects).  The associated value is a string indicating
+   what kind of (internal) operation ran out of memory. Note that because of the
+   underlying memory management architecture (C's :cfunc:`malloc` function), the
+   interpreter may not always be able to completely recover from this situation; it
+   nevertheless raises an exception so that a stack traceback can be printed, in
+   case a run-away program was the cause.
+
+
+.. exception:: NameError
+
+   Raised when a local or global name is not found.  This applies only to
+   unqualified names.  The associated value is an error message that includes the
+   name that could not be found.
+
+
+.. exception:: NotImplementedError
+
+   This exception is derived from :exc:`RuntimeError`.  In user defined base
+   classes, abstract methods should raise this exception when they require derived
+   classes to override the method.
+
+   .. versionadded:: 1.5.2
+
+
+.. exception:: OSError
+
+   This class is derived from :exc:`EnvironmentError` and is used primarily as the
+   :mod:`os` module's ``os.error`` exception. See :exc:`EnvironmentError` above for
+   a description of the possible associated values.
+
+   .. % xref for os module
+
+   .. versionadded:: 1.5.2
+
+
+.. exception:: OverflowError
+
+   Raised when the result of an arithmetic operation is too large to be
+   represented.  This cannot occur for long integers (which would rather raise
+   :exc:`MemoryError` than give up).  Because of the lack of standardization of
+   floating point exception handling in C, most floating point operations also
+   aren't checked.  For plain integers, all operations that can overflow are
+   checked except left shift, where typical applications prefer to drop bits than
+   raise an exception.
+
+   .. % XXXJH reference to long's and/or int's?
+
+
+.. exception:: ReferenceError
+
+   This exception is raised when a weak reference proxy, created by the
+   :func:`weakref.proxy` function, is used to access an attribute of the referent
+   after it has been garbage collected. For more information on weak references,
+   see the :mod:`weakref` module.
+
+   .. versionadded:: 2.2
+      Previously known as the :exc:`weakref.ReferenceError` exception.
+
+
+.. exception:: RuntimeError
+
+   Raised when an error is detected that doesn't fall in any of the other
+   categories.  The associated value is a string indicating what precisely went
+   wrong.  (This exception is mostly a relic from a previous version of the
+   interpreter; it is not used very much any more.)
+
+
+.. exception:: StopIteration
+
+   Raised by builtin :func:`next` and an iterator's :meth:`__next__` method to
+   signal that there are no further values.
+
+   .. versionadded:: 2.2
+
+   .. versionchanged:: 3.0
+      Changed to inherit from Exception instead of StandardError.
+
+
+.. exception:: SyntaxError
+
+   Raised when the parser encounters a syntax error.  This may occur in an
+   :keyword:`import` statement, in a call to the built-in functions :func:`exec`
+   or :func:`eval`, or when reading the initial script or standard input
+   (also interactively).
+
+   .. % XXXJH xref to these functions?
+
+   Instances of this class have attributes :attr:`filename`, :attr:`lineno`,
+   :attr:`offset` and :attr:`text` for easier access to the details.  :func:`str`
+   of the exception instance returns only the message.
+
+
+.. exception:: SystemError
+
+   Raised when the interpreter finds an internal error, but the situation does not
+   look so serious to cause it to abandon all hope. The associated value is a
+   string indicating what went wrong (in low-level terms).
+
+   You should report this to the author or maintainer of your Python interpreter.
+   Be sure to report the version of the Python interpreter (``sys.version``; it is
+   also printed at the start of an interactive Python session), the exact error
+   message (the exception's associated value) and if possible the source of the
+   program that triggered the error.
+
+
+.. exception:: SystemExit
+
+   This exception is raised by the :func:`sys.exit` function.  When it is not
+   handled, the Python interpreter exits; no stack traceback is printed.  If the
+   associated value is a plain integer, it specifies the system exit status (passed
+   to C's :cfunc:`exit` function); if it is ``None``, the exit status is zero; if
+   it has another type (such as a string), the object's value is printed and the
+   exit status is one.
+
+   .. % XXX(hylton) xref to module sys?
+
+   Instances have an attribute :attr:`code` which is set to the proposed exit
+   status or error message (defaulting to ``None``). Also, this exception derives
+   directly from :exc:`BaseException` and not :exc:`Exception`, since it is not
+   technically an error.
+
+   A call to :func:`sys.exit` is translated into an exception so that clean-up
+   handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be
+   executed, and so that a debugger can execute a script without running the risk
+   of losing control.  The :func:`os._exit` function can be used if it is
+   absolutely positively necessary to exit immediately (for example, in the child
+   process after a call to :func:`fork`).
+
+   The exception inherits from :exc:`BaseException` instead of :exc:`Exception` so
+   that it is not accidentally caught by code that catches :exc:`Exception`.  This
+   allows the exception to properly propagate up and cause the interpreter to exit.
+
+   .. versionchanged:: 2.5
+      Changed to inherit from :exc:`BaseException`.
+
+
+.. exception:: TypeError
+
+   Raised when an operation or function is applied to an object of inappropriate
+   type.  The associated value is a string giving details about the type mismatch.
+
+
+.. exception:: UnboundLocalError
+
+   Raised when a reference is made to a local variable in a function or method, but
+   no value has been bound to that variable.  This is a subclass of
+   :exc:`NameError`.
+
+   .. versionadded:: 2.0
+
+
+.. exception:: UnicodeError
+
+   Raised when a Unicode-related encoding or decoding error occurs.  It is a
+   subclass of :exc:`ValueError`.
+
+   .. versionadded:: 2.0
+
+
+.. exception:: UnicodeEncodeError
+
+   Raised when a Unicode-related error occurs during encoding.  It is a subclass of
+   :exc:`UnicodeError`.
+
+   .. versionadded:: 2.3
+
+
+.. exception:: UnicodeDecodeError
+
+   Raised when a Unicode-related error occurs during decoding.  It is a subclass of
+   :exc:`UnicodeError`.
+
+   .. versionadded:: 2.3
+
+
+.. exception:: UnicodeTranslateError
+
+   Raised when a Unicode-related error occurs during translating.  It is a subclass
+   of :exc:`UnicodeError`.
+
+   .. versionadded:: 2.3
+
+
+.. exception:: ValueError
+
+   Raised when a built-in operation or function receives an argument that has the
+   right type but an inappropriate value, and the situation is not described by a
+   more precise exception such as :exc:`IndexError`.
+
+
+.. exception:: WindowsError
+
+   Raised when a Windows-specific error occurs or when the error number does not
+   correspond to an :cdata:`errno` value.  The :attr:`winerror` and
+   :attr:`strerror` values are created from the return values of the
+   :cfunc:`GetLastError` and :cfunc:`FormatMessage` functions from the Windows
+   Platform API. The :attr:`errno` value maps the :attr:`winerror` value to
+   corresponding ``errno.h`` values. This is a subclass of :exc:`OSError`.
+
+   .. versionadded:: 2.0
+
+   .. versionchanged:: 2.5
+      Previous versions put the :cfunc:`GetLastError` codes into :attr:`errno`.
+
+
+.. exception:: ZeroDivisionError
+
+   Raised when the second argument of a division or modulo operation is zero.  The
+   associated value is a string indicating the type of the operands and the
+   operation.
+
+The following exceptions are used as warning categories; see the :mod:`warnings`
+module for more information.
+
+
+.. exception:: Warning
+
+   Base class for warning categories.
+
+
+.. exception:: UserWarning
+
+   Base class for warnings generated by user code.
+
+
+.. exception:: DeprecationWarning
+
+   Base class for warnings about deprecated features.
+
+
+.. exception:: PendingDeprecationWarning
+
+   Base class for warnings about features which will be deprecated in the future.
+
+
+.. exception:: SyntaxWarning
+
+   Base class for warnings about dubious syntax
+
+
+.. exception:: RuntimeWarning
+
+   Base class for warnings about dubious runtime behavior.
+
+
+.. exception:: FutureWarning
+
+   Base class for warnings about constructs that will change semantically in the
+   future.
+
+
+.. exception:: ImportWarning
+
+   Base class for warnings about probable mistakes in module imports.
+
+   .. versionadded:: 2.5
+
+
+.. exception:: UnicodeWarning
+
+   Base class for warnings related to Unicode.
+
+   .. versionadded:: 2.5
+
+The class hierarchy for built-in exceptions is:
+
+
+.. literalinclude:: ../../Lib/test/exception_hierarchy.txt

Doc/library/fcntl.rst

@@ -0,0 +1,155 @@
+
+:mod:`fcntl` --- The :func:`fcntl` and :func:`ioctl` system calls
+=================================================================
+
+.. module:: fcntl
+   :platform: Unix
+   :synopsis: The fcntl() and ioctl() system calls.
+.. sectionauthor:: Jaap Vermeulen
+
+
+.. index::
+   pair: UNIX@Unix; file control
+   pair: UNIX@Unix; I/O control
+
+This module performs file control and I/O control on file descriptors. It is an
+interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.
+
+All functions in this module take a file descriptor *fd* as their first
+argument.  This can be an integer file descriptor, such as returned by
+``sys.stdin.fileno()``, or a file object, such as ``sys.stdin`` itself, which
+provides a :meth:`fileno` which returns a genuine file descriptor.
+
+The module defines the following functions:
+
+
+.. function:: fcntl(fd, op[, arg])
+
+   Perform the requested operation on file descriptor *fd* (file objects providing
+   a :meth:`fileno` method are accepted as well). The operation is defined by *op*
+   and is operating system dependent.  These codes are also found in the
+   :mod:`fcntl` module. The argument *arg* is optional, and defaults to the integer
+   value ``0``.  When present, it can either be an integer value, or a string.
+   With the argument missing or an integer value, the return value of this function
+   is the integer return value of the C :cfunc:`fcntl` call.  When the argument is
+   a string it represents a binary structure, e.g. created by :func:`struct.pack`.
+   The binary data is copied to a buffer whose address is passed to the C
+   :cfunc:`fcntl` call.  The return value after a successful call is the contents
+   of the buffer, converted to a string object.  The length of the returned string
+   will be the same as the length of the *arg* argument.  This is limited to 1024
+   bytes.  If the information returned in the buffer by the operating system is
+   larger than 1024 bytes, this is most likely to result in a segmentation
+   violation or a more subtle data corruption.
+
+   If the :cfunc:`fcntl` fails, an :exc:`IOError` is raised.
+
+
+.. function:: ioctl(fd, op[, arg[, mutate_flag]])
+
+   This function is identical to the :func:`fcntl` function, except that the
+   operations are typically defined in the library module :mod:`termios` and the
+   argument handling is even more complicated.
+
+   The parameter *arg* can be one of an integer, absent (treated identically to the
+   integer ``0``), an object supporting the read-only buffer interface (most likely
+   a plain Python string) or an object supporting the read-write buffer interface.
+
+   In all but the last case, behaviour is as for the :func:`fcntl` function.
+
+   If a mutable buffer is passed, then the behaviour is determined by the value of
+   the *mutate_flag* parameter.
+
+   If it is false, the buffer's mutability is ignored and behaviour is as for a
+   read-only buffer, except that the 1024 byte limit mentioned above is avoided --
+   so long as the buffer you pass is as least as long as what the operating system
+   wants to put there, things should work.
+
+   If *mutate_flag* is true, then the buffer is (in effect) passed to the
+   underlying :func:`ioctl` system call, the latter's return code is passed back to
+   the calling Python, and the buffer's new contents reflect the action of the
+   :func:`ioctl`.  This is a slight simplification, because if the supplied buffer
+   is less than 1024 bytes long it is first copied into a static buffer 1024 bytes
+   long which is then passed to :func:`ioctl` and copied back into the supplied
+   buffer.
+
+   If *mutate_flag* is not supplied, then from Python 2.5 it defaults to true,
+   which is a change from versions 2.3 and 2.4. Supply the argument explicitly if
+   version portability is a priority.
+
+   An example::
+
+      >>> import array, fcntl, struct, termios, os
+      >>> os.getpgrp()
+      13341
+      >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, "  "))[0]
+      13341
+      >>> buf = array.array('h', [0])
+      >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
+      0
+      >>> buf
+      array('h', [13341])
+
+
+.. function:: flock(fd, op)
+
+   Perform the lock operation *op* on file descriptor *fd* (file objects providing
+   a :meth:`fileno` method are accepted as well). See the Unix manual
+   :manpage:`flock(3)` for details.  (On some systems, this function is emulated
+   using :cfunc:`fcntl`.)
+
+
+.. function:: lockf(fd, operation, [length, [start, [whence]]])
+
+   This is essentially a wrapper around the :func:`fcntl` locking calls.  *fd* is
+   the file descriptor of the file to lock or unlock, and *operation* is one of the
+   following values:
+
+   * :const:`LOCK_UN` -- unlock
+   * :const:`LOCK_SH` -- acquire a shared lock
+   * :const:`LOCK_EX` -- acquire an exclusive lock
+
+   When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be
+   bit-wise OR'd with :const:`LOCK_NB` to avoid blocking on lock acquisition.
+   If :const:`LOCK_NB` is used and the lock cannot be acquired, an
+   :exc:`IOError` will be raised and the exception will have an *errno*
+   attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the
+   operating system; for portability, check for both values).  On at least some
+   systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a
+   file opened for writing.
+
+   *length* is the number of bytes to lock, *start* is the byte offset at which the
+   lock starts, relative to *whence*, and *whence* is as with :func:`fileobj.seek`,
+   specifically:
+
+   * :const:`0` -- relative to the start of the file (:const:`SEEK_SET`)
+   * :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`)
+   * :const:`2` -- relative to the end of the file (:const:`SEEK_END`)
+
+   The default for *start* is 0, which means to start at the beginning of the file.
+   The default for *length* is 0 which means to lock to the end of the file.  The
+   default for *whence* is also 0.
+
+Examples (all on a SVR4 compliant system)::
+
+   import struct, fcntl, os
+
+   f = open(...)
+   rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
+
+   lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
+   rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
+
+Note that in the first example the return value variable *rv* will hold an
+integer value; in the second example it will hold a string value.  The structure
+lay-out for the *lockdata* variable is system dependent --- therefore using the
+:func:`flock` call may be better.
+
+
+.. seealso::
+
+   Module :mod:`os`
+      If the locking flags :const:`O_SHLOCK` and :const:`O_EXLOCK` are present
+      in the :mod:`os` module, the :func:`os.open` function provides a more
+      platform-independent alternative to the :func:`lockf` and :func:`flock`
+      functions.
+

Doc/library/filecmp.rst

@@ -0,0 +1,152 @@
+
+:mod:`filecmp` --- File and Directory Comparisons
+=================================================
+
+.. module:: filecmp
+   :synopsis: Compare files efficiently.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+The :mod:`filecmp` module defines functions to compare files and directories,
+with various optional time/correctness trade-offs.
+
+The :mod:`filecmp` module defines the following functions:
+
+
+.. function:: cmp(f1, f2[, shallow])
+
+   Compare the files named *f1* and *f2*, returning ``True`` if they seem equal,
+   ``False`` otherwise.
+
+   Unless *shallow* is given and is false, files with identical :func:`os.stat`
+   signatures are taken to be equal.
+
+   Files that were compared using this function will not be compared again unless
+   their :func:`os.stat` signature changes.
+
+   Note that no external programs are called from this function, giving it
+   portability and efficiency.
+
+
+.. function:: cmpfiles(dir1, dir2, common[, shallow])
+
+   Returns three lists of file names: *match*, *mismatch*, *errors*.  *match*
+   contains the list of files match in both directories, *mismatch* includes the
+   names of those that don't, and *errros* lists the names of files which could not
+   be compared.  Files may be listed in *errors* because the user may lack
+   permission to read them or many other reasons, but always that the comparison
+   could not be done for some reason.
+
+   The *common* parameter is a list of file names found in both directories. The
+   *shallow* parameter has the same meaning and default value as for
+   :func:`filecmp.cmp`.
+
+Example::
+
+   >>> import filecmp
+   >>> filecmp.cmp('undoc.rst', 'undoc.rst')
+   True
+   >>> filecmp.cmp('undoc.rst', 'index.rst')
+   False
+
+
+.. _dircmp-objects:
+
+The :class:`dircmp` class
+-------------------------
+
+:class:`dircmp` instances are built using this constructor:
+
+
+.. class:: dircmp(a, b[, ignore[, hide]])
+
+   Construct a new directory comparison object, to compare the directories *a* and
+   *b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS',
+   'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir,
+   os.pardir]``.
+
+The :class:`dircmp` class provides the following methods:
+
+
+.. method:: dircmp.report()
+
+   Print (to ``sys.stdout``) a comparison between *a* and *b*.
+
+
+.. method:: dircmp.report_partial_closure()
+
+   Print a comparison between *a* and *b* and common immediate subdirectories.
+
+
+.. method:: dircmp.report_full_closure()
+
+   Print a comparison between *a* and *b* and common  subdirectories (recursively).
+
+The :class:`dircmp` offers a number of interesting attributes that may be used
+to get various bits of information about the directory trees being compared.
+
+Note that via :meth:`__getattr__` hooks, all attributes are computed lazily, so
+there is no speed penalty if only those attributes which are lightweight to
+compute are used.
+
+
+.. attribute:: dircmp.left_list
+
+   Files and subdirectories in *a*, filtered by *hide* and *ignore*.
+
+
+.. attribute:: dircmp.right_list
+
+   Files and subdirectories in *b*, filtered by *hide* and *ignore*.
+
+
+.. attribute:: dircmp.common
+
+   Files and subdirectories in both *a* and *b*.
+
+
+.. attribute:: dircmp.left_only
+
+   Files and subdirectories only in *a*.
+
+
+.. attribute:: dircmp.right_only
+
+   Files and subdirectories only in *b*.
+
+
+.. attribute:: dircmp.common_dirs
+
+   Subdirectories in both *a* and *b*.
+
+
+.. attribute:: dircmp.common_files
+
+   Files in both *a* and *b*
+
+
+.. attribute:: dircmp.common_funny
+
+   Names in both *a* and *b*, such that the type differs between the directories,
+   or names for which :func:`os.stat` reports an error.
+
+
+.. attribute:: dircmp.same_files
+
+   Files which are identical in both *a* and *b*.
+
+
+.. attribute:: dircmp.diff_files
+
+   Files which are in both *a* and *b*, whose contents differ.
+
+
+.. attribute:: dircmp.funny_files
+
+   Files which are in both *a* and *b*, but could not be compared.
+
+
+.. attribute:: dircmp.subdirs
+
+   A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.
+

Doc/library/fileformats.rst

@@ -0,0 +1,18 @@
+
+.. _fileformats:
+
+************
+File Formats
+************
+
+The modules described in this chapter parse various miscellaneous file formats
+that aren't markup languages or are related to e-mail.
+
+
+.. toctree::
+
+   csv.rst
+   configparser.rst
+   robotparser.rst
+   netrc.rst
+   xdrlib.rst

Doc/library/fileinput.rst

@@ -0,0 +1,183 @@
+:mod:`fileinput` --- Iterate over lines from multiple input streams
+===================================================================
+
+.. module:: fileinput
+   :synopsis: Loop over standard input or a list of files.
+.. moduleauthor:: Guido van Rossum <guido@python.org>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+This module implements a helper class and functions to quickly write a loop over
+standard input or a list of files.
+
+The typical use is::
+
+   import fileinput
+   for line in fileinput.input():
+       process(line)
+
+This iterates over the lines of all files listed in ``sys.argv[1:]``, defaulting
+to ``sys.stdin`` if the list is empty.  If a filename is ``'-'``, it is also
+replaced by ``sys.stdin``.  To specify an alternative list of filenames, pass it
+as the first argument to :func:`input`.  A single file name is also allowed.
+
+All files are opened in text mode by default, but you can override this by
+specifying the *mode* parameter in the call to :func:`input` or
+:class:`FileInput()`.  If an I/O error occurs during opening or reading a file,
+:exc:`IOError` is raised.
+
+If ``sys.stdin`` is used more than once, the second and further use will return
+no lines, except perhaps for interactive use, or if it has been explicitly reset
+(e.g. using ``sys.stdin.seek(0)``).
+
+Empty files are opened and immediately closed; the only time their presence in
+the list of filenames is noticeable at all is when the last file opened is
+empty.
+
+Lines are returned with any newlines intact, which means that the last line in
+a file may not have one.
+
+You can control how files are opened by providing an opening hook via the
+*openhook* parameter to :func:`fileinput.input` or :class:`FileInput()`. The
+hook must be a function that takes two arguments, *filename* and *mode*, and
+returns an accordingly opened file-like object. Two useful hooks are already
+provided by this module.
+
+The following function is the primary interface of this module:
+
+
+.. function:: input([files[, inplace[, backup[, mode[, openhook]]]]])
+
+   Create an instance of the :class:`FileInput` class.  The instance will be used
+   as global state for the functions of this module, and is also returned to use
+   during iteration.  The parameters to this function will be passed along to the
+   constructor of the :class:`FileInput` class.
+
+   .. versionchanged:: 2.5
+      Added the *mode* and *openhook* parameters.
+
+The following functions use the global state created by :func:`fileinput.input`;
+if there is no active state, :exc:`RuntimeError` is raised.
+
+
+.. function:: filename()
+
+   Return the name of the file currently being read.  Before the first line has
+   been read, returns ``None``.
+
+
+.. function:: fileno()
+
+   Return the integer "file descriptor" for the current file. When no file is
+   opened (before the first line and between files), returns ``-1``.
+
+   .. versionadded:: 2.5
+
+
+.. function:: lineno()
+
+   Return the cumulative line number of the line that has just been read.  Before
+   the first line has been read, returns ``0``.  After the last line of the last
+   file has been read, returns the line number of that line.
+
+
+.. function:: filelineno()
+
+   Return the line number in the current file.  Before the first line has been
+   read, returns ``0``.  After the last line of the last file has been read,
+   returns the line number of that line within the file.
+
+
+.. function:: isfirstline()
+
+   Returns true if the line just read is the first line of its file, otherwise
+   returns false.
+
+
+.. function:: isstdin()
+
+   Returns true if the last line was read from ``sys.stdin``, otherwise returns
+   false.
+
+
+.. function:: nextfile()
+
+   Close the current file so that the next iteration will read the first line from
+   the next file (if any); lines not read from the file will not count towards the
+   cumulative line count.  The filename is not changed until after the first line
+   of the next file has been read.  Before the first line has been read, this
+   function has no effect; it cannot be used to skip the first file.  After the
+   last line of the last file has been read, this function has no effect.
+
+
+.. function:: close()
+
+   Close the sequence.
+
+The class which implements the sequence behavior provided by the module is
+available for subclassing as well:
+
+
+.. class:: FileInput([files[, inplace[, backup[, mode[, openhook]]]]])
+
+   Class :class:`FileInput` is the implementation; its methods :meth:`filename`,
+   :meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:`isfirstline`,
+   :meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the functions
+   of the same name in the module. In addition it has a :meth:`readline` method
+   which returns the next input line, and a :meth:`__getitem__` method which
+   implements the sequence behavior.  The sequence must be accessed in strictly
+   sequential order; random access and :meth:`readline` cannot be mixed.
+
+   With *mode* you can specify which file mode will be passed to :func:`open`. It
+   must be one of ``'r'``, ``'rU'``, ``'U'`` and ``'rb'``.
+
+   The *openhook*, when given, must be a function that takes two arguments,
+   *filename* and *mode*, and returns an accordingly opened file-like object. You
+   cannot use *inplace* and *openhook* together.
+
+   .. versionchanged:: 2.5
+      Added the *mode* and *openhook* parameters.
+
+**Optional in-place filtering:** if the keyword argument ``inplace=1`` is passed
+to :func:`fileinput.input` or to the :class:`FileInput` constructor, the file is
+moved to a backup file and standard output is directed to the input file (if a
+file of the same name as the backup file already exists, it will be replaced
+silently).  This makes it possible to write a filter that rewrites its input
+file in place.  If the *backup* parameter is given (typically as
+``backup='.<some extension>'``), it specifies the extension for the backup file,
+and the backup file remains around; by default, the extension is ``'.bak'`` and
+it is deleted when the output file is closed.  In-place filtering is disabled
+when standard input is read.
+
+**Caveat:** The current implementation does not work for MS-DOS 8+3 filesystems.
+
+The two following opening hooks are provided by this module:
+
+
+.. function:: hook_compressed(filename, mode)
+
+   Transparently opens files compressed with gzip and bzip2 (recognized by the
+   extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2`
+   modules.  If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file is
+   opened normally (ie, using :func:`open` without any decompression).
+
+   Usage example:  ``fi = fileinput.FileInput(openhook=fileinput.hook_compressed)``
+
+   .. versionadded:: 2.5
+
+
+.. function:: hook_encoded(encoding)
+
+   Returns a hook which opens each file with :func:`codecs.open`, using the given
+   *encoding* to read the file.
+
+   Usage example: ``fi =
+   fileinput.FileInput(openhook=fileinput.hook_encoded("iso-8859-1"))``
+
+   .. note::
+
+      With this hook, :class:`FileInput` might return Unicode strings depending on the
+      specified *encoding*.
+
+   .. versionadded:: 2.5
+

Doc/library/filesys.rst

@@ -0,0 +1,38 @@
+
+.. _filesys:
+
+*************************
+File and Directory Access
+*************************
+
+The modules described in this chapter deal with disk files and directories.  For
+example, there are modules for reading the properties of files, manipulating
+paths in a portable way, and creating temporary files.  The full list of modules
+in this chapter is:
+
+
+.. toctree::
+
+   os.path.rst
+   fileinput.rst
+   stat.rst
+   statvfs.rst
+   filecmp.rst
+   tempfile.rst
+   glob.rst
+   fnmatch.rst
+   linecache.rst
+   shutil.rst
+   dircache.rst
+   macpath.rst
+
+
+.. seealso::
+
+   Section :ref:`bltin-file-objects`
+      A description of Python's built-in file objects.
+
+   Module :mod:`os`
+      Operating system interfaces, including functions to work with files at a lower
+      level than the built-in file object.
+

Doc/library/fnmatch.rst

@@ -0,0 +1,91 @@
+
+:mod:`fnmatch` --- Unix filename pattern matching
+=================================================
+
+.. module:: fnmatch
+   :synopsis: Unix shell style filename pattern matching.
+
+
+.. index:: single: filenames; wildcard expansion
+
+.. index:: module: re
+
+This module provides support for Unix shell-style wildcards, which are *not* the
+same as regular expressions (which are documented in the :mod:`re` module).  The
+special characters used in shell-style wildcards are:
+
++------------+------------------------------------+
+| Pattern    | Meaning                            |
++============+====================================+
+| ``*``      | matches everything                 |
++------------+------------------------------------+
+| ``?``      | matches any single character       |
++------------+------------------------------------+
+| ``[seq]``  | matches any character in *seq*     |
++------------+------------------------------------+
+| ``[!seq]`` | matches any character not in *seq* |
++------------+------------------------------------+
+
+.. index:: module: glob
+
+Note that the filename separator (``'/'`` on Unix) is *not* special to this
+module.  See module :mod:`glob` for pathname expansion (:mod:`glob` uses
+:func:`fnmatch` to match pathname segments).  Similarly, filenames starting with
+a period are not special for this module, and are matched by the ``*`` and ``?``
+patterns.
+
+
+.. function:: fnmatch(filename, pattern)
+
+   Test whether the *filename* string matches the *pattern* string, returning true
+   or false.  If the operating system is case-insensitive, then both parameters
+   will be normalized to all lower- or upper-case before the comparison is
+   performed.  If you require a case-sensitive comparison regardless of whether
+   that's standard for your operating system, use :func:`fnmatchcase` instead.
+
+   This example will print all file names in the current directory with the
+   extension ``.txt``::
+
+      import fnmatch
+      import os
+
+      for file in os.listdir('.'):
+          if fnmatch.fnmatch(file, '*.txt'):
+              print file
+
+
+.. function:: fnmatchcase(filename, pattern)
+
+   Test whether *filename* matches *pattern*, returning true or false; the
+   comparison is case-sensitive.
+
+
+.. function:: filter(names, pattern)
+
+   Return the subset of the list of *names* that match *pattern*. It is the same as
+   ``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
+
+   .. versionadded:: 2.2
+
+
+.. function:: translate(pattern)
+
+   Return the shell-style *pattern* converted to a regular expression.
+
+   Example::
+
+      >>> import fnmatch, re
+      >>>
+      >>> regex = fnmatch.translate('*.txt')
+      >>> regex
+      '.*\\.txt$'
+      >>> reobj = re.compile(regex)
+      >>> print reobj.match('foobar.txt')
+      <_sre.SRE_Match object at 0x...>
+
+
+.. seealso::
+
+   Module :mod:`glob`
+      Unix shell-style path expansion.
+

Doc/library/formatter.rst

@@ -0,0 +1,350 @@
+
+:mod:`formatter` --- Generic output formatting
+==============================================
+
+.. module:: formatter
+   :synopsis: Generic output formatter and device interface.
+
+
+.. index:: single: HTMLParser (class in htmllib)
+
+This module supports two interface definitions, each with multiple
+implementations.  The *formatter* interface is used by the :class:`HTMLParser`
+class of the :mod:`htmllib` module, and the *writer* interface is required by
+the formatter interface.
+
+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.
+
+
+.. _formatter-interface:
+
+The Formatter Interface
+-----------------------
+
+Interfaces to create formatters are dependent on the specific formatter class
+being instantiated.  The interfaces described below are the required interfaces
+which all formatters must support once initialized.
+
+One data element is defined at the module level:
+
+
+.. data:: AS_IS
+
+   Value which can be used in the font specification passed to the ``push_font()``
+   method described below, or as the new value to any other ``push_property()``
+   method.  Pushing the ``AS_IS`` value allows the corresponding ``pop_property()``
+   method to be called without having to track whether the property was changed.
+
+The following attributes are defined for formatter instance objects:
+
+
+.. attribute:: formatter.writer
+
+   The writer instance with which the formatter interacts.
+
+
+.. method:: formatter.end_paragraph(blanklines)
+
+   Close any open paragraphs and insert at least *blanklines* before the next
+   paragraph.
+
+
+.. method:: formatter.add_line_break()
+
+   Add a hard line break if one does not already exist.  This does not break the
+   logical paragraph.
+
+
+.. method:: formatter.add_hor_rule(*args, **kw)
+
+   Insert a horizontal rule in the output.  A hard break is inserted if there is
+   data in the current paragraph, but the logical paragraph is not broken.  The
+   arguments and keywords are passed on to the writer's :meth:`send_line_break`
+   method.
+
+
+.. method:: formatter.add_flowing_data(data)
+
+   Provide data which should be formatted with collapsed whitespace. Whitespace
+   from preceding and successive calls to :meth:`add_flowing_data` is considered as
+   well when the whitespace collapse is performed.  The data which is passed to
+   this method is expected to be word-wrapped by the output device.  Note that any
+   word-wrapping still must be performed by the writer object due to the need to
+   rely on device and font information.
+
+
+.. method:: formatter.add_literal_data(data)
+
+   Provide data which should be passed to the writer unchanged. Whitespace,
+   including newline and tab characters, are considered legal in the value of
+   *data*.
+
+
+.. method:: formatter.add_label_data(format, counter)
+
+   Insert a label which should be placed to the left of the current left margin.
+   This should be used for constructing bulleted or numbered lists.  If the
+   *format* value is a string, it is interpreted as a format specification for
+   *counter*, which should be an integer. The result of this formatting becomes the
+   value of the label; if *format* is not a string it is used as the label value
+   directly. The label value is passed as the only argument to the writer's
+   :meth:`send_label_data` method.  Interpretation of non-string label values is
+   dependent on the associated writer.
+
+   Format specifications are strings which, in combination with a counter value,
+   are used to compute label values.  Each character in the format string is copied
+   to the label value, with some characters recognized to indicate a transform on
+   the counter value.  Specifically, the character ``'1'`` represents the counter
+   value formatter as an Arabic number, the characters ``'A'`` and ``'a'``
+   represent alphabetic representations of the counter value in upper and lower
+   case, respectively, and ``'I'`` and ``'i'`` represent the counter value in Roman
+   numerals, in upper and lower case.  Note that the alphabetic and roman
+   transforms require that the counter value be greater than zero.
+
+
+.. method:: formatter.flush_softspace()
+
+   Send any pending whitespace buffered from a previous call to
+   :meth:`add_flowing_data` to the associated writer object.  This should be called
+   before any direct manipulation of the writer object.
+
+
+.. method:: formatter.push_alignment(align)
+
+   Push a new alignment setting onto the alignment stack.  This may be
+   :const:`AS_IS` if no change is desired.  If the alignment value is changed from
+   the previous setting, the writer's :meth:`new_alignment` method is called with
+   the *align* value.
+
+
+.. method:: formatter.pop_alignment()
+
+   Restore the previous alignment.
+
+
+.. method:: formatter.push_font((size, italic, bold, teletype))
+
+   Change some or all font properties of the writer object.  Properties which are
+   not set to :const:`AS_IS` are set to the values passed in while others are
+   maintained at their current settings.  The writer's :meth:`new_font` method is
+   called with the fully resolved font specification.
+
+
+.. method:: formatter.pop_font()
+
+   Restore the previous font.
+
+
+.. method:: formatter.push_margin(margin)
+
+   Increase the number of left margin indentations by one, associating the logical
+   tag *margin* with the new indentation.  The initial margin level is ``0``.
+   Changed values of the logical tag must be true values; false values other than
+   :const:`AS_IS` are not sufficient to change the margin.
+
+
+.. method:: formatter.pop_margin()
+
+   Restore the previous margin.
+
+
+.. method:: formatter.push_style(*styles)
+
+   Push any number of arbitrary style specifications.  All styles are pushed onto
+   the styles stack in order.  A tuple representing the entire stack, including
+   :const:`AS_IS` values, is passed to the writer's :meth:`new_styles` method.
+
+
+.. method:: formatter.pop_style([n=1])
+
+   Pop the last *n* style specifications passed to :meth:`push_style`.  A tuple
+   representing the revised stack, including :const:`AS_IS` values, is passed to
+   the writer's :meth:`new_styles` method.
+
+
+.. method:: formatter.set_spacing(spacing)
+
+   Set the spacing style for the writer.
+
+
+.. method:: formatter.assert_line_data([flag=1])
+
+   Inform the formatter that data has been added to the current paragraph
+   out-of-band.  This should be used when the writer has been manipulated
+   directly.  The optional *flag* argument can be set to false if the writer
+   manipulations produced a hard line break at the end of the output.
+
+
+.. _formatter-impls:
+
+Formatter Implementations
+-------------------------
+
+Two implementations of formatter objects are provided by this module. Most
+applications may use one of these classes without modification or subclassing.
+
+
+.. class:: NullFormatter([writer])
+
+   A formatter which does nothing.  If *writer* is omitted, a :class:`NullWriter`
+   instance is created.  No methods of the writer are called by
+   :class:`NullFormatter` instances.  Implementations should inherit from this
+   class if implementing a writer interface but don't need to inherit any
+   implementation.
+
+
+.. class:: AbstractFormatter(writer)
+
+   The standard formatter.  This implementation has demonstrated wide applicability
+   to many writers, and may be used directly in most circumstances.  It has been
+   used to implement a full-featured World Wide Web browser.
+
+
+.. _writer-interface:
+
+The Writer Interface
+--------------------
+
+Interfaces to create writers are dependent on the specific writer class being
+instantiated.  The interfaces described below are the required interfaces which
+all writers must support once initialized. Note that while most applications can
+use the :class:`AbstractFormatter` class as a formatter, the writer must
+typically be provided by the application.
+
+
+.. method:: writer.flush()
+
+   Flush any buffered output or device control events.
+
+
+.. method:: writer.new_alignment(align)
+
+   Set the alignment style.  The *align* value can be any object, but by convention
+   is a string or ``None``, where ``None`` indicates that the writer's "preferred"
+   alignment should be used. Conventional *align* values are ``'left'``,
+   ``'center'``, ``'right'``, and ``'justify'``.
+
+
+.. method:: writer.new_font(font)
+
+   Set the font style.  The value of *font* will be ``None``, indicating that the
+   device's default font should be used, or a tuple of the form ``(``*size*,
+   *italic*, *bold*, *teletype*``)``.  Size will be a string indicating the size of
+   font that should be used; specific strings and their interpretation must be
+   defined by the application.  The *italic*, *bold*, and *teletype* values are
+   Boolean values specifying which of those font attributes should be used.
+
+
+.. method:: writer.new_margin(margin, level)
+
+   Set the margin level to the integer *level* and the logical tag to *margin*.
+   Interpretation of the logical tag is at the writer's discretion; the only
+   restriction on the value of the logical tag is that it not be a false value for
+   non-zero values of *level*.
+
+
+.. method:: writer.new_spacing(spacing)
+
+   Set the spacing style to *spacing*.
+
+
+.. method:: writer.new_styles(styles)
+
+   Set additional styles.  The *styles* value is a tuple of arbitrary values; the
+   value :const:`AS_IS` should be ignored.  The *styles* tuple may be interpreted
+   either as a set or as a stack depending on the requirements of the application
+   and writer implementation.
+
+
+.. method:: writer.send_line_break()
+
+   Break the current line.
+
+
+.. method:: writer.send_paragraph(blankline)
+
+   Produce a paragraph separation of at least *blankline* blank lines, or the
+   equivalent.  The *blankline* value will be an integer.  Note that the
+   implementation will receive a call to :meth:`send_line_break` before this call
+   if a line break is needed;  this method should not include ending the last line
+   of the paragraph. It is only responsible for vertical spacing between
+   paragraphs.
+
+
+.. method:: writer.send_hor_rule(*args, **kw)
+
+   Display a horizontal rule on the output device.  The arguments to this method
+   are entirely application- and writer-specific, and should be interpreted with
+   care.  The method implementation may assume that a line break has already been
+   issued via :meth:`send_line_break`.
+
+
+.. method:: writer.send_flowing_data(data)
+
+   Output character data which may be word-wrapped and re-flowed as needed.  Within
+   any sequence of calls to this method, the writer may assume that spans of
+   multiple whitespace characters have been collapsed to single space characters.
+
+
+.. method:: writer.send_literal_data(data)
+
+   Output character data which has already been formatted for display.  Generally,
+   this should be interpreted to mean that line breaks indicated by newline
+   characters should be preserved and no new line breaks should be introduced.  The
+   data may contain embedded newline and tab characters, unlike data provided to
+   the :meth:`send_formatted_data` interface.
+
+
+.. method:: writer.send_label_data(data)
+
+   Set *data* to the left of the current left margin, if possible. The value of
+   *data* is not restricted; treatment of non-string values is entirely
+   application- and writer-dependent.  This method will only be called at the
+   beginning of a line.
+
+
+.. _writer-impls:
+
+Writer Implementations
+----------------------
+
+Three implementations of the writer object interface are provided as examples by
+this module.  Most applications will need to derive new writer classes from the
+:class:`NullWriter` class.
+
+
+.. class:: NullWriter()
+
+   A writer which only provides the interface definition; no actions are taken on
+   any methods.  This should be the base class for all writers which do not need to
+   inherit any implementation methods.
+
+
+.. class:: AbstractWriter()
+
+   A writer which can be used in debugging formatters, but not much else.  Each
+   method simply announces itself by printing its name and arguments on standard
+   output.
+
+
+.. class:: DumbWriter([file[, maxcol=72]])
+
+   Simple writer class which writes output on the file object passed in as *file*
+   or, if *file* is omitted, on standard output.  The output is simply word-wrapped
+   to the number of columns specified by *maxcol*.  This class is suitable for
+   reflowing a sequence of paragraphs.
+

Doc/library/fpectl.rst

@@ -0,0 +1,120 @@
+
+:mod:`fpectl` --- Floating point exception control
+==================================================
+
+.. module:: fpectl
+   :platform: Unix
+   :synopsis: Provide control for floating point exception handling.
+.. moduleauthor:: Lee Busby <busby1@llnl.gov>
+.. sectionauthor:: Lee Busby <busby1@llnl.gov>
+
+
+.. note::
+
+   The :mod:`fpectl` module is not built by default, and its usage is discouraged
+   and may be dangerous except in the hands of experts.  See also the section
+   :ref:`fpectl-limitations` on limitations for more details.
+
+.. index:: single: IEEE-754
+
+Most computers carry out floating point operations in conformance with the
+so-called IEEE-754 standard. On any real computer, some floating point
+operations produce results that cannot be expressed as a normal floating point
+value. For example, try ::
+
+   >>> import math
+   >>> math.exp(1000)
+   inf
+   >>> math.exp(1000) / math.exp(1000)
+   nan
+
+(The example above will work on many platforms. DEC Alpha may be one exception.)
+"Inf" is a special, non-numeric value in IEEE-754 that stands for "infinity",
+and "nan" means "not a number." Note that, other than the non-numeric results,
+nothing special happened when you asked Python to carry out those calculations.
+That is in fact the default behaviour prescribed in the IEEE-754 standard, and
+if it works for you, stop reading now.
+
+In some circumstances, it would be better to raise an exception and stop
+processing at the point where the faulty operation was attempted. The
+:mod:`fpectl` module is for use in that situation. It provides control over
+floating point units from several hardware manufacturers, allowing the user to
+turn on the generation of :const:`SIGFPE` whenever any of the IEEE-754
+exceptions Division by Zero, Overflow, or Invalid Operation occurs. In tandem
+with a pair of wrapper macros that are inserted into the C code comprising your
+python system, :const:`SIGFPE` is trapped and converted into the Python
+:exc:`FloatingPointError` exception.
+
+The :mod:`fpectl` module defines the following functions and may raise the given
+exception:
+
+
+.. function:: turnon_sigfpe()
+
+   Turn on the generation of :const:`SIGFPE`, and set up an appropriate signal
+   handler.
+
+
+.. function:: turnoff_sigfpe()
+
+   Reset default handling of floating point exceptions.
+
+
+.. exception:: FloatingPointError
+
+   After :func:`turnon_sigfpe` has been executed, a floating point operation that
+   raises one of the IEEE-754 exceptions Division by Zero, Overflow, or Invalid
+   operation will in turn raise this standard Python exception.
+
+
+.. _fpectl-example:
+
+Example
+-------
+
+The following example demonstrates how to start up and test operation of the
+:mod:`fpectl` module. ::
+
+   >>> import fpectl
+   >>> import fpetest
+   >>> fpectl.turnon_sigfpe()
+   >>> fpetest.test()
+   overflow        PASS
+   FloatingPointError: Overflow
+
+   div by 0        PASS
+   FloatingPointError: Division by zero
+     [ more output from test elided ]
+   >>> import math
+   >>> math.exp(1000)
+   Traceback (most recent call last):
+     File "<stdin>", line 1, in ?
+   FloatingPointError: in math_1
+
+
+.. _fpectl-limitations:
+
+Limitations and other considerations
+------------------------------------
+
+Setting up a given processor to trap IEEE-754 floating point errors currently
+requires custom code on a per-architecture basis. You may have to modify
+:mod:`fpectl` to control your particular hardware.
+
+Conversion of an IEEE-754 exception to a Python exception requires that the
+wrapper macros ``PyFPE_START_PROTECT`` and ``PyFPE_END_PROTECT`` be inserted
+into your code in an appropriate fashion.  Python itself has been modified to
+support the :mod:`fpectl` module, but many other codes of interest to numerical
+analysts have not.
+
+The :mod:`fpectl` module is not thread-safe.
+
+
+.. seealso::
+
+   Some files in the source distribution may be interesting in learning more about
+   how this module operates. The include file :file:`Include/pyfpe.h` discusses the
+   implementation of this module at some length. :file:`Modules/fpetestmodule.c`
+   gives several examples of use. Many additional examples can be found in
+   :file:`Objects/floatobject.c`.
+

Doc/library/fpformat.rst

@@ -0,0 +1,56 @@
+
+:mod:`fpformat` --- Floating point conversions
+==============================================
+
+.. module:: fpformat
+   :synopsis: General floating point formatting functions.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+The :mod:`fpformat` module defines functions for dealing with floating point
+numbers representations in 100% pure Python.
+
+.. note::
+
+   This module is unneeded: everything here could be done via the ``%`` string
+   interpolation operator.
+
+The :mod:`fpformat` module defines the following functions and an exception:
+
+
+.. function:: fix(x, digs)
+
+   Format *x* as ``[-]ddd.ddd`` with *digs* digits after the point and at least one
+   digit before. If ``digs <= 0``, the decimal point is suppressed.
+
+   *x* can be either a number or a string that looks like one. *digs* is an
+   integer.
+
+   Return value is a string.
+
+
+.. function:: sci(x, digs)
+
+   Format *x* as ``[-]d.dddE[+-]ddd`` with *digs* digits after the  point and
+   exactly one digit before. If ``digs <= 0``, one digit is kept and the point is
+   suppressed.
+
+   *x* can be either a real number, or a string that looks like one. *digs* is an
+   integer.
+
+   Return value is a string.
+
+
+.. exception:: NotANumber
+
+   Exception raised when a string passed to :func:`fix` or :func:`sci` as the *x*
+   parameter does not look like a number. This is a subclass of :exc:`ValueError`
+   when the standard exceptions are strings.  The exception value is the improperly
+   formatted string that caused the exception to be raised.
+
+Example::
+
+   >>> import fpformat
+   >>> fpformat.fix(1.23, 1)
+   '1.2'
+

Doc/library/framework.rst

@@ -0,0 +1,335 @@
+
+:mod:`FrameWork` --- Interactive application framework
+======================================================
+
+.. module:: FrameWork
+   :platform: Mac
+   :synopsis: Interactive application framework.
+
+
+The :mod:`FrameWork` module contains classes that together provide a framework
+for an interactive Macintosh application. The programmer builds an application
+by creating subclasses that override various methods of the bases classes,
+thereby implementing the functionality wanted. Overriding functionality can
+often be done on various different levels, i.e. to handle clicks in a single
+dialog window in a non-standard way it is not necessary to override the complete
+event handling.
+
+Work on the :mod:`FrameWork` has pretty much stopped, now that :mod:`PyObjC` is
+available for full Cocoa access from Python, and the documentation describes
+only the most important functionality, and not in the most logical manner at
+that. Examine the source or the examples for more details.  The following are
+some comments posted on the MacPython newsgroup about the strengths and
+limitations of :mod:`FrameWork`:
+
+
+.. epigraph::
+
+   The strong point of :mod:`FrameWork` is that it allows you to break into the
+   control-flow at many different places. :mod:`W`, for instance, uses a different
+   way to enable/disable menus and that plugs right in leaving the rest intact.
+   The weak points of :mod:`FrameWork` are that it has no abstract command
+   interface (but that shouldn't be difficult), that its dialog support is minimal
+   and that its control/toolbar support is non-existent.
+
+The :mod:`FrameWork` module defines the following functions:
+
+
+.. function:: Application()
+
+   An object representing the complete application. See below for a description of
+   the methods. The default :meth:`__init__` routine creates an empty window
+   dictionary and a menu bar with an apple menu.
+
+
+.. function:: MenuBar()
+
+   An object representing the menubar. This object is usually not created by the
+   user.
+
+
+.. function:: Menu(bar, title[, after])
+
+   An object representing a menu. Upon creation you pass the ``MenuBar`` the menu
+   appears in, the *title* string and a position (1-based) *after* where the menu
+   should appear (default: at the end).
+
+
+.. function:: MenuItem(menu, title[, shortcut, callback])
+
+   Create a menu item object. The arguments are the menu to create, the item title
+   string and optionally the keyboard shortcut and a callback routine. The callback
+   is called with the arguments menu-id, item number within menu (1-based), current
+   front window and the event record.
+
+   Instead of a callable object the callback can also be a string. In this case
+   menu selection causes the lookup of a method in the topmost window and the
+   application. The method name is the callback string with ``'domenu_'``
+   prepended.
+
+   Calling the ``MenuBar`` :meth:`fixmenudimstate` method sets the correct dimming
+   for all menu items based on the current front window.
+
+
+.. function:: Separator(menu)
+
+   Add a separator to the end of a menu.
+
+
+.. function:: SubMenu(menu, label)
+
+   Create a submenu named *label* under menu *menu*. The menu object is returned.
+
+
+.. function:: Window(parent)
+
+   Creates a (modeless) window. *Parent* is the application object to which the
+   window belongs. The window is not displayed until later.
+
+
+.. function:: DialogWindow(parent)
+
+   Creates a modeless dialog window.
+
+
+.. function:: windowbounds(width, height)
+
+   Return a ``(left, top, right, bottom)`` tuple suitable for creation of a window
+   of given width and height. The window will be staggered with respect to previous
+   windows, and an attempt is made to keep the whole window on-screen. However, the
+   window will however always be the exact size given, so parts may be offscreen.
+
+
+.. function:: setwatchcursor()
+
+   Set the mouse cursor to a watch.
+
+
+.. function:: setarrowcursor()
+
+   Set the mouse cursor to an arrow.
+
+
+.. _application-objects:
+
+Application Objects
+-------------------
+
+Application objects have the following methods, among others:
+
+
+.. method:: Application.makeusermenus()
+
+   Override this method if you need menus in your application. Append the menus to
+   the attribute :attr:`menubar`.
+
+
+.. method:: Application.getabouttext()
+
+   Override this method to return a text string describing your application.
+   Alternatively, override the :meth:`do_about` method for more elaborate "about"
+   messages.
+
+
+.. method:: Application.mainloop([mask[, wait]])
+
+   This routine is the main event loop, call it to set your application rolling.
+   *Mask* is the mask of events you want to handle, *wait* is the number of ticks
+   you want to leave to other concurrent application (default 0, which is probably
+   not a good idea). While raising *self* to exit the mainloop is still supported
+   it is not recommended: call ``self._quit()`` instead.
+
+   The event loop is split into many small parts, each of which can be overridden.
+   The default methods take care of dispatching events to windows and dialogs,
+   handling drags and resizes, Apple Events, events for non-FrameWork windows, etc.
+
+   In general, all event handlers should return ``1`` if the event is fully handled
+   and ``0`` otherwise (because the front window was not a FrameWork window, for
+   instance). This is needed so that update events and such can be passed on to
+   other windows like the Sioux console window. Calling :func:`MacOS.HandleEvent`
+   is not allowed within *our_dispatch* or its callees, since this may result in an
+   infinite loop if the code is called through the Python inner-loop event handler.
+
+
+.. method:: Application.asyncevents(onoff)
+
+   Call this method with a nonzero parameter to enable asynchronous event handling.
+   This will tell the inner interpreter loop to call the application event handler
+   *async_dispatch* whenever events are available. This will cause FrameWork window
+   updates and the user interface to remain working during long computations, but
+   will slow the interpreter down and may cause surprising results in non-reentrant
+   code (such as FrameWork itself). By default *async_dispatch* will immediately
+   call *our_dispatch* but you may override this to handle only certain events
+   asynchronously. Events you do not handle will be passed to Sioux and such.
+
+   The old on/off value is returned.
+
+
+.. method:: Application._quit()
+
+   Terminate the running :meth:`mainloop` call at the next convenient moment.
+
+
+.. method:: Application.do_char(c, event)
+
+   The user typed character *c*. The complete details of the event can be found in
+   the *event* structure. This method can also be provided in a ``Window`` object,
+   which overrides the application-wide handler if the window is frontmost.
+
+
+.. method:: Application.do_dialogevent(event)
+
+   Called early in the event loop to handle modeless dialog events. The default
+   method simply dispatches the event to the relevant dialog (not through the
+   ``DialogWindow`` object involved). Override if you need special handling of
+   dialog events (keyboard shortcuts, etc).
+
+
+.. method:: Application.idle(event)
+
+   Called by the main event loop when no events are available. The null-event is
+   passed (so you can look at mouse position, etc).
+
+
+.. _window-objects:
+
+Window Objects
+--------------
+
+Window objects have the following methods, among others:
+
+
+.. method:: Window.open()
+
+   Override this method to open a window. Store the MacOS window-id in
+   :attr:`self.wid` and call the :meth:`do_postopen` method to register the window
+   with the parent application.
+
+
+.. method:: Window.close()
+
+   Override this method to do any special processing on window close. Call the
+   :meth:`do_postclose` method to cleanup the parent state.
+
+
+.. method:: Window.do_postresize(width, height, macoswindowid)
+
+   Called after the window is resized. Override if more needs to be done than
+   calling ``InvalRect``.
+
+
+.. method:: Window.do_contentclick(local, modifiers, event)
+
+   The user clicked in the content part of a window. The arguments are the
+   coordinates (window-relative), the key modifiers and the raw event.
+
+
+.. method:: Window.do_update(macoswindowid, event)
+
+   An update event for the window was received. Redraw the window.
+
+
+.. method:: Window.do_activate(activate, event)
+
+   The window was activated (``activate == 1``) or deactivated (``activate == 0``).
+   Handle things like focus highlighting, etc.
+
+
+.. _controlswindow-object:
+
+ControlsWindow Object
+---------------------
+
+ControlsWindow objects have the following methods besides those of ``Window``
+objects:
+
+
+.. method:: ControlsWindow.do_controlhit(window, control, pcode, event)
+
+   Part *pcode* of control *control* was hit by the user. Tracking and such has
+   already been taken care of.
+
+
+.. _scrolledwindow-object:
+
+ScrolledWindow Object
+---------------------
+
+ScrolledWindow objects are ControlsWindow objects with the following extra
+methods:
+
+
+.. method:: ScrolledWindow.scrollbars([wantx[, wanty]])
+
+   Create (or destroy) horizontal and vertical scrollbars. The arguments specify
+   which you want (default: both). The scrollbars always have minimum ``0`` and
+   maximum ``32767``.
+
+
+.. method:: ScrolledWindow.getscrollbarvalues()
+
+   You must supply this method. It should return a tuple ``(x, y)`` giving the
+   current position of the scrollbars (between ``0`` and ``32767``). You can return
+   ``None`` for either to indicate the whole document is visible in that direction.
+
+
+.. method:: ScrolledWindow.updatescrollbars()
+
+   Call this method when the document has changed. It will call
+   :meth:`getscrollbarvalues` and update the scrollbars.
+
+
+.. method:: ScrolledWindow.scrollbar_callback(which, what, value)
+
+   Supplied by you and called after user interaction. *which* will be ``'x'`` or
+   ``'y'``, *what* will be ``'-'``, ``'--'``, ``'set'``, ``'++'`` or ``'+'``. For
+   ``'set'``, *value* will contain the new scrollbar position.
+
+
+.. method:: ScrolledWindow.scalebarvalues(absmin, absmax, curmin, curmax)
+
+   Auxiliary method to help you calculate values to return from
+   :meth:`getscrollbarvalues`. You pass document minimum and maximum value and
+   topmost (leftmost) and bottommost (rightmost) visible values and it returns the
+   correct number or ``None``.
+
+
+.. method:: ScrolledWindow.do_activate(onoff, event)
+
+   Takes care of dimming/highlighting scrollbars when a window becomes frontmost.
+   If you override this method, call this one at the end of your method.
+
+
+.. method:: ScrolledWindow.do_postresize(width, height, window)
+
+   Moves scrollbars to the correct position. Call this method initially if you
+   override it.
+
+
+.. method:: ScrolledWindow.do_controlhit(window, control, pcode, event)
+
+   Handles scrollbar interaction. If you override it call this method first, a
+   nonzero return value indicates the hit was in the scrollbars and has been
+   handled.
+
+
+.. _dialogwindow-objects:
+
+DialogWindow Objects
+--------------------
+
+DialogWindow objects have the following methods besides those of ``Window``
+objects:
+
+
+.. method:: DialogWindow.open(resid)
+
+   Create the dialog window, from the DLOG resource with id *resid*. The dialog
+   object is stored in :attr:`self.wid`.
+
+
+.. method:: DialogWindow.do_itemhit(item, event)
+
+   Item number *item* was hit. You are responsible for redrawing toggle buttons,
+   etc.
+

Doc/library/frameworks.rst

@@ -0,0 +1,18 @@
+
+.. _frameworks:
+
+******************
+Program Frameworks
+******************
+
+The modules described in this chapter are frameworks that will largely dictate
+the structure of your program.  Currently the modules described  here are all
+oriented toward writing command-line interfaces.
+
+The full list of modules described in this chapter is:
+
+
+.. toctree::
+
+   cmd.rst
+   shlex.rst

Doc/library/ftplib.rst

@@ -0,0 +1,320 @@
+
+:mod:`ftplib` --- FTP protocol client
+=====================================
+
+.. module:: ftplib
+   :synopsis: FTP protocol client (requires sockets).
+
+
+.. index::
+   pair: FTP; protocol
+   single: FTP; ftplib (standard module)
+
+This module defines the class :class:`FTP` and a few related items. The
+:class:`FTP` class implements the client side of the FTP protocol.  You can use
+this to write Python programs that perform a variety of automated FTP jobs, such
+as mirroring other ftp servers.  It is also used by the module :mod:`urllib` to
+handle URLs that use FTP.  For more information on FTP (File Transfer Protocol),
+see Internet :rfc:`959`.
+
+Here's a sample session using the :mod:`ftplib` module::
+
+   >>> from ftplib import FTP
+   >>> ftp = FTP('ftp.cwi.nl')   # connect to host, default port
+   >>> ftp.login()               # user anonymous, passwd anonymous@
+   >>> ftp.retrlines('LIST')     # list directory contents
+   total 24418
+   drwxrwsr-x   5 ftp-usr  pdmaint     1536 Mar 20 09:48 .
+   dr-xr-srwt 105 ftp-usr  pdmaint     1536 Mar 21 14:32 ..
+   -rw-r--r--   1 ftp-usr  pdmaint     5305 Mar 20 09:48 INDEX
+    .
+    .
+    .
+   >>> ftp.retrbinary('RETR README', open('README', 'wb').write)
+   '226 Transfer complete.'
+   >>> ftp.quit()
+
+The module defines the following items:
+
+
+.. class:: FTP([host[, user[, passwd[, acct[, timeout]]]]])
+
+   Return a new instance of the :class:`FTP` class.  When *host* is given, the
+   method call ``connect(host)`` is made.  When *user* is given, additionally the
+   method call ``login(user, passwd, acct)`` is made (where *passwd* and *acct*
+   default to the empty string when not given). The optional *timeout* parameter
+   specifies a timeout in seconds for the connection attempt (if is not specified,
+   or passed as None, the global default timeout setting will be used).
+
+   .. versionchanged:: 2.6
+      *timeout* was added.
+
+
+.. data:: all_errors
+
+   The set of all exceptions (as a tuple) that methods of :class:`FTP` instances
+   may raise as a result of problems with the FTP connection (as opposed to
+   programming errors made by the caller).  This set includes the four exceptions
+   listed below as well as :exc:`socket.error` and :exc:`IOError`.
+
+
+.. exception:: error_reply
+
+   Exception raised when an unexpected reply is received from the server.
+
+
+.. exception:: error_temp
+
+   Exception raised when an error code in the range 400--499 is received.
+
+
+.. exception:: error_perm
+
+   Exception raised when an error code in the range 500--599 is received.
+
+
+.. exception:: error_proto
+
+   Exception raised when a reply is received from the server that does not begin
+   with a digit in the range 1--5.
+
+
+.. seealso::
+
+   Module :mod:`netrc`
+      Parser for the :file:`.netrc` file format.  The file :file:`.netrc` is typically
+      used by FTP clients to load user authentication information before prompting the
+      user.
+
+   .. index:: single: ftpmirror.py
+
+   The file :file:`Tools/scripts/ftpmirror.py` in the Python source distribution is
+   a script that can mirror FTP sites, or portions thereof, using the :mod:`ftplib`
+   module. It can be used as an extended example that applies this module.
+
+
+.. _ftp-objects:
+
+FTP Objects
+-----------
+
+Several methods are available in two flavors: one for handling text files and
+another for binary files.  These are named for the command which is used
+followed by ``lines`` for the text version or ``binary`` for the binary version.
+
+:class:`FTP` instances have the following methods:
+
+
+.. method:: FTP.set_debuglevel(level)
+
+   Set the instance's debugging level.  This controls the amount of debugging
+   output printed.  The default, ``0``, produces no debugging output.  A value of
+   ``1`` produces a moderate amount of debugging output, generally a single line
+   per request.  A value of ``2`` or higher produces the maximum amount of
+   debugging output, logging each line sent and received on the control connection.
+
+
+.. method:: FTP.connect(host[, port[, timeout]])
+
+   Connect to the given host and port.  The default port number is ``21``, as
+   specified by the FTP protocol specification.  It is rarely needed to specify a
+   different port number.  This function should be called only once for each
+   instance; it should not be called at all if a host was given when the instance
+   was created.  All other methods can only be used after a connection has been
+   made.
+
+   The optional *timeout* parameter specifies a timeout in seconds for the
+   connection attempt. If is not specified, or passed as None, the  object timeout
+   is used (the timeout that you passed when instantiating the class); if the
+   object timeout is also None, the global default timeout  setting will be used.
+
+   .. versionchanged:: 2.6
+      *timeout* was added.
+
+
+.. method:: FTP.getwelcome()
+
+   Return the welcome message sent by the server in reply to the initial
+   connection.  (This message sometimes contains disclaimers or help information
+   that may be relevant to the user.)
+
+
+.. method:: FTP.login([user[, passwd[, acct]]])
+
+   Log in as the given *user*.  The *passwd* and *acct* parameters are optional and
+   default to the empty string.  If no *user* is specified, it defaults to
+   ``'anonymous'``.  If *user* is ``'anonymous'``, the default *passwd* is
+   ``'anonymous@'``.  This function should be called only once for each instance,
+   after a connection has been established; it should not be called at all if a
+   host and user were given when the instance was created.  Most FTP commands are
+   only allowed after the client has logged in.
+
+
+.. method:: FTP.abort()
+
+   Abort a file transfer that is in progress.  Using this does not always work, but
+   it's worth a try.
+
+
+.. method:: FTP.sendcmd(command)
+
+   Send a simple command string to the server and return the response string.
+
+
+.. method:: FTP.voidcmd(command)
+
+   Send a simple command string to the server and handle the response. Return
+   nothing if a response code in the range 200--299 is received. Raise an exception
+   otherwise.
+
+
+.. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
+
+   Retrieve a file in binary transfer mode.  *command* should be an appropriate
+   ``RETR`` command: ``'RETR filename'``. The *callback* function is called for
+   each block of data received, with a single string argument giving the data
+   block. The optional *maxblocksize* argument specifies the maximum chunk size to
+   read on the low-level socket object created to do the actual transfer (which
+   will also be the largest size of the data blocks passed to *callback*).  A
+   reasonable default is chosen. *rest* means the same thing as in the
+   :meth:`transfercmd` method.
+
+
+.. method:: FTP.retrlines(command[, callback])
+
+   Retrieve a file or directory listing in ASCII transfer mode. *command* should be
+   an appropriate ``RETR`` command (see :meth:`retrbinary`) or a ``LIST`` command
+   (usually just the string ``'LIST'``).  The *callback* function is called for
+   each line, with the trailing CRLF stripped.  The default *callback* prints the
+   line to ``sys.stdout``.
+
+
+.. method:: FTP.set_pasv(boolean)
+
+   Enable "passive" mode if *boolean* is true, other disable passive mode.  (In
+   Python 2.0 and before, passive mode was off by default; in Python 2.1 and later,
+   it is on by default.)
+
+
+.. method:: FTP.storbinary(command, file[, blocksize])
+
+   Store a file in binary transfer mode.  *command* should be an appropriate
+   ``STOR`` command: ``"STOR filename"``. *file* is an open file object which is
+   read until EOF using its :meth:`read` method in blocks of size *blocksize* to
+   provide the data to be stored.  The *blocksize* argument defaults to 8192.
+
+   .. versionchanged:: 2.1
+      default for *blocksize* added.
+
+
+.. method:: FTP.storlines(command, file)
+
+   Store a file in ASCII transfer mode.  *command* should be an appropriate
+   ``STOR`` command (see :meth:`storbinary`).  Lines are read until EOF from the
+   open file object *file* using its :meth:`readline` method to provide the data to
+   be stored.
+
+
+.. method:: FTP.transfercmd(cmd[, rest])
+
+   Initiate a transfer over the data connection.  If the transfer is active, send a
+   ``EPRT`` or  ``PORT`` command and the transfer command specified by *cmd*, and
+   accept the connection.  If the server is passive, send a ``EPSV`` or ``PASV``
+   command, connect to it, and start the transfer command.  Either way, return the
+   socket for the connection.
+
+   If optional *rest* is given, a ``REST`` command is sent to the server, passing
+   *rest* as an argument.  *rest* is usually a byte offset into the requested file,
+   telling the server to restart sending the file's bytes at the requested offset,
+   skipping over the initial bytes.  Note however that RFC 959 requires only that
+   *rest* be a string containing characters in the printable range from ASCII code
+   33 to ASCII code 126.  The :meth:`transfercmd` method, therefore, converts
+   *rest* to a string, but no check is performed on the string's contents.  If the
+   server does not recognize the ``REST`` command, an :exc:`error_reply` exception
+   will be raised.  If this happens, simply call :meth:`transfercmd` without a
+   *rest* argument.
+
+
+.. method:: FTP.ntransfercmd(cmd[, rest])
+
+   Like :meth:`transfercmd`, but returns a tuple of the data connection and the
+   expected size of the data.  If the expected size could not be computed, ``None``
+   will be returned as the expected size.  *cmd* and *rest* means the same thing as
+   in :meth:`transfercmd`.
+
+
+.. method:: FTP.nlst(argument[, ...])
+
+   Return a list of files as returned by the ``NLST`` command.  The optional
+   *argument* is a directory to list (default is the current server directory).
+   Multiple arguments can be used to pass non-standard options to the ``NLST``
+   command.
+
+
+.. method:: FTP.dir(argument[, ...])
+
+   Produce a directory listing as returned by the ``LIST`` command, printing it to
+   standard output.  The optional *argument* is a directory to list (default is the
+   current server directory).  Multiple arguments can be used to pass non-standard
+   options to the ``LIST`` command.  If the last argument is a function, it is used
+   as a *callback* function as for :meth:`retrlines`; the default prints to
+   ``sys.stdout``.  This method returns ``None``.
+
+
+.. method:: FTP.rename(fromname, toname)
+
+   Rename file *fromname* on the server to *toname*.
+
+
+.. method:: FTP.delete(filename)
+
+   Remove the file named *filename* from the server.  If successful, returns the
+   text of the response, otherwise raises :exc:`error_perm` on permission errors or
+   :exc:`error_reply` on other errors.
+
+
+.. method:: FTP.cwd(pathname)
+
+   Set the current directory on the server.
+
+
+.. method:: FTP.mkd(pathname)
+
+   Create a new directory on the server.
+
+
+.. method:: FTP.pwd()
+
+   Return the pathname of the current directory on the server.
+
+
+.. method:: FTP.rmd(dirname)
+
+   Remove the directory named *dirname* on the server.
+
+
+.. method:: FTP.size(filename)
+
+   Request the size of the file named *filename* on the server.  On success, the
+   size of the file is returned as an integer, otherwise ``None`` is returned.
+   Note that the ``SIZE`` command is not  standardized, but is supported by many
+   common server implementations.
+
+
+.. method:: FTP.quit()
+
+   Send a ``QUIT`` command to the server and close the connection. This is the
+   "polite" way to close a connection, but it may raise an exception of the server
+   reponds with an error to the ``QUIT`` command.  This implies a call to the
+   :meth:`close` method which renders the :class:`FTP` instance useless for
+   subsequent calls (see below).
+
+
+.. method:: FTP.close()
+
+   Close the connection unilaterally.  This should not be applied to an already
+   closed connection such as after a successful call to :meth:`quit`.  After this
+   call the :class:`FTP` instance should not be used any more (after a call to
+   :meth:`close` or :meth:`quit` you cannot reopen the connection by issuing
+   another :meth:`login` method).
+