cpython-lru_cache-weakref: Doc/lib/xmlsaxhandler.tex annotate

annotate Doc/lib/xmlsaxhandler.tex @ 20737:00a581bdedeb legacy-trunk

When overriding __str__ or __repr__, set the tp_print slot to NULL.

author	Guido van Rossum <guido@python.org>
date	Mon, 29 Oct 2001 14:33:44 +0000
parents	376ee174ecd0
children	6027fdf1ebda

rev	line source
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	1 \section{\module{xml.sax.handler} ---
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	2 Base classes for SAX handlers}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	3
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	4 \declaremodule{standard}{xml.sax.handler}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	5 \modulesynopsis{Base classes for SAX event handlers.}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	6 \sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	7 \moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	8
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	9 \versionadded{2.0}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	10
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	11
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	12 The SAX API defines four kinds of handlers: content handlers, DTD
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	13 handlers, error handlers, and entity resolvers. Applications normally
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	14 only need to implement those interfaces whose events they are
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	15 interested in; they can implement the interfaces in a single object or
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	16 in multiple objects. Handler implementations should inherit from the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	17 base classes provided in the module \module{xml.sax}, so that all
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	18 methods get default implementations.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	19
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	20 \begin{classdesc}{ContentHandler}{}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	21 This is the main callback interface in SAX, and the one most
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	22 important to applications. The order of events in this interface
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	23 mirrors the order of the information in the document.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	24 \end{classdesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	25
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	26 \begin{classdesc}{DTDHandler}{}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	27 Handle DTD events.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	28
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	29 This interface specifies only those DTD events required for basic
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	30 parsing (unparsed entities and attributes).
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	31 \end{classdesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	32
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	33 \begin{classdesc}{EntityResolver}{}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	34 Basic interface for resolving entities. If you create an object
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	35 implementing this interface, then register the object with your
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	36 Parser, the parser will call the method in your object to resolve all
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	37 external entities.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	38 \end{classdesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	39
15616 e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	40 \begin{classdesc}{ErrorHandler}{}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	41 Interface used by the parser to present error and warning messages
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	42 to the application. The methods of this object control whether errors
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	43 are immediately converted to exceptions or are handled in some other
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	44 way.
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	45 \end{classdesc}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	46
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	47 In addition to these classes, \module{xml.sax.handler} provides
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	48 symbolic constants for the feature and property names.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	49
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	50 \begin{datadesc}{feature_namespaces}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	51 Value: \code{"http://xml.org/sax/features/namespaces"}\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	52 true: Perform Namespace processing (default).\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	53 false: Optionally do not perform Namespace processing
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	54 (implies namespace-prefixes).\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	55 access: (parsing) read-only; (not parsing) read/write\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	56 \end{datadesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	57
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	58 \begin{datadesc}{feature_namespace_prefixes}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	59 Value: \code{"http://xml.org/sax/features/namespace-prefixes"}\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	60 true: Report the original prefixed names and attributes used for Namespace
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	61 declarations.\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	62 false: Do not report attributes used for Namespace declarations, and
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	63 optionally do not report original prefixed names (default).\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	64 access: (parsing) read-only; (not parsing) read/write
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	65 \end{datadesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	66
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	67 \begin{datadesc}{feature_string_interning}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	68 Value: \code{"http://xml.org/sax/features/string-interning"}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	69 true: All element names, prefixes, attribute names, Namespace URIs, and
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	70 local names are interned using the built-in intern function.\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	71 false: Names are not necessarily interned, although they may be (default).\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	72 access: (parsing) read-only; (not parsing) read/write
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	73 \end{datadesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	74
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	75 \begin{datadesc}{feature_validation}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	76 Value: \code{"http://xml.org/sax/features/validation"}\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	77 true: Report all validation errors (implies external-general-entities and
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	78 external-parameter-entities).\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	79 false: Do not report validation errors.\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	80 access: (parsing) read-only; (not parsing) read/write
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	81 \end{datadesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	82
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	83 \begin{datadesc}{feature_external_ges}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	84 Value: \code{"http://xml.org/sax/features/external-general-entities"}\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	85 true: Include all external general (text) entities.\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	86 false: Do not include external general entities.\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	87 access: (parsing) read-only; (not parsing) read/write
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	88 \end{datadesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	89
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	90 \begin{datadesc}{feature_external_pes}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	91 Value: \code{"http://xml.org/sax/features/external-parameter-entities"}\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	92 true: Include all external parameter entities, including the external
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	93 DTD subset.\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	94 false: Do not include any external parameter entities, even the external
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	95 DTD subset.\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	96 access: (parsing) read-only; (not parsing) read/write
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	97 \end{datadesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	98
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	99 \begin{datadesc}{all_features}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	100 List of all features.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	101 \end{datadesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	102
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	103 \begin{datadesc}{property_lexical_handler}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	104 Value: \code{"http://xml.org/sax/properties/lexical-handler"}\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	105 data type: xml.sax.sax2lib.LexicalHandler (not supported in Python 2)\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	106 description: An optional extension handler for lexical events like comments.\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	107 access: read/write
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	108 \end{datadesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	109
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	110 \begin{datadesc}{property_declaration_handler}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	111 Value: \code{"http://xml.org/sax/properties/declaration-handler"}\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	112 data type: xml.sax.sax2lib.DeclHandler (not supported in Python 2)\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	113 description: An optional extension handler for DTD-related events other
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	114 than notations and unparsed entities.\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	115 access: read/write
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	116 \end{datadesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	117
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	118 \begin{datadesc}{property_dom_node}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	119 Value: \code{"http://xml.org/sax/properties/dom-node"}\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	120 data type: org.w3c.dom.Node (not supported in Python 2) \\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	121 description: When parsing, the current DOM node being visited if this is
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	122 a DOM iterator; when not parsing, the root DOM node for
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	123 iteration.\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	124 access: (parsing) read-only; (not parsing) read/write
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	125 \end{datadesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	126
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	127 \begin{datadesc}{property_xml_string}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	128 Value: \code{"http://xml.org/sax/properties/xml-string"}\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	129 data type: String\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	130 description: The literal string of characters that was the source for
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	131 the current event.\\
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	132 access: read-only
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	133 \end{datadesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	134
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	135 \begin{datadesc}{all_properties}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	136 List of all known property names.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	137 \end{datadesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	138
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	139
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	140 \subsection{ContentHandler Objects \label{content-handler-objects}}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	141
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	142 Users are expected to subclass \class{ContentHandler} to support their
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	143 application. The following methods are called by the parser on the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	144 appropriate events in the input document:
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	145
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	146 \begin{methoddesc}[ContentHandler]{setDocumentLocator}{locator}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	147 Called by the parser to give the application a locator for locating
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	148 the origin of document events.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	149
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	150 SAX parsers are strongly encouraged (though not absolutely required)
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	151 to supply a locator: if it does so, it must supply the locator to
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	152 the application by invoking this method before invoking any of the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	153 other methods in the DocumentHandler interface.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	154
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	155 The locator allows the application to determine the end position of
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	156 any document-related event, even if the parser is not reporting an
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	157 error. Typically, the application will use this information for
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	158 reporting its own errors (such as character content that does not
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	159 match an application's business rules). The information returned by
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	160 the locator is probably not sufficient for use with a search engine.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	161
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	162 Note that the locator will return correct information only during
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	163 the invocation of the events in this interface. The application
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	164 should not attempt to use it at any other time.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	165 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	166
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	167 \begin{methoddesc}[ContentHandler]{startDocument}{}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	168 Receive notification of the beginning of a document.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	169
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	170 The SAX parser will invoke this method only once, before any other
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	171 methods in this interface or in DTDHandler (except for
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	172 \method{setDocumentLocator()}).
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	173 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	174
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	175 \begin{methoddesc}[ContentHandler]{endDocument}{}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	176 Receive notification of the end of a document.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	177
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	178 The SAX parser will invoke this method only once, and it will be the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	179 last method invoked during the parse. The parser shall not invoke
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	180 this method until it has either abandoned parsing (because of an
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	181 unrecoverable error) or reached the end of input.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	182 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	183
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	184 \begin{methoddesc}[ContentHandler]{startPrefixMapping}{prefix, uri}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	185 Begin the scope of a prefix-URI Namespace mapping.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	186
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	187 The information from this event is not necessary for normal
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	188 Namespace processing: the SAX XML reader will automatically replace
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	189 prefixes for element and attribute names when the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	190 \code{http://xml.org/sax/features/namespaces} feature is true (the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	191 default).
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	192
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	193 %% XXX This is not really the default, is it? MvL
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	194
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	195 There are cases, however, when applications need to use prefixes in
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	196 character data or in attribute values, where they cannot safely be
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	197 expanded automatically; the start/endPrefixMapping event supplies
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	198 the information to the application to expand prefixes in those
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	199 contexts itself, if necessary.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	200
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	201 Note that start/endPrefixMapping events are not guaranteed to be
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	202 properly nested relative to each-other: all
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	203 \method{startPrefixMapping()} events will occur before the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	204 corresponding startElement event, and all \method{endPrefixMapping()}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	205 events will occur after the corresponding \method{endElement()} event,
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	206 but their order is not guaranteed.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	207 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	208
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	209 \begin{methoddesc}[ContentHandler]{endPrefixMapping}{prefix}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	210 End the scope of a prefix-URI mapping.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	211
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	212 See \method{startPrefixMapping()} for details. This event will always
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	213 occur after the corresponding endElement event, but the order of
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	214 endPrefixMapping events is not otherwise guaranteed.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	215 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	216
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	217 \begin{methoddesc}[ContentHandler]{startElement}{name, attrs}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	218 Signals the start of an element in non-namespace mode.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	219
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	220 The \var{name} parameter contains the raw XML 1.0 name of the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	221 element type as a string and the \var{attrs} parameter holds an
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	222 instance of the \class{Attributes} class containing the attributes
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	223 of the element.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	224 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	225
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	226 \begin{methoddesc}[ContentHandler]{endElement}{name}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	227 Signals the end of an element in non-namespace mode.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	228
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	229 The \var{name} parameter contains the name of the element type, just
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	230 as with the startElement event.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	231 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	232
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	233 \begin{methoddesc}[ContentHandler]{startElementNS}{name, qname, attrs}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	234 Signals the start of an element in namespace mode.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	235
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	236 The \var{name} parameter contains the name of the element type as a
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	237 (uri, localname) tuple, the \var{qname} parameter the raw XML 1.0
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	238 name used in the source document, and the \var{attrs} parameter
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	239 holds an instance of the \class{AttributesNS} class containing the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	240 attributes of the element.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	241
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	242 Parsers may set the \var{qname} parameter to \code{None}, unless the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	243 \code{http://xml.org/sax/features/namespace-prefixes} feature is
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	244 activated.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	245 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	246
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	247 \begin{methoddesc}[ContentHandler]{endElementNS}{name, qname}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	248 Signals the end of an element in namespace mode.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	249
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	250 The \var{name} parameter contains the name of the element type, just
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	251 as with the startElementNS event, likewise the \var{qname} parameter.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	252 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	253
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	254 \begin{methoddesc}[ContentHandler]{characters}{content}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	255 Receive notification of character data.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	256
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	257 The Parser will call this method to report each chunk of character
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	258 data. SAX parsers may return all contiguous character data in a
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	259 single chunk, or they may split it into several chunks; however, all
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	260 of the characters in any single event must come from the same
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	261 external entity so that the Locator provides useful information.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	262
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	263 \var{content} may be a Unicode string or a byte string; the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	264 \code{expat} reader module produces always Unicode strings.
15481 07c2e136260c Added a comment for ContentHandler.characters() explaining how to migrate Fred Drake <fdrake@acm.org> parents: 15183 diff changeset	265
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 15616 diff changeset	266 \note{The earlier SAX 1 interface provided by the Python
15481 07c2e136260c Added a comment for ContentHandler.characters() explaining how to migrate Fred Drake <fdrake@acm.org> parents: 15183 diff changeset	267 XML Special Interest Group used a more Java-like interface for this
15482 6838e72f8dd2 Two typos caught by /F; thanks! Fred Drake <fdrake@acm.org> parents: 15481 diff changeset	268 method. Since most parsers used from Python did not take advantage
15481 07c2e136260c Added a comment for ContentHandler.characters() explaining how to migrate Fred Drake <fdrake@acm.org> parents: 15183 diff changeset	269 of the older interface, the simpler signature was chosen to replace
07c2e136260c Added a comment for ContentHandler.characters() explaining how to migrate Fred Drake <fdrake@acm.org> parents: 15183 diff changeset	270 it. To convert old code to the new interface, use \var{content}
07c2e136260c Added a comment for ContentHandler.characters() explaining how to migrate Fred Drake <fdrake@acm.org> parents: 15183 diff changeset	271 instead of slicing content with the old \var{offset} and
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 15616 diff changeset	272 \var{length} parameters.}
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	273 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	274
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	275 \begin{methoddesc}[ContentHandler]{ignorableWhitespace}{}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	276 Receive notification of ignorable whitespace in element content.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	277
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	278 Validating Parsers must use this method to report each chunk
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	279 of ignorable whitespace (see the W3C XML 1.0 recommendation,
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	280 section 2.10): non-validating parsers may also use this method
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	281 if they are capable of parsing and using content models.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	282
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	283 SAX parsers may return all contiguous whitespace in a single
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	284 chunk, or they may split it into several chunks; however, all
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	285 of the characters in any single event must come from the same
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	286 external entity, so that the Locator provides useful
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	287 information.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	288 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	289
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	290 \begin{methoddesc}[ContentHandler]{processingInstruction}{target, data}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	291 Receive notification of a processing instruction.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	292
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	293 The Parser will invoke this method once for each processing
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	294 instruction found: note that processing instructions may occur
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	295 before or after the main document element.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	296
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	297 A SAX parser should never report an XML declaration (XML 1.0,
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	298 section 2.8) or a text declaration (XML 1.0, section 4.3.1) using
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	299 this method.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	300 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	301
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	302 \begin{methoddesc}[ContentHandler]{skippedEntity}{name}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	303 Receive notification of a skipped entity.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	304
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	305 The Parser will invoke this method once for each entity
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	306 skipped. Non-validating processors may skip entities if they have
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	307 not seen the declarations (because, for example, the entity was
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	308 declared in an external DTD subset). All processors may skip
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	309 external entities, depending on the values of the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	310 \code{http://xml.org/sax/features/external-general-entities} and the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	311 \code{http://xml.org/sax/features/external-parameter-entities}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	312 properties.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	313 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	314
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	315
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	316 \subsection{DTDHandler Objects \label{dtd-handler-objects}}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	317
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	318 \class{DTDHandler} instances provide the following methods:
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	319
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	320 \begin{methoddesc}[DTDHandler]{notationDecl}{name, publicId, systemId}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	321 Handle a notation declaration event.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	322 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	323
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	324 \begin{methoddesc}[DTDHandler]{unparsedEntityDecl}{name, publicId,
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	325 systemId, ndata}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	326 Handle an unparsed entity declaration event.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	327 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	328
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	329
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	330 \subsection{EntityResolver Objects \label{entity-resolver-objects}}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	331
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	332 \begin{methoddesc}[EntityResolver]{resolveEntity}{publicId, systemId}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	333 Resolve the system identifier of an entity and return either the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	334 system identifier to read from as a string, or an InputSource to
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	335 read from. The default implementation returns \var{systemId}.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	336 \end{methoddesc}
15616 e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	337
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	338
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	339 \subsection{ErrorHandler Objects \label{sax-error-handler}}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	340
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	341 Objects with this interface are used to receive error and warning
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	342 information from the \class{XMLReader}. If you create an object that
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	343 implements this interface, then register the object with your
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	344 \class{XMLReader}, the parser will call the methods in your object to
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	345 report all warnings and errors. There are three levels of errors
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	346 available: warnings, (possibly) recoverable errors, and unrecoverable
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	347 errors. All methods take a \exception{SAXParseException} as the only
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	348 parameter. Errors and warnings may be converted to an exception by
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	349 raising the passed-in exception object.
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	350
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	351 \begin{methoddesc}[ErrorHandler]{error}{exception}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	352 Called when the parser encounters a recoverable error. If this method
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	353 does not raise an exception, parsing may continue, but further document
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	354 information should not be expected by the application. Allowing the
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	355 parser to continue may allow additional errors to be discovered in the
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	356 input document.
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	357 \end{methoddesc}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	358
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	359 \begin{methoddesc}[ErrorHandler]{fatalError}{exception}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	360 Called when the parser encounters an error it cannot recover from;
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	361 parsing is expected to terminate when this method returns.
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	362 \end{methoddesc}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	363
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	364 \begin{methoddesc}[ErrorHandler]{warning}{exception}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	365 Called when the parser presents minor warning information to the
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	366 application. Parsing is expected to continue when this method returns,
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	367 and document information will continue to be passed to the application.
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	368 Raising an exception in this method will cause parsing to end.
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	369 \end{methoddesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/xmlsaxhandler.tex @ 20737:00a581bdedeb legacy-trunk