Python code coverage for Lib/xml/sax/handler.py

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