Move the 3k reST doc tree in place.

1 files changed, 143 insertions, 0 deletions

diff --git a/Doc/library/xml.sax.rst b/Doc/library/xml.sax.rst
new file mode 100644
index 0000000000..43d17c2aed
--- /dev/null
+++ b/Doc/library/xml.sax.rst
@@ -0,0 +1,143 @@
+
+:mod:`xml.sax` --- Support for SAX2 parsers
+===========================================
+
+.. module:: xml.sax
+   :synopsis: Package containing SAX2 base classes and convenience functions.
+.. moduleauthor:: Lars Marius Garshol <larsga@garshol.priv.no>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
+
+
+.. versionadded:: 2.0
+
+The :mod:`xml.sax` package provides a number of modules which implement the
+Simple API for XML (SAX) interface for Python.  The package itself provides the
+SAX exceptions and the convenience functions which will be most used by users of
+the SAX API.
+
+The convenience functions are:
+
+
+.. function:: make_parser([parser_list])
+
+   Create and return a SAX :class:`XMLReader` object.  The first parser found will
+   be used.  If *parser_list* is provided, it must be a sequence of strings which
+   name modules that have a function named :func:`create_parser`.  Modules listed
+   in *parser_list* will be used before modules in the default list of parsers.
+
+
+.. function:: parse(filename_or_stream, handler[, error_handler])
+
+   Create a SAX parser and use it to parse a document.  The document, passed in as
+   *filename_or_stream*, can be a filename or a file object.  The *handler*
+   parameter needs to be a SAX :class:`ContentHandler` instance.  If
+   *error_handler* is given, it must be a SAX :class:`ErrorHandler` instance; if
+   omitted,  :exc:`SAXParseException` will be raised on all errors.  There is no
+   return value; all work must be done by the *handler* passed in.
+
+
+.. function:: parseString(string, handler[, error_handler])
+
+   Similar to :func:`parse`, but parses from a buffer *string* received as a
+   parameter.
+
+A typical SAX application uses three kinds of objects: readers, handlers and
+input sources.  "Reader" in this context is another term for parser, i.e. some
+piece of code that reads the bytes or characters from the input source, and
+produces a sequence of events. The events then get distributed to the handler
+objects, i.e. the reader invokes a method on the handler.  A SAX application
+must therefore obtain a reader object, create or open the input sources, create
+the handlers, and connect these objects all together.  As the final step of
+preparation, the reader is called to parse the input. During parsing, methods on
+the handler objects are called based on structural and syntactic events from the
+input data.
+
+For these objects, only the interfaces are relevant; they are normally not
+instantiated by the application itself.  Since Python does not have an explicit
+notion of interface, they are formally introduced as classes, but applications
+may use implementations which do not inherit from the provided classes.  The
+:class:`InputSource`, :class:`Locator`, :class:`Attributes`,
+:class:`AttributesNS`, and :class:`XMLReader` interfaces are defined in the
+module :mod:`xml.sax.xmlreader`.  The handler interfaces are defined in
+:mod:`xml.sax.handler`.  For convenience, :class:`InputSource` (which is often
+instantiated directly) and the handler classes are also available from
+:mod:`xml.sax`.  These interfaces are described below.
+
+In addition to these classes, :mod:`xml.sax` provides the following exception
+classes.
+
+
+.. exception:: SAXException(msg[, exception])
+
+   Encapsulate an XML error or warning.  This class can contain basic error or
+   warning information from either the XML parser or the application: it can be
+   subclassed to provide additional functionality or to add localization.  Note
+   that although the handlers defined in the :class:`ErrorHandler` interface
+   receive instances of this exception, it is not required to actually raise the
+   exception --- it is also useful as a container for information.
+
+   When instantiated, *msg* should be a human-readable description of the error.
+   The optional *exception* parameter, if given, should be ``None`` or an exception
+   that was caught by the parsing code and is being passed along as information.
+
+   This is the base class for the other SAX exception classes.
+
+
+.. exception:: SAXParseException(msg, exception, locator)
+
+   Subclass of :exc:`SAXException` raised on parse errors. Instances of this class
+   are passed to the methods of the SAX :class:`ErrorHandler` interface to provide
+   information about the parse error.  This class supports the SAX :class:`Locator`
+   interface as well as the :class:`SAXException` interface.
+
+
+.. exception:: SAXNotRecognizedException(msg[, exception])
+
+   Subclass of :exc:`SAXException` raised when a SAX :class:`XMLReader` is
+   confronted with an unrecognized feature or property.  SAX applications and
+   extensions may use this class for similar purposes.
+
+
+.. exception:: SAXNotSupportedException(msg[, exception])
+
+   Subclass of :exc:`SAXException` raised when a SAX :class:`XMLReader` is asked to
+   enable a feature that is not supported, or to set a property to a value that the
+   implementation does not support.  SAX applications and extensions may use this
+   class for similar purposes.
+
+
+.. seealso::
+
+   `SAX: The Simple API for XML <http://www.saxproject.org/>`_
+      This site is the focal point for the definition of the SAX API.  It provides a
+      Java implementation and online documentation.  Links to implementations and
+      historical information are also available.
+
+   Module :mod:`xml.sax.handler`
+      Definitions of the interfaces for application-provided objects.
+
+   Module :mod:`xml.sax.saxutils`
+      Convenience functions for use in SAX applications.
+
+   Module :mod:`xml.sax.xmlreader`
+      Definitions of the interfaces for parser-provided objects.
+
+
+.. _sax-exception-objects:
+
+SAXException Objects
+--------------------
+
+The :class:`SAXException` exception class supports the following methods:
+
+
+.. method:: SAXException.getMessage()
+
+   Return a human-readable message describing the error condition.
+
+
+.. method:: SAXException.getException()
+
+   Return an encapsulated exception object, or ``None``.
+