/Doc/library/xml.sax.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 143 lines · 94 code · 49 blank · 0 comment · 0 complexity · a74b89f7e1c1e769e98038d282c9939a MD5 · raw file
- :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``.