|
jpayne@69
|
1 """
|
|
jpayne@69
|
2 This module contains the core classes of version 2.0 of SAX for Python.
|
|
jpayne@69
|
3 This file provides only default classes with absolutely minimum
|
|
jpayne@69
|
4 functionality, from which drivers and applications can be subclassed.
|
|
jpayne@69
|
5
|
|
jpayne@69
|
6 Many of these classes are empty and are included only as documentation
|
|
jpayne@69
|
7 of the interfaces.
|
|
jpayne@69
|
8
|
|
jpayne@69
|
9 $Id$
|
|
jpayne@69
|
10 """
|
|
jpayne@69
|
11
|
|
jpayne@69
|
12 version = '2.0beta'
|
|
jpayne@69
|
13
|
|
jpayne@69
|
14 #============================================================================
|
|
jpayne@69
|
15 #
|
|
jpayne@69
|
16 # HANDLER INTERFACES
|
|
jpayne@69
|
17 #
|
|
jpayne@69
|
18 #============================================================================
|
|
jpayne@69
|
19
|
|
jpayne@69
|
20 # ===== ERRORHANDLER =====
|
|
jpayne@69
|
21
|
|
jpayne@69
|
22 class ErrorHandler:
|
|
jpayne@69
|
23 """Basic interface for SAX error handlers.
|
|
jpayne@69
|
24
|
|
jpayne@69
|
25 If you create an object that implements this interface, then
|
|
jpayne@69
|
26 register the object with your XMLReader, the parser will call the
|
|
jpayne@69
|
27 methods in your object to report all warnings and errors. There
|
|
jpayne@69
|
28 are three levels of errors available: warnings, (possibly)
|
|
jpayne@69
|
29 recoverable errors, and unrecoverable errors. All methods take a
|
|
jpayne@69
|
30 SAXParseException as the only parameter."""
|
|
jpayne@69
|
31
|
|
jpayne@69
|
32 def error(self, exception):
|
|
jpayne@69
|
33 "Handle a recoverable error."
|
|
jpayne@69
|
34 raise exception
|
|
jpayne@69
|
35
|
|
jpayne@69
|
36 def fatalError(self, exception):
|
|
jpayne@69
|
37 "Handle a non-recoverable error."
|
|
jpayne@69
|
38 raise exception
|
|
jpayne@69
|
39
|
|
jpayne@69
|
40 def warning(self, exception):
|
|
jpayne@69
|
41 "Handle a warning."
|
|
jpayne@69
|
42 print(exception)
|
|
jpayne@69
|
43
|
|
jpayne@69
|
44
|
|
jpayne@69
|
45 # ===== CONTENTHANDLER =====
|
|
jpayne@69
|
46
|
|
jpayne@69
|
47 class ContentHandler:
|
|
jpayne@69
|
48 """Interface for receiving logical document content events.
|
|
jpayne@69
|
49
|
|
jpayne@69
|
50 This is the main callback interface in SAX, and the one most
|
|
jpayne@69
|
51 important to applications. The order of events in this interface
|
|
jpayne@69
|
52 mirrors the order of the information in the document."""
|
|
jpayne@69
|
53
|
|
jpayne@69
|
54 def __init__(self):
|
|
jpayne@69
|
55 self._locator = None
|
|
jpayne@69
|
56
|
|
jpayne@69
|
57 def setDocumentLocator(self, locator):
|
|
jpayne@69
|
58 """Called by the parser to give the application a locator for
|
|
jpayne@69
|
59 locating the origin of document events.
|
|
jpayne@69
|
60
|
|
jpayne@69
|
61 SAX parsers are strongly encouraged (though not absolutely
|
|
jpayne@69
|
62 required) to supply a locator: if it does so, it must supply
|
|
jpayne@69
|
63 the locator to the application by invoking this method before
|
|
jpayne@69
|
64 invoking any of the other methods in the DocumentHandler
|
|
jpayne@69
|
65 interface.
|
|
jpayne@69
|
66
|
|
jpayne@69
|
67 The locator allows the application to determine the end
|
|
jpayne@69
|
68 position of any document-related event, even if the parser is
|
|
jpayne@69
|
69 not reporting an error. Typically, the application will use
|
|
jpayne@69
|
70 this information for reporting its own errors (such as
|
|
jpayne@69
|
71 character content that does not match an application's
|
|
jpayne@69
|
72 business rules). The information returned by the locator is
|
|
jpayne@69
|
73 probably not sufficient for use with a search engine.
|
|
jpayne@69
|
74
|
|
jpayne@69
|
75 Note that the locator will return correct information only
|
|
jpayne@69
|
76 during the invocation of the events in this interface. The
|
|
jpayne@69
|
77 application should not attempt to use it at any other time."""
|
|
jpayne@69
|
78 self._locator = locator
|
|
jpayne@69
|
79
|
|
jpayne@69
|
80 def startDocument(self):
|
|
jpayne@69
|
81 """Receive notification of the beginning of a document.
|
|
jpayne@69
|
82
|
|
jpayne@69
|
83 The SAX parser will invoke this method only once, before any
|
|
jpayne@69
|
84 other methods in this interface or in DTDHandler (except for
|
|
jpayne@69
|
85 setDocumentLocator)."""
|
|
jpayne@69
|
86
|
|
jpayne@69
|
87 def endDocument(self):
|
|
jpayne@69
|
88 """Receive notification of the end of a document.
|
|
jpayne@69
|
89
|
|
jpayne@69
|
90 The SAX parser will invoke this method only once, and it will
|
|
jpayne@69
|
91 be the last method invoked during the parse. The parser shall
|
|
jpayne@69
|
92 not invoke this method until it has either abandoned parsing
|
|
jpayne@69
|
93 (because of an unrecoverable error) or reached the end of
|
|
jpayne@69
|
94 input."""
|
|
jpayne@69
|
95
|
|
jpayne@69
|
96 def startPrefixMapping(self, prefix, uri):
|
|
jpayne@69
|
97 """Begin the scope of a prefix-URI Namespace mapping.
|
|
jpayne@69
|
98
|
|
jpayne@69
|
99 The information from this event is not necessary for normal
|
|
jpayne@69
|
100 Namespace processing: the SAX XML reader will automatically
|
|
jpayne@69
|
101 replace prefixes for element and attribute names when the
|
|
jpayne@69
|
102 http://xml.org/sax/features/namespaces feature is true (the
|
|
jpayne@69
|
103 default).
|
|
jpayne@69
|
104
|
|
jpayne@69
|
105 There are cases, however, when applications need to use
|
|
jpayne@69
|
106 prefixes in character data or in attribute values, where they
|
|
jpayne@69
|
107 cannot safely be expanded automatically; the
|
|
jpayne@69
|
108 start/endPrefixMapping event supplies the information to the
|
|
jpayne@69
|
109 application to expand prefixes in those contexts itself, if
|
|
jpayne@69
|
110 necessary.
|
|
jpayne@69
|
111
|
|
jpayne@69
|
112 Note that start/endPrefixMapping events are not guaranteed to
|
|
jpayne@69
|
113 be properly nested relative to each-other: all
|
|
jpayne@69
|
114 startPrefixMapping events will occur before the corresponding
|
|
jpayne@69
|
115 startElement event, and all endPrefixMapping events will occur
|
|
jpayne@69
|
116 after the corresponding endElement event, but their order is
|
|
jpayne@69
|
117 not guaranteed."""
|
|
jpayne@69
|
118
|
|
jpayne@69
|
119 def endPrefixMapping(self, prefix):
|
|
jpayne@69
|
120 """End the scope of a prefix-URI mapping.
|
|
jpayne@69
|
121
|
|
jpayne@69
|
122 See startPrefixMapping for details. This event will always
|
|
jpayne@69
|
123 occur after the corresponding endElement event, but the order
|
|
jpayne@69
|
124 of endPrefixMapping events is not otherwise guaranteed."""
|
|
jpayne@69
|
125
|
|
jpayne@69
|
126 def startElement(self, name, attrs):
|
|
jpayne@69
|
127 """Signals the start of an element in non-namespace mode.
|
|
jpayne@69
|
128
|
|
jpayne@69
|
129 The name parameter contains the raw XML 1.0 name of the
|
|
jpayne@69
|
130 element type as a string and the attrs parameter holds an
|
|
jpayne@69
|
131 instance of the Attributes class containing the attributes of
|
|
jpayne@69
|
132 the element."""
|
|
jpayne@69
|
133
|
|
jpayne@69
|
134 def endElement(self, name):
|
|
jpayne@69
|
135 """Signals the end of an element in non-namespace mode.
|
|
jpayne@69
|
136
|
|
jpayne@69
|
137 The name parameter contains the name of the element type, just
|
|
jpayne@69
|
138 as with the startElement event."""
|
|
jpayne@69
|
139
|
|
jpayne@69
|
140 def startElementNS(self, name, qname, attrs):
|
|
jpayne@69
|
141 """Signals the start of an element in namespace mode.
|
|
jpayne@69
|
142
|
|
jpayne@69
|
143 The name parameter contains the name of the element type as a
|
|
jpayne@69
|
144 (uri, localname) tuple, the qname parameter the raw XML 1.0
|
|
jpayne@69
|
145 name used in the source document, and the attrs parameter
|
|
jpayne@69
|
146 holds an instance of the Attributes class containing the
|
|
jpayne@69
|
147 attributes of the element.
|
|
jpayne@69
|
148
|
|
jpayne@69
|
149 The uri part of the name tuple is None for elements which have
|
|
jpayne@69
|
150 no namespace."""
|
|
jpayne@69
|
151
|
|
jpayne@69
|
152 def endElementNS(self, name, qname):
|
|
jpayne@69
|
153 """Signals the end of an element in namespace mode.
|
|
jpayne@69
|
154
|
|
jpayne@69
|
155 The name parameter contains the name of the element type, just
|
|
jpayne@69
|
156 as with the startElementNS event."""
|
|
jpayne@69
|
157
|
|
jpayne@69
|
158 def characters(self, content):
|
|
jpayne@69
|
159 """Receive notification of character data.
|
|
jpayne@69
|
160
|
|
jpayne@69
|
161 The Parser will call this method to report each chunk of
|
|
jpayne@69
|
162 character data. SAX parsers may return all contiguous
|
|
jpayne@69
|
163 character data in a single chunk, or they may split it into
|
|
jpayne@69
|
164 several chunks; however, all of the characters in any single
|
|
jpayne@69
|
165 event must come from the same external entity so that the
|
|
jpayne@69
|
166 Locator provides useful information."""
|
|
jpayne@69
|
167
|
|
jpayne@69
|
168 def ignorableWhitespace(self, whitespace):
|
|
jpayne@69
|
169 """Receive notification of ignorable whitespace in element content.
|
|
jpayne@69
|
170
|
|
jpayne@69
|
171 Validating Parsers must use this method to report each chunk
|
|
jpayne@69
|
172 of ignorable whitespace (see the W3C XML 1.0 recommendation,
|
|
jpayne@69
|
173 section 2.10): non-validating parsers may also use this method
|
|
jpayne@69
|
174 if they are capable of parsing and using content models.
|
|
jpayne@69
|
175
|
|
jpayne@69
|
176 SAX parsers may return all contiguous whitespace in a single
|
|
jpayne@69
|
177 chunk, or they may split it into several chunks; however, all
|
|
jpayne@69
|
178 of the characters in any single event must come from the same
|
|
jpayne@69
|
179 external entity, so that the Locator provides useful
|
|
jpayne@69
|
180 information."""
|
|
jpayne@69
|
181
|
|
jpayne@69
|
182 def processingInstruction(self, target, data):
|
|
jpayne@69
|
183 """Receive notification of a processing instruction.
|
|
jpayne@69
|
184
|
|
jpayne@69
|
185 The Parser will invoke this method once for each processing
|
|
jpayne@69
|
186 instruction found: note that processing instructions may occur
|
|
jpayne@69
|
187 before or after the main document element.
|
|
jpayne@69
|
188
|
|
jpayne@69
|
189 A SAX parser should never report an XML declaration (XML 1.0,
|
|
jpayne@69
|
190 section 2.8) or a text declaration (XML 1.0, section 4.3.1)
|
|
jpayne@69
|
191 using this method."""
|
|
jpayne@69
|
192
|
|
jpayne@69
|
193 def skippedEntity(self, name):
|
|
jpayne@69
|
194 """Receive notification of a skipped entity.
|
|
jpayne@69
|
195
|
|
jpayne@69
|
196 The Parser will invoke this method once for each entity
|
|
jpayne@69
|
197 skipped. Non-validating processors may skip entities if they
|
|
jpayne@69
|
198 have not seen the declarations (because, for example, the
|
|
jpayne@69
|
199 entity was declared in an external DTD subset). All processors
|
|
jpayne@69
|
200 may skip external entities, depending on the values of the
|
|
jpayne@69
|
201 http://xml.org/sax/features/external-general-entities and the
|
|
jpayne@69
|
202 http://xml.org/sax/features/external-parameter-entities
|
|
jpayne@69
|
203 properties."""
|
|
jpayne@69
|
204
|
|
jpayne@69
|
205
|
|
jpayne@69
|
206 # ===== DTDHandler =====
|
|
jpayne@69
|
207
|
|
jpayne@69
|
208 class DTDHandler:
|
|
jpayne@69
|
209 """Handle DTD events.
|
|
jpayne@69
|
210
|
|
jpayne@69
|
211 This interface specifies only those DTD events required for basic
|
|
jpayne@69
|
212 parsing (unparsed entities and attributes)."""
|
|
jpayne@69
|
213
|
|
jpayne@69
|
214 def notationDecl(self, name, publicId, systemId):
|
|
jpayne@69
|
215 "Handle a notation declaration event."
|
|
jpayne@69
|
216
|
|
jpayne@69
|
217 def unparsedEntityDecl(self, name, publicId, systemId, ndata):
|
|
jpayne@69
|
218 "Handle an unparsed entity declaration event."
|
|
jpayne@69
|
219
|
|
jpayne@69
|
220
|
|
jpayne@69
|
221 # ===== ENTITYRESOLVER =====
|
|
jpayne@69
|
222
|
|
jpayne@69
|
223 class EntityResolver:
|
|
jpayne@69
|
224 """Basic interface for resolving entities. If you create an object
|
|
jpayne@69
|
225 implementing this interface, then register the object with your
|
|
jpayne@69
|
226 Parser, the parser will call the method in your object to
|
|
jpayne@69
|
227 resolve all external entities. Note that DefaultHandler implements
|
|
jpayne@69
|
228 this interface with the default behaviour."""
|
|
jpayne@69
|
229
|
|
jpayne@69
|
230 def resolveEntity(self, publicId, systemId):
|
|
jpayne@69
|
231 """Resolve the system identifier of an entity and return either
|
|
jpayne@69
|
232 the system identifier to read from as a string, or an InputSource
|
|
jpayne@69
|
233 to read from."""
|
|
jpayne@69
|
234 return systemId
|
|
jpayne@69
|
235
|
|
jpayne@69
|
236
|
|
jpayne@69
|
237 #============================================================================
|
|
jpayne@69
|
238 #
|
|
jpayne@69
|
239 # CORE FEATURES
|
|
jpayne@69
|
240 #
|
|
jpayne@69
|
241 #============================================================================
|
|
jpayne@69
|
242
|
|
jpayne@69
|
243 feature_namespaces = "http://xml.org/sax/features/namespaces"
|
|
jpayne@69
|
244 # true: Perform Namespace processing (default).
|
|
jpayne@69
|
245 # false: Optionally do not perform Namespace processing
|
|
jpayne@69
|
246 # (implies namespace-prefixes).
|
|
jpayne@69
|
247 # access: (parsing) read-only; (not parsing) read/write
|
|
jpayne@69
|
248
|
|
jpayne@69
|
249 feature_namespace_prefixes = "http://xml.org/sax/features/namespace-prefixes"
|
|
jpayne@69
|
250 # true: Report the original prefixed names and attributes used for Namespace
|
|
jpayne@69
|
251 # declarations.
|
|
jpayne@69
|
252 # false: Do not report attributes used for Namespace declarations, and
|
|
jpayne@69
|
253 # optionally do not report original prefixed names (default).
|
|
jpayne@69
|
254 # access: (parsing) read-only; (not parsing) read/write
|
|
jpayne@69
|
255
|
|
jpayne@69
|
256 feature_string_interning = "http://xml.org/sax/features/string-interning"
|
|
jpayne@69
|
257 # true: All element names, prefixes, attribute names, Namespace URIs, and
|
|
jpayne@69
|
258 # local names are interned using the built-in intern function.
|
|
jpayne@69
|
259 # false: Names are not necessarily interned, although they may be (default).
|
|
jpayne@69
|
260 # access: (parsing) read-only; (not parsing) read/write
|
|
jpayne@69
|
261
|
|
jpayne@69
|
262 feature_validation = "http://xml.org/sax/features/validation"
|
|
jpayne@69
|
263 # true: Report all validation errors (implies external-general-entities and
|
|
jpayne@69
|
264 # external-parameter-entities).
|
|
jpayne@69
|
265 # false: Do not report validation errors.
|
|
jpayne@69
|
266 # access: (parsing) read-only; (not parsing) read/write
|
|
jpayne@69
|
267
|
|
jpayne@69
|
268 feature_external_ges = "http://xml.org/sax/features/external-general-entities"
|
|
jpayne@69
|
269 # true: Include all external general (text) entities.
|
|
jpayne@69
|
270 # false: Do not include external general entities.
|
|
jpayne@69
|
271 # access: (parsing) read-only; (not parsing) read/write
|
|
jpayne@69
|
272
|
|
jpayne@69
|
273 feature_external_pes = "http://xml.org/sax/features/external-parameter-entities"
|
|
jpayne@69
|
274 # true: Include all external parameter entities, including the external
|
|
jpayne@69
|
275 # DTD subset.
|
|
jpayne@69
|
276 # false: Do not include any external parameter entities, even the external
|
|
jpayne@69
|
277 # DTD subset.
|
|
jpayne@69
|
278 # access: (parsing) read-only; (not parsing) read/write
|
|
jpayne@69
|
279
|
|
jpayne@69
|
280 all_features = [feature_namespaces,
|
|
jpayne@69
|
281 feature_namespace_prefixes,
|
|
jpayne@69
|
282 feature_string_interning,
|
|
jpayne@69
|
283 feature_validation,
|
|
jpayne@69
|
284 feature_external_ges,
|
|
jpayne@69
|
285 feature_external_pes]
|
|
jpayne@69
|
286
|
|
jpayne@69
|
287
|
|
jpayne@69
|
288 #============================================================================
|
|
jpayne@69
|
289 #
|
|
jpayne@69
|
290 # CORE PROPERTIES
|
|
jpayne@69
|
291 #
|
|
jpayne@69
|
292 #============================================================================
|
|
jpayne@69
|
293
|
|
jpayne@69
|
294 property_lexical_handler = "http://xml.org/sax/properties/lexical-handler"
|
|
jpayne@69
|
295 # data type: xml.sax.sax2lib.LexicalHandler
|
|
jpayne@69
|
296 # description: An optional extension handler for lexical events like comments.
|
|
jpayne@69
|
297 # access: read/write
|
|
jpayne@69
|
298
|
|
jpayne@69
|
299 property_declaration_handler = "http://xml.org/sax/properties/declaration-handler"
|
|
jpayne@69
|
300 # data type: xml.sax.sax2lib.DeclHandler
|
|
jpayne@69
|
301 # description: An optional extension handler for DTD-related events other
|
|
jpayne@69
|
302 # than notations and unparsed entities.
|
|
jpayne@69
|
303 # access: read/write
|
|
jpayne@69
|
304
|
|
jpayne@69
|
305 property_dom_node = "http://xml.org/sax/properties/dom-node"
|
|
jpayne@69
|
306 # data type: org.w3c.dom.Node
|
|
jpayne@69
|
307 # description: When parsing, the current DOM node being visited if this is
|
|
jpayne@69
|
308 # a DOM iterator; when not parsing, the root DOM node for
|
|
jpayne@69
|
309 # iteration.
|
|
jpayne@69
|
310 # access: (parsing) read-only; (not parsing) read/write
|
|
jpayne@69
|
311
|
|
jpayne@69
|
312 property_xml_string = "http://xml.org/sax/properties/xml-string"
|
|
jpayne@69
|
313 # data type: String
|
|
jpayne@69
|
314 # description: The literal string of characters that was the source for
|
|
jpayne@69
|
315 # the current event.
|
|
jpayne@69
|
316 # access: read-only
|
|
jpayne@69
|
317
|
|
jpayne@69
|
318 property_encoding = "http://www.python.org/sax/properties/encoding"
|
|
jpayne@69
|
319 # data type: String
|
|
jpayne@69
|
320 # description: The name of the encoding to assume for input data.
|
|
jpayne@69
|
321 # access: write: set the encoding, e.g. established by a higher-level
|
|
jpayne@69
|
322 # protocol. May change during parsing (e.g. after
|
|
jpayne@69
|
323 # processing a META tag)
|
|
jpayne@69
|
324 # read: return the current encoding (possibly established through
|
|
jpayne@69
|
325 # auto-detection.
|
|
jpayne@69
|
326 # initial value: UTF-8
|
|
jpayne@69
|
327 #
|
|
jpayne@69
|
328
|
|
jpayne@69
|
329 property_interning_dict = "http://www.python.org/sax/properties/interning-dict"
|
|
jpayne@69
|
330 # data type: Dictionary
|
|
jpayne@69
|
331 # description: The dictionary used to intern common strings in the document
|
|
jpayne@69
|
332 # access: write: Request that the parser uses a specific dictionary, to
|
|
jpayne@69
|
333 # allow interning across different documents
|
|
jpayne@69
|
334 # read: return the current interning dictionary, or None
|
|
jpayne@69
|
335 #
|
|
jpayne@69
|
336
|
|
jpayne@69
|
337 all_properties = [property_lexical_handler,
|
|
jpayne@69
|
338 property_dom_node,
|
|
jpayne@69
|
339 property_declaration_handler,
|
|
jpayne@69
|
340 property_xml_string,
|
|
jpayne@69
|
341 property_encoding,
|
|
jpayne@69
|
342 property_interning_dict]
|
