--- /dev/null
+"""\r
+This module contains the core classes of version 2.0 of SAX for Python.\r
+This file provides only default classes with absolutely minimum\r
+functionality, from which drivers and applications can be subclassed.\r
+\r
+Many of these classes are empty and are included only as documentation\r
+of the interfaces.\r
+\r
+$Id$\r
+"""\r
+\r
+version = '2.0beta'\r
+\r
+#============================================================================\r
+#\r
+# HANDLER INTERFACES\r
+#\r
+#============================================================================\r
+\r
+# ===== ERRORHANDLER =====\r
+\r
+class ErrorHandler:\r
+ """Basic interface for SAX error handlers.\r
+\r
+ If you create an object that implements this interface, then\r
+ register the object with your XMLReader, the parser will call the\r
+ methods in your object to report all warnings and errors. There\r
+ are three levels of errors available: warnings, (possibly)\r
+ recoverable errors, and unrecoverable errors. All methods take a\r
+ SAXParseException as the only parameter."""\r
+\r
+ def error(self, exception):\r
+ "Handle a recoverable error."\r
+ raise exception\r
+\r
+ def fatalError(self, exception):\r
+ "Handle a non-recoverable error."\r
+ raise exception\r
+\r
+ def warning(self, exception):\r
+ "Handle a warning."\r
+ print exception\r
+\r
+\r
+# ===== CONTENTHANDLER =====\r
+\r
+class ContentHandler:\r
+ """Interface for receiving logical document content events.\r
+\r
+ This is the main callback interface in SAX, and the one most\r
+ important to applications. The order of events in this interface\r
+ mirrors the order of the information in the document."""\r
+\r
+ def __init__(self):\r
+ self._locator = None\r
+\r
+ def setDocumentLocator(self, locator):\r
+ """Called by the parser to give the application a locator for\r
+ locating the origin of document events.\r
+\r
+ SAX parsers are strongly encouraged (though not absolutely\r
+ required) to supply a locator: if it does so, it must supply\r
+ the locator to the application by invoking this method before\r
+ invoking any of the other methods in the DocumentHandler\r
+ interface.\r
+\r
+ The locator allows the application to determine the end\r
+ position of any document-related event, even if the parser is\r
+ not reporting an error. Typically, the application will use\r
+ this information for reporting its own errors (such as\r
+ character content that does not match an application's\r
+ business rules). The information returned by the locator is\r
+ probably not sufficient for use with a search engine.\r
+\r
+ Note that the locator will return correct information only\r
+ during the invocation of the events in this interface. The\r
+ application should not attempt to use it at any other time."""\r
+ self._locator = locator\r
+\r
+ def startDocument(self):\r
+ """Receive notification of the beginning of a document.\r
+\r
+ The SAX parser will invoke this method only once, before any\r
+ other methods in this interface or in DTDHandler (except for\r
+ setDocumentLocator)."""\r
+\r
+ def endDocument(self):\r
+ """Receive notification of the end of a document.\r
+\r
+ The SAX parser will invoke this method only once, and it will\r
+ be the last method invoked during the parse. The parser shall\r
+ not invoke this method until it has either abandoned parsing\r
+ (because of an unrecoverable error) or reached the end of\r
+ input."""\r
+\r
+ def startPrefixMapping(self, prefix, uri):\r
+ """Begin the scope of a prefix-URI Namespace mapping.\r
+\r
+ The information from this event is not necessary for normal\r
+ Namespace processing: the SAX XML reader will automatically\r
+ replace prefixes for element and attribute names when the\r
+ http://xml.org/sax/features/namespaces feature is true (the\r
+ default).\r
+\r
+ There are cases, however, when applications need to use\r
+ prefixes in character data or in attribute values, where they\r
+ cannot safely be expanded automatically; the\r
+ start/endPrefixMapping event supplies the information to the\r
+ application to expand prefixes in those contexts itself, if\r
+ necessary.\r
+\r
+ Note that start/endPrefixMapping events are not guaranteed to\r
+ be properly nested relative to each-other: all\r
+ startPrefixMapping events will occur before the corresponding\r
+ startElement event, and all endPrefixMapping events will occur\r
+ after the corresponding endElement event, but their order is\r
+ not guaranteed."""\r
+\r
+ def endPrefixMapping(self, prefix):\r
+ """End the scope of a prefix-URI mapping.\r
+\r
+ See startPrefixMapping for details. This event will always\r
+ occur after the corresponding endElement event, but the order\r
+ of endPrefixMapping events is not otherwise guaranteed."""\r
+\r
+ def startElement(self, name, attrs):\r
+ """Signals the start of an element in non-namespace mode.\r
+\r
+ The name parameter contains the raw XML 1.0 name of the\r
+ element type as a string and the attrs parameter holds an\r
+ instance of the Attributes class containing the attributes of\r
+ the element."""\r
+\r
+ def endElement(self, name):\r
+ """Signals the end of an element in non-namespace mode.\r
+\r
+ The name parameter contains the name of the element type, just\r
+ as with the startElement event."""\r
+\r
+ def startElementNS(self, name, qname, attrs):\r
+ """Signals the start of an element in namespace mode.\r
+\r
+ The name parameter contains the name of the element type as a\r
+ (uri, localname) tuple, the qname parameter the raw XML 1.0\r
+ name used in the source document, and the attrs parameter\r
+ holds an instance of the Attributes class containing the\r
+ attributes of the element.\r
+\r
+ The uri part of the name tuple is None for elements which have\r
+ no namespace."""\r
+\r
+ def endElementNS(self, name, qname):\r
+ """Signals the end of an element in namespace mode.\r
+\r
+ The name parameter contains the name of the element type, just\r
+ as with the startElementNS event."""\r
+\r
+ def characters(self, content):\r
+ """Receive notification of character data.\r
+\r
+ The Parser will call this method to report each chunk of\r
+ character data. SAX parsers may return all contiguous\r
+ character data in a single chunk, or they may split it into\r
+ several chunks; however, all of the characters in any single\r
+ event must come from the same external entity so that the\r
+ Locator provides useful information."""\r
+\r
+ def ignorableWhitespace(self, whitespace):\r
+ """Receive notification of ignorable whitespace in element content.\r
+\r
+ Validating Parsers must use this method to report each chunk\r
+ of ignorable whitespace (see the W3C XML 1.0 recommendation,\r
+ section 2.10): non-validating parsers may also use this method\r
+ if they are capable of parsing and using content models.\r
+\r
+ SAX parsers may return all contiguous whitespace in a single\r
+ chunk, or they may split it into several chunks; however, all\r
+ of the characters in any single event must come from the same\r
+ external entity, so that the Locator provides useful\r
+ information."""\r
+\r
+ def processingInstruction(self, target, data):\r
+ """Receive notification of a processing instruction.\r
+\r
+ The Parser will invoke this method once for each processing\r
+ instruction found: note that processing instructions may occur\r
+ before or after the main document element.\r
+\r
+ A SAX parser should never report an XML declaration (XML 1.0,\r
+ section 2.8) or a text declaration (XML 1.0, section 4.3.1)\r
+ using this method."""\r
+\r
+ def skippedEntity(self, name):\r
+ """Receive notification of a skipped entity.\r
+\r
+ The Parser will invoke this method once for each entity\r
+ skipped. Non-validating processors may skip entities if they\r
+ have not seen the declarations (because, for example, the\r
+ entity was declared in an external DTD subset). All processors\r
+ may skip external entities, depending on the values of the\r
+ http://xml.org/sax/features/external-general-entities and the\r
+ http://xml.org/sax/features/external-parameter-entities\r
+ properties."""\r
+\r
+\r
+# ===== DTDHandler =====\r
+\r
+class DTDHandler:\r
+ """Handle DTD events.\r
+\r
+ This interface specifies only those DTD events required for basic\r
+ parsing (unparsed entities and attributes)."""\r
+\r
+ def notationDecl(self, name, publicId, systemId):\r
+ "Handle a notation declaration event."\r
+\r
+ def unparsedEntityDecl(self, name, publicId, systemId, ndata):\r
+ "Handle an unparsed entity declaration event."\r
+\r
+\r
+# ===== ENTITYRESOLVER =====\r
+\r
+class EntityResolver:\r
+ """Basic interface for resolving entities. If you create an object\r
+ implementing this interface, then register the object with your\r
+ Parser, the parser will call the method in your object to\r
+ resolve all external entities. Note that DefaultHandler implements\r
+ this interface with the default behaviour."""\r
+\r
+ def resolveEntity(self, publicId, systemId):\r
+ """Resolve the system identifier of an entity and return either\r
+ the system identifier to read from as a string, or an InputSource\r
+ to read from."""\r
+ return systemId\r
+\r
+\r
+#============================================================================\r
+#\r
+# CORE FEATURES\r
+#\r
+#============================================================================\r
+\r
+feature_namespaces = "http://xml.org/sax/features/namespaces"\r
+# true: Perform Namespace processing (default).\r
+# false: Optionally do not perform Namespace processing\r
+# (implies namespace-prefixes).\r
+# access: (parsing) read-only; (not parsing) read/write\r
+\r
+feature_namespace_prefixes = "http://xml.org/sax/features/namespace-prefixes"\r
+# true: Report the original prefixed names and attributes used for Namespace\r
+# declarations.\r
+# false: Do not report attributes used for Namespace declarations, and\r
+# optionally do not report original prefixed names (default).\r
+# access: (parsing) read-only; (not parsing) read/write\r
+\r
+feature_string_interning = "http://xml.org/sax/features/string-interning"\r
+# true: All element names, prefixes, attribute names, Namespace URIs, and\r
+# local names are interned using the built-in intern function.\r
+# false: Names are not necessarily interned, although they may be (default).\r
+# access: (parsing) read-only; (not parsing) read/write\r
+\r
+feature_validation = "http://xml.org/sax/features/validation"\r
+# true: Report all validation errors (implies external-general-entities and\r
+# external-parameter-entities).\r
+# false: Do not report validation errors.\r
+# access: (parsing) read-only; (not parsing) read/write\r
+\r
+feature_external_ges = "http://xml.org/sax/features/external-general-entities"\r
+# true: Include all external general (text) entities.\r
+# false: Do not include external general entities.\r
+# access: (parsing) read-only; (not parsing) read/write\r
+\r
+feature_external_pes = "http://xml.org/sax/features/external-parameter-entities"\r
+# true: Include all external parameter entities, including the external\r
+# DTD subset.\r
+# false: Do not include any external parameter entities, even the external\r
+# DTD subset.\r
+# access: (parsing) read-only; (not parsing) read/write\r
+\r
+all_features = [feature_namespaces,\r
+ feature_namespace_prefixes,\r
+ feature_string_interning,\r
+ feature_validation,\r
+ feature_external_ges,\r
+ feature_external_pes]\r
+\r
+\r
+#============================================================================\r
+#\r
+# CORE PROPERTIES\r
+#\r
+#============================================================================\r
+\r
+property_lexical_handler = "http://xml.org/sax/properties/lexical-handler"\r
+# data type: xml.sax.sax2lib.LexicalHandler\r
+# description: An optional extension handler for lexical events like comments.\r
+# access: read/write\r
+\r
+property_declaration_handler = "http://xml.org/sax/properties/declaration-handler"\r
+# data type: xml.sax.sax2lib.DeclHandler\r
+# description: An optional extension handler for DTD-related events other\r
+# than notations and unparsed entities.\r
+# access: read/write\r
+\r
+property_dom_node = "http://xml.org/sax/properties/dom-node"\r
+# data type: org.w3c.dom.Node\r
+# description: When parsing, the current DOM node being visited if this is\r
+# a DOM iterator; when not parsing, the root DOM node for\r
+# iteration.\r
+# access: (parsing) read-only; (not parsing) read/write\r
+\r
+property_xml_string = "http://xml.org/sax/properties/xml-string"\r
+# data type: String\r
+# description: The literal string of characters that was the source for\r
+# the current event.\r
+# access: read-only\r
+\r
+property_encoding = "http://www.python.org/sax/properties/encoding"\r
+# data type: String\r
+# description: The name of the encoding to assume for input data.\r
+# access: write: set the encoding, e.g. established by a higher-level\r
+# protocol. May change during parsing (e.g. after\r
+# processing a META tag)\r
+# read: return the current encoding (possibly established through\r
+# auto-detection.\r
+# initial value: UTF-8\r
+#\r
+\r
+property_interning_dict = "http://www.python.org/sax/properties/interning-dict"\r
+# data type: Dictionary\r
+# description: The dictionary used to intern common strings in the document\r
+# access: write: Request that the parser uses a specific dictionary, to\r
+# allow interning across different documents\r
+# read: return the current interning dictionary, or None\r
+#\r
+\r
+all_properties = [property_lexical_handler,\r
+ property_dom_node,\r
+ property_declaration_handler,\r
+ property_xml_string,\r
+ property_encoding,\r
+ property_interning_dict]\r