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