codekingpro/portable-devtools

1"""2This module contains the core classes of version 2.0 of SAX for Python.3This file provides only default classes with absolutely minimum4functionality, from which drivers and applications can be subclassed.5 6Many of these classes are empty and are included only as documentation7of the interfaces.8 9$Id$10"""11 12version = '2.0beta'13 14#============================================================================15#16# HANDLER INTERFACES17#18#============================================================================19 20# ===== ERRORHANDLER =====21 22class ErrorHandler:23    """Basic interface for SAX error handlers.24 25    If you create an object that implements this interface, then26    register the object with your XMLReader, the parser will call the27    methods in your object to report all warnings and errors. There28    are three levels of errors available: warnings, (possibly)29    recoverable errors, and unrecoverable errors. All methods take a30    SAXParseException as the only parameter."""31 32    def error(self, exception):33        "Handle a recoverable error."34        raise exception35 36    def fatalError(self, exception):37        "Handle a non-recoverable error."38        raise exception39 40    def warning(self, exception):41        "Handle a warning."42        print(exception)43 44 45# ===== CONTENTHANDLER =====46 47class ContentHandler:48    """Interface for receiving logical document content events.49 50    This is the main callback interface in SAX, and the one most51    important to applications. The order of events in this interface52    mirrors the order of the information in the document."""53 54    def __init__(self):55        self._locator = None56 57    def setDocumentLocator(self, locator):58        """Called by the parser to give the application a locator for59        locating the origin of document events.60 61        SAX parsers are strongly encouraged (though not absolutely62        required) to supply a locator: if it does so, it must supply63        the locator to the application by invoking this method before64        invoking any of the other methods in the DocumentHandler65        interface.66 67        The locator allows the application to determine the end68        position of any document-related event, even if the parser is69        not reporting an error. Typically, the application will use70        this information for reporting its own errors (such as71        character content that does not match an application's72        business rules). The information returned by the locator is73        probably not sufficient for use with a search engine.74 75        Note that the locator will return correct information only76        during the invocation of the events in this interface. The77        application should not attempt to use it at any other time."""78        self._locator = locator79 80    def startDocument(self):81        """Receive notification of the beginning of a document.82 83        The SAX parser will invoke this method only once, before any84        other methods in this interface or in DTDHandler (except for85        setDocumentLocator)."""86 87    def endDocument(self):88        """Receive notification of the end of a document.89 90        The SAX parser will invoke this method only once, and it will91        be the last method invoked during the parse. The parser shall92        not invoke this method until it has either abandoned parsing93        (because of an unrecoverable error) or reached the end of94        input."""95 96    def startPrefixMapping(self, prefix, uri):97        """Begin the scope of a prefix-URI Namespace mapping.98 99        The information from this event is not necessary for normal100        Namespace processing: the SAX XML reader will automatically101        replace prefixes for element and attribute names when the102        http://xml.org/sax/features/namespaces feature is true (the103        default).104 105        There are cases, however, when applications need to use106        prefixes in character data or in attribute values, where they107        cannot safely be expanded automatically; the108        start/endPrefixMapping event supplies the information to the109        application to expand prefixes in those contexts itself, if110        necessary.111 112        Note that start/endPrefixMapping events are not guaranteed to113        be properly nested relative to each-other: all114        startPrefixMapping events will occur before the corresponding115        startElement event, and all endPrefixMapping events will occur116        after the corresponding endElement event, but their order is117        not guaranteed."""118 119    def endPrefixMapping(self, prefix):120        """End the scope of a prefix-URI mapping.121 122        See startPrefixMapping for details. This event will always123        occur after the corresponding endElement event, but the order124        of endPrefixMapping events is not otherwise guaranteed."""125 126    def startElement(self, name, attrs):127        """Signals the start of an element in non-namespace mode.128 129        The name parameter contains the raw XML 1.0 name of the130        element type as a string and the attrs parameter holds an131        instance of the Attributes class containing the attributes of132        the element."""133 134    def endElement(self, name):135        """Signals the end of an element in non-namespace mode.136 137        The name parameter contains the name of the element type, just138        as with the startElement event."""139 140    def startElementNS(self, name, qname, attrs):141        """Signals the start of an element in namespace mode.142 143        The name parameter contains the name of the element type as a144        (uri, localname) tuple, the qname parameter the raw XML 1.0145        name used in the source document, and the attrs parameter146        holds an instance of the Attributes class containing the147        attributes of the element.148 149        The uri part of the name tuple is None for elements which have150        no namespace."""151 152    def endElementNS(self, name, qname):153        """Signals the end of an element in namespace mode.154 155        The name parameter contains the name of the element type, just156        as with the startElementNS event."""157 158    def characters(self, content):159        """Receive notification of character data.160 161        The Parser will call this method to report each chunk of162        character data. SAX parsers may return all contiguous163        character data in a single chunk, or they may split it into164        several chunks; however, all of the characters in any single165        event must come from the same external entity so that the166        Locator provides useful information."""167 168    def ignorableWhitespace(self, whitespace):169        """Receive notification of ignorable whitespace in element content.170 171        Validating Parsers must use this method to report each chunk172        of ignorable whitespace (see the W3C XML 1.0 recommendation,173        section 2.10): non-validating parsers may also use this method174        if they are capable of parsing and using content models.175 176        SAX parsers may return all contiguous whitespace in a single177        chunk, or they may split it into several chunks; however, all178        of the characters in any single event must come from the same179        external entity, so that the Locator provides useful180        information."""181 182    def processingInstruction(self, target, data):183        """Receive notification of a processing instruction.184 185        The Parser will invoke this method once for each processing186        instruction found: note that processing instructions may occur187        before or after the main document element.188 189        A SAX parser should never report an XML declaration (XML 1.0,190        section 2.8) or a text declaration (XML 1.0, section 4.3.1)191        using this method."""192 193    def skippedEntity(self, name):194        """Receive notification of a skipped entity.195 196        The Parser will invoke this method once for each entity197        skipped. Non-validating processors may skip entities if they198        have not seen the declarations (because, for example, the199        entity was declared in an external DTD subset). All processors200        may skip external entities, depending on the values of the201        http://xml.org/sax/features/external-general-entities and the202        http://xml.org/sax/features/external-parameter-entities203        properties."""204 205 206# ===== DTDHandler =====207 208class DTDHandler:209    """Handle DTD events.210 211    This interface specifies only those DTD events required for basic212    parsing (unparsed entities and attributes)."""213 214    def notationDecl(self, name, publicId, systemId):215        "Handle a notation declaration event."216 217    def unparsedEntityDecl(self, name, publicId, systemId, ndata):218        "Handle an unparsed entity declaration event."219 220 221# ===== ENTITYRESOLVER =====222 223class EntityResolver:224    """Basic interface for resolving entities. If you create an object225    implementing this interface, then register the object with your226    Parser, the parser will call the method in your object to227    resolve all external entities. Note that DefaultHandler implements228    this interface with the default behaviour."""229 230    def resolveEntity(self, publicId, systemId):231        """Resolve the system identifier of an entity and return either232        the system identifier to read from as a string, or an InputSource233        to read from."""234        return systemId235 236 237#============================================================================238#239# CORE FEATURES240#241#============================================================================242 243feature_namespaces = "http://xml.org/sax/features/namespaces"244# true: Perform Namespace processing (default).245# false: Optionally do not perform Namespace processing246#        (implies namespace-prefixes).247# access: (parsing) read-only; (not parsing) read/write248 249feature_namespace_prefixes = "http://xml.org/sax/features/namespace-prefixes"250# true: Report the original prefixed names and attributes used for Namespace251#       declarations.252# false: Do not report attributes used for Namespace declarations, and253#        optionally do not report original prefixed names (default).254# access: (parsing) read-only; (not parsing) read/write255 256feature_string_interning = "http://xml.org/sax/features/string-interning"257# true: All element names, prefixes, attribute names, Namespace URIs, and258#       local names are interned using the built-in intern function.259# false: Names are not necessarily interned, although they may be (default).260# access: (parsing) read-only; (not parsing) read/write261 262feature_validation = "http://xml.org/sax/features/validation"263# true: Report all validation errors (implies external-general-entities and264#       external-parameter-entities).265# false: Do not report validation errors.266# access: (parsing) read-only; (not parsing) read/write267 268feature_external_ges = "http://xml.org/sax/features/external-general-entities"269# true: Include all external general (text) entities.270# false: Do not include external general entities.271# access: (parsing) read-only; (not parsing) read/write272 273feature_external_pes = "http://xml.org/sax/features/external-parameter-entities"274# true: Include all external parameter entities, including the external275#       DTD subset.276# false: Do not include any external parameter entities, even the external277#        DTD subset.278# access: (parsing) read-only; (not parsing) read/write279 280all_features = [feature_namespaces,281                feature_namespace_prefixes,282                feature_string_interning,283                feature_validation,284                feature_external_ges,285                feature_external_pes]286 287 288#============================================================================289#290# CORE PROPERTIES291#292#============================================================================293 294property_lexical_handler = "http://xml.org/sax/properties/lexical-handler"295# data type: xml.sax.sax2lib.LexicalHandler296# description: An optional extension handler for lexical events like comments.297# access: read/write298 299property_declaration_handler = "http://xml.org/sax/properties/declaration-handler"300# data type: xml.sax.sax2lib.DeclHandler301# description: An optional extension handler for DTD-related events other302#              than notations and unparsed entities.303# access: read/write304 305property_dom_node = "http://xml.org/sax/properties/dom-node"306# data type: org.w3c.dom.Node307# description: When parsing, the current DOM node being visited if this is308#              a DOM iterator; when not parsing, the root DOM node for309#              iteration.310# access: (parsing) read-only; (not parsing) read/write311 312property_xml_string = "http://xml.org/sax/properties/xml-string"313# data type: String314# description: The literal string of characters that was the source for315#              the current event.316# access: read-only317 318property_encoding = "http://www.python.org/sax/properties/encoding"319# data type: String320# description: The name of the encoding to assume for input data.321# access: write: set the encoding, e.g. established by a higher-level322#                protocol. May change during parsing (e.g. after323#                processing a META tag)324#         read:  return the current encoding (possibly established through325#                auto-detection.326# initial value: UTF-8327#328 329property_interning_dict = "http://www.python.org/sax/properties/interning-dict"330# data type: Dictionary331# description: The dictionary used to intern common strings in the document332# access: write: Request that the parser uses a specific dictionary, to333#                allow interning across different documents334#         read:  return the current interning dictionary, or None335#336 337all_properties = [property_lexical_handler,338                  property_dom_node,339                  property_declaration_handler,340                  property_xml_string,341                  property_encoding,342                  property_interning_dict]343 344 345class LexicalHandler:346    """Optional SAX2 handler for lexical events.347 348    This handler is used to obtain lexical information about an XML349    document, that is, information about how the document was encoded350    (as opposed to what it contains, which is reported to the351    ContentHandler), such as comments and CDATA marked section352    boundaries.353 354    To set the LexicalHandler of an XMLReader, use the setProperty355    method with the property identifier356    'http://xml.org/sax/properties/lexical-handler'."""357 358    def comment(self, content):359        """Reports a comment anywhere in the document (including the360        DTD and outside the document element).361 362        content is a string that holds the contents of the comment."""363 364    def startDTD(self, name, public_id, system_id):365        """Report the start of the DTD declarations, if the document366        has an associated DTD.367 368        A startEntity event will be reported before declaration events369        from the external DTD subset are reported, and this can be370        used to infer from which subset DTD declarations derive.371 372        name is the name of the document element type, public_id the373        public identifier of the DTD (or None if none were supplied)374        and system_id the system identifier of the external subset (or375        None if none were supplied)."""376 377    def endDTD(self):378        """Signals the end of DTD declarations."""379 380    def startCDATA(self):381        """Reports the beginning of a CDATA marked section.382 383        The contents of the CDATA marked section will be reported384        through the characters event."""385 386    def endCDATA(self):387        """Reports the end of a CDATA marked section."""388