Debian Codegraph @

Doc/library/xml.sax.rst

raw
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