Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`xml.sax` --- Support for SAX2 parsers |
| 2 | =========================================== |
| 3 | |
| 4 | .. module:: xml.sax |
| 5 | :synopsis: Package containing SAX2 base classes and convenience functions. |
| 6 | .. moduleauthor:: Lars Marius Garshol <larsga@garshol.priv.no> |
| 7 | .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| 8 | .. sectionauthor:: Martin v. Lรถwis <martin@v.loewis.de> |
| 9 | |
| 10 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | The :mod:`xml.sax` package provides a number of modules which implement the |
| 12 | Simple API for XML (SAX) interface for Python. The package itself provides the |
| 13 | SAX exceptions and the convenience functions which will be most used by users of |
| 14 | the SAX API. |
| 15 | |
Christian Heimes | 7380a67 | 2013-03-26 17:35:55 +0100 | [diff] [blame] | 16 | |
| 17 | .. warning:: |
| 18 | |
| 19 | The :mod:`xml.sax` module is not secure against maliciously |
| 20 | constructed data. If you need to parse untrusted or unauthenticated data see |
| 21 | :ref:`xml-vulnerabilities`. |
| 22 | |
| 23 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | The convenience functions are: |
| 25 | |
| 26 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 27 | .. function:: make_parser(parser_list=[]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | |
Serhiy Storchaka | 15e6590 | 2013-08-29 10:28:44 +0300 | [diff] [blame] | 29 | Create and return a SAX :class:`~xml.sax.xmlreader.XMLReader` object. The |
| 30 | first parser found will |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | be used. If *parser_list* is provided, it must be a sequence of strings which |
| 32 | name modules that have a function named :func:`create_parser`. Modules listed |
| 33 | in *parser_list* will be used before modules in the default list of parsers. |
| 34 | |
| 35 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 36 | .. function:: parse(filename_or_stream, handler, error_handler=handler.ErrorHandler()) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 37 | |
| 38 | Create a SAX parser and use it to parse a document. The document, passed in as |
| 39 | *filename_or_stream*, can be a filename or a file object. The *handler* |
Serhiy Storchaka | 15e6590 | 2013-08-29 10:28:44 +0300 | [diff] [blame] | 40 | parameter needs to be a SAX :class:`~handler.ContentHandler` instance. If |
| 41 | *error_handler* is given, it must be a SAX :class:`~handler.ErrorHandler` |
| 42 | instance; if |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | omitted, :exc:`SAXParseException` will be raised on all errors. There is no |
| 44 | return value; all work must be done by the *handler* passed in. |
| 45 | |
| 46 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 47 | .. function:: parseString(string, handler, error_handler=handler.ErrorHandler()) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | |
| 49 | Similar to :func:`parse`, but parses from a buffer *string* received as a |
| 50 | parameter. |
| 51 | |
| 52 | A typical SAX application uses three kinds of objects: readers, handlers and |
| 53 | input sources. "Reader" in this context is another term for parser, i.e. some |
| 54 | piece of code that reads the bytes or characters from the input source, and |
| 55 | produces a sequence of events. The events then get distributed to the handler |
| 56 | objects, i.e. the reader invokes a method on the handler. A SAX application |
| 57 | must therefore obtain a reader object, create or open the input sources, create |
| 58 | the handlers, and connect these objects all together. As the final step of |
| 59 | preparation, the reader is called to parse the input. During parsing, methods on |
| 60 | the handler objects are called based on structural and syntactic events from the |
| 61 | input data. |
| 62 | |
| 63 | For these objects, only the interfaces are relevant; they are normally not |
| 64 | instantiated by the application itself. Since Python does not have an explicit |
| 65 | notion of interface, they are formally introduced as classes, but applications |
| 66 | may use implementations which do not inherit from the provided classes. The |
Serhiy Storchaka | 15e6590 | 2013-08-29 10:28:44 +0300 | [diff] [blame] | 67 | :class:`~xml.sax.xmlreader.InputSource`, :class:`~xml.sax.xmlreader.Locator`, |
| 68 | :class:`~xml.sax.xmlreader.Attributes`, :class:`~xml.sax.xmlreader.AttributesNS`, |
| 69 | and :class:`~xml.sax.xmlreader.XMLReader` interfaces are defined in the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 70 | module :mod:`xml.sax.xmlreader`. The handler interfaces are defined in |
Serhiy Storchaka | 15e6590 | 2013-08-29 10:28:44 +0300 | [diff] [blame] | 71 | :mod:`xml.sax.handler`. For convenience, |
| 72 | :class:`~xml.sax.xmlreader.InputSource` (which is often |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | instantiated directly) and the handler classes are also available from |
| 74 | :mod:`xml.sax`. These interfaces are described below. |
| 75 | |
| 76 | In addition to these classes, :mod:`xml.sax` provides the following exception |
| 77 | classes. |
| 78 | |
| 79 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 80 | .. exception:: SAXException(msg, exception=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 81 | |
| 82 | Encapsulate an XML error or warning. This class can contain basic error or |
| 83 | warning information from either the XML parser or the application: it can be |
| 84 | subclassed to provide additional functionality or to add localization. Note |
Serhiy Storchaka | 15e6590 | 2013-08-29 10:28:44 +0300 | [diff] [blame] | 85 | that although the handlers defined in the |
| 86 | :class:`~xml.sax.handler.ErrorHandler` interface |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | receive instances of this exception, it is not required to actually raise the |
| 88 | exception --- it is also useful as a container for information. |
| 89 | |
| 90 | When instantiated, *msg* should be a human-readable description of the error. |
| 91 | The optional *exception* parameter, if given, should be ``None`` or an exception |
| 92 | that was caught by the parsing code and is being passed along as information. |
| 93 | |
| 94 | This is the base class for the other SAX exception classes. |
| 95 | |
| 96 | |
| 97 | .. exception:: SAXParseException(msg, exception, locator) |
| 98 | |
Serhiy Storchaka | 15e6590 | 2013-08-29 10:28:44 +0300 | [diff] [blame] | 99 | Subclass of :exc:`SAXException` raised on parse errors. Instances of this |
| 100 | class are passed to the methods of the SAX |
| 101 | :class:`~xml.sax.handler.ErrorHandler` interface to provide information |
| 102 | about the parse error. This class supports the SAX |
| 103 | :class:`~xml.sax.xmlreader.Locator` interface as well as the |
| 104 | :class:`SAXException` interface. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | |
| 106 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 107 | .. exception:: SAXNotRecognizedException(msg, exception=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 108 | |
Serhiy Storchaka | 15e6590 | 2013-08-29 10:28:44 +0300 | [diff] [blame] | 109 | Subclass of :exc:`SAXException` raised when a SAX |
| 110 | :class:`~xml.sax.xmlreader.XMLReader` is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 111 | confronted with an unrecognized feature or property. SAX applications and |
| 112 | extensions may use this class for similar purposes. |
| 113 | |
| 114 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 115 | .. exception:: SAXNotSupportedException(msg, exception=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
Serhiy Storchaka | 15e6590 | 2013-08-29 10:28:44 +0300 | [diff] [blame] | 117 | Subclass of :exc:`SAXException` raised when a SAX |
| 118 | :class:`~xml.sax.xmlreader.XMLReader` is asked to |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | enable a feature that is not supported, or to set a property to a value that the |
| 120 | implementation does not support. SAX applications and extensions may use this |
| 121 | class for similar purposes. |
| 122 | |
| 123 | |
| 124 | .. seealso:: |
| 125 | |
| 126 | `SAX: The Simple API for XML <http://www.saxproject.org/>`_ |
| 127 | This site is the focal point for the definition of the SAX API. It provides a |
| 128 | Java implementation and online documentation. Links to implementations and |
| 129 | historical information are also available. |
| 130 | |
| 131 | Module :mod:`xml.sax.handler` |
| 132 | Definitions of the interfaces for application-provided objects. |
| 133 | |
| 134 | Module :mod:`xml.sax.saxutils` |
| 135 | Convenience functions for use in SAX applications. |
| 136 | |
| 137 | Module :mod:`xml.sax.xmlreader` |
| 138 | Definitions of the interfaces for parser-provided objects. |
| 139 | |
| 140 | |
| 141 | .. _sax-exception-objects: |
| 142 | |
| 143 | SAXException Objects |
| 144 | -------------------- |
| 145 | |
| 146 | The :class:`SAXException` exception class supports the following methods: |
| 147 | |
| 148 | |
| 149 | .. method:: SAXException.getMessage() |
| 150 | |
| 151 | Return a human-readable message describing the error condition. |
| 152 | |
| 153 | |
| 154 | .. method:: SAXException.getException() |
| 155 | |
| 156 | Return an encapsulated exception object, or ``None``. |
| 157 | |