0001 """ 0002 This module contains the core classes of version 2.0 of SAX for Python. 0003 This file provides only default classes with absolutely minimum 0004 functionality, from which drivers and applications can be subclassed. 0005 0006 Many of these classes are empty and are included only as documentation 0007 of the interfaces. 0008 0009 $Id: handler.py,v 1.11 2004/05/06 03:47:48 fdrake Exp $ 0010 """ 0011 0012 version = '2.0beta' 0013 0014 #============================================================================ 0015 # 0016 # HANDLER INTERFACES 0017 # 0018 #============================================================================ 0019 0020 # ===== ERRORHANDLER ===== 0021 0022 class ErrorHandler: 0023 """Basic interface for SAX error handlers. 0024 0025 If you create an object that implements this interface, then 0026 register the object with your XMLReader, the parser will call the 0027 methods in your object to report all warnings and errors. There 0028 are three levels of errors available: warnings, (possibly) 0029 recoverable errors, and unrecoverable errors. All methods take a 0030 SAXParseException as the only parameter.""" 0031 0032 def error(self, exception): 0033 "Handle a recoverable error." 0034 raise exception 0035 0036 def fatalError(self, exception): 0037 "Handle a non-recoverable error." 0038 raise exception 0039 0040 def warning(self, exception): 0041 "Handle a warning." 0042 print exception 0043 0044 0045 # ===== CONTENTHANDLER ===== 0046 0047 class ContentHandler: 0048 """Interface for receiving logical document content events. 0049 0050 This is the main callback interface in SAX, and the one most 0051 important to applications. The order of events in this interface 0052 mirrors the order of the information in the document.""" 0053 0054 def __init__(self): 0055 self._locator = None 0056 0057 def setDocumentLocator(self, locator): 0058 """Called by the parser to give the application a locator for 0059 locating the origin of document events. 0060 0061 SAX parsers are strongly encouraged (though not absolutely 0062 required) to supply a locator: if it does so, it must supply 0063 the locator to the application by invoking this method before 0064 invoking any of the other methods in the DocumentHandler 0065 interface. 0066 0067 The locator allows the application to determine the end 0068 position of any document-related event, even if the parser is 0069 not reporting an error. Typically, the application will use 0070 this information for reporting its own errors (such as 0071 character content that does not match an application's 0072 business rules). The information returned by the locator is 0073 probably not sufficient for use with a search engine. 0074 0075 Note that the locator will return correct information only 0076 during the invocation of the events in this interface. The 0077 application should not attempt to use it at any other time.""" 0078 self._locator = locator 0079 0080 def startDocument(self): 0081 """Receive notification of the beginning of a document. 0082 0083 The SAX parser will invoke this method only once, before any 0084 other methods in this interface or in DTDHandler (except for 0085 setDocumentLocator).""" 0086 0087 def endDocument(self): 0088 """Receive notification of the end of a document. 0089 0090 The SAX parser will invoke this method only once, and it will 0091 be the last method invoked during the parse. The parser shall 0092 not invoke this method until it has either abandoned parsing 0093 (because of an unrecoverable error) or reached the end of 0094 input.""" 0095 0096 def startPrefixMapping(self, prefix, uri): 0097 """Begin the scope of a prefix-URI Namespace mapping. 0098 0099 The information from this event is not necessary for normal 0100 Namespace processing: the SAX XML reader will automatically 0101 replace prefixes for element and attribute names when the 0102 http://xml.org/sax/features/namespaces feature is true (the 0103 default). 0104 0105 There are cases, however, when applications need to use 0106 prefixes in character data or in attribute values, where they 0107 cannot safely be expanded automatically; the 0108 start/endPrefixMapping event supplies the information to the 0109 application to expand prefixes in those contexts itself, if 0110 necessary. 0111 0112 Note that start/endPrefixMapping events are not guaranteed to 0113 be properly nested relative to each-other: all 0114 startPrefixMapping events will occur before the corresponding 0115 startElement event, and all endPrefixMapping events will occur 0116 after the corresponding endElement event, but their order is 0117 not guaranteed.""" 0118 0119 def endPrefixMapping(self, prefix): 0120 """End the scope of a prefix-URI mapping. 0121 0122 See startPrefixMapping for details. This event will always 0123 occur after the corresponding endElement event, but the order 0124 of endPrefixMapping events is not otherwise guaranteed.""" 0125 0126 def startElement(self, name, attrs): 0127 """Signals the start of an element in non-namespace mode. 0128 0129 The name parameter contains the raw XML 1.0 name of the 0130 element type as a string and the attrs parameter holds an 0131 instance of the Attributes class containing the attributes of 0132 the element.""" 0133 0134 def endElement(self, name): 0135 """Signals the end of an element in non-namespace mode. 0136 0137 The name parameter contains the name of the element type, just 0138 as with the startElement event.""" 0139 0140 def startElementNS(self, name, qname, attrs): 0141 """Signals the start of an element in namespace mode. 0142 0143 The name parameter contains the name of the element type as a 0144 (uri, localname) tuple, the qname parameter the raw XML 1.0 0145 name used in the source document, and the attrs parameter 0146 holds an instance of the Attributes class containing the 0147 attributes of the element. 0148 0149 The uri part of the name tuple is None for elements which have 0150 no namespace.""" 0151 0152 def endElementNS(self, name, qname): 0153 """Signals the end of an element in namespace mode. 0154 0155 The name parameter contains the name of the element type, just 0156 as with the startElementNS event.""" 0157 0158 def characters(self, content): 0159 """Receive notification of character data. 0160 0161 The Parser will call this method to report each chunk of 0162 character data. SAX parsers may return all contiguous 0163 character data in a single chunk, or they may split it into 0164 several chunks; however, all of the characters in any single 0165 event must come from the same external entity so that the 0166 Locator provides useful information.""" 0167 0168 def ignorableWhitespace(self, whitespace): 0169 """Receive notification of ignorable whitespace in element content. 0170 0171 Validating Parsers must use this method to report each chunk 0172 of ignorable whitespace (see the W3C XML 1.0 recommendation, 0173 section 2.10): non-validating parsers may also use this method 0174 if they are capable of parsing and using content models. 0175 0176 SAX parsers may return all contiguous whitespace in a single 0177 chunk, or they may split it into several chunks; however, all 0178 of the characters in any single event must come from the same 0179 external entity, so that the Locator provides useful 0180 information.""" 0181 0182 def processingInstruction(self, target, data): 0183 """Receive notification of a processing instruction. 0184 0185 The Parser will invoke this method once for each processing 0186 instruction found: note that processing instructions may occur 0187 before or after the main document element. 0188 0189 A SAX parser should never report an XML declaration (XML 1.0, 0190 section 2.8) or a text declaration (XML 1.0, section 4.3.1) 0191 using this method.""" 0192 0193 def skippedEntity(self, name): 0194 """Receive notification of a skipped entity. 0195 0196 The Parser will invoke this method once for each entity 0197 skipped. Non-validating processors may skip entities if they 0198 have not seen the declarations (because, for example, the 0199 entity was declared in an external DTD subset). All processors 0200 may skip external entities, depending on the values of the 0201 http://xml.org/sax/features/external-general-entities and the 0202 http://xml.org/sax/features/external-parameter-entities 0203 properties.""" 0204 0205 0206 # ===== DTDHandler ===== 0207 0208 class DTDHandler: 0209 """Handle DTD events. 0210 0211 This interface specifies only those DTD events required for basic 0212 parsing (unparsed entities and attributes).""" 0213 0214 def notationDecl(self, name, publicId, systemId): 0215 "Handle a notation declaration event." 0216 0217 def unparsedEntityDecl(self, name, publicId, systemId, ndata): 0218 "Handle an unparsed entity declaration event." 0219 0220 0221 # ===== ENTITYRESOLVER ===== 0222 0223 class EntityResolver: 0224 """Basic interface for resolving entities. If you create an object 0225 implementing this interface, then register the object with your 0226 Parser, the parser will call the method in your object to 0227 resolve all external entities. Note that DefaultHandler implements 0228 this interface with the default behaviour.""" 0229 0230 def resolveEntity(self, publicId, systemId): 0231 """Resolve the system identifier of an entity and return either 0232 the system identifier to read from as a string, or an InputSource 0233 to read from.""" 0234 return systemId 0235 0236 0237 #============================================================================ 0238 # 0239 # CORE FEATURES 0240 # 0241 #============================================================================ 0242 0243 feature_namespaces = "http://xml.org/sax/features/namespaces" 0244 # true: Perform Namespace processing (default). 0245 # false: Optionally do not perform Namespace processing 0246 # (implies namespace-prefixes). 0247 # access: (parsing) read-only; (not parsing) read/write 0248 0249 feature_namespace_prefixes = "http://xml.org/sax/features/namespace-prefixes" 0250 # true: Report the original prefixed names and attributes used for Namespace 0251 # declarations. 0252 # false: Do not report attributes used for Namespace declarations, and 0253 # optionally do not report original prefixed names (default). 0254 # access: (parsing) read-only; (not parsing) read/write 0255 0256 feature_string_interning = "http://xml.org/sax/features/string-interning" 0257 # true: All element names, prefixes, attribute names, Namespace URIs, and 0258 # local names are interned using the built-in intern function. 0259 # false: Names are not necessarily interned, although they may be (default). 0260 # access: (parsing) read-only; (not parsing) read/write 0261 0262 feature_validation = "http://xml.org/sax/features/validation" 0263 # true: Report all validation errors (implies external-general-entities and 0264 # external-parameter-entities). 0265 # false: Do not report validation errors. 0266 # access: (parsing) read-only; (not parsing) read/write 0267 0268 feature_external_ges = "http://xml.org/sax/features/external-general-entities" 0269 # true: Include all external general (text) entities. 0270 # false: Do not include external general entities. 0271 # access: (parsing) read-only; (not parsing) read/write 0272 0273 feature_external_pes = "http://xml.org/sax/features/external-parameter-entities" 0274 # true: Include all external parameter entities, including the external 0275 # DTD subset. 0276 # false: Do not include any external parameter entities, even the external 0277 # DTD subset. 0278 # access: (parsing) read-only; (not parsing) read/write 0279 0280 all_features = [feature_namespaces, 0281 feature_namespace_prefixes, 0282 feature_string_interning, 0283 feature_validation, 0284 feature_external_ges, 0285 feature_external_pes] 0286 0287 0288 #============================================================================ 0289 # 0290 # CORE PROPERTIES 0291 # 0292 #============================================================================ 0293 0294 property_lexical_handler = "http://xml.org/sax/properties/lexical-handler" 0295 # data type: xml.sax.sax2lib.LexicalHandler 0296 # description: An optional extension handler for lexical events like comments. 0297 # access: read/write 0298 0299 property_declaration_handler = "http://xml.org/sax/properties/declaration-handler" 0300 # data type: xml.sax.sax2lib.DeclHandler 0301 # description: An optional extension handler for DTD-related events other 0302 # than notations and unparsed entities. 0303 # access: read/write 0304 0305 property_dom_node = "http://xml.org/sax/properties/dom-node" 0306 # data type: org.w3c.dom.Node 0307 # description: When parsing, the current DOM node being visited if this is 0308 # a DOM iterator; when not parsing, the root DOM node for 0309 # iteration. 0310 # access: (parsing) read-only; (not parsing) read/write 0311 0312 property_xml_string = "http://xml.org/sax/properties/xml-string" 0313 # data type: String 0314 # description: The literal string of characters that was the source for 0315 # the current event. 0316 # access: read-only 0317 0318 property_encoding = "http://www.python.org/sax/properties/encoding" 0319 # data type: String 0320 # description: The name of the encoding to assume for input data. 0321 # access: write: set the encoding, e.g. established by a higher-level 0322 # protocol. May change during parsing (e.g. after 0323 # processing a META tag) 0324 # read: return the current encoding (possibly established through 0325 # auto-detection. 0326 # initial value: UTF-8 0327 # 0328 0329 property_interning_dict = "http://www.python.org/sax/properties/interning-dict" 0330 # data type: Dictionary 0331 # description: The dictionary used to intern common strings in the document 0332 # access: write: Request that the parser uses a specific dictionary, to 0333 # allow interning across different documents 0334 # read: return the current interning dictionary, or None 0335 # 0336 0337 all_properties = [property_lexical_handler, 0338 property_dom_node, 0339 property_declaration_handler, 0340 property_xml_string, 0341 property_encoding, 0342 property_interning_dict] 0343
Generated by PyXR 0.9.4