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

annotate Doc/lib/xmlsaxhandler.tex @ 21467:4e35fa5d5708 legacy-trunk

Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.

author	Fred Drake <fdrake@acm.org>
date	Tue, 18 Dec 2001 16:31:08 +0000
parents	57c791a5f81c
children	33ea522dd3d2

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
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	20 \begin{classdesc*}{ContentHandler}
15183 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.
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	24 \end{classdesc*}
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	25
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	26 \begin{classdesc*}{DTDHandler}
15183 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).
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	31 \end{classdesc*}
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	32
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	33 \begin{classdesc*}{EntityResolver}
15183 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.
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	38 \end{classdesc*}
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	39
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	40 \begin{classdesc*}{ErrorHandler}
15616 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.
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	45 \end{classdesc*}
15616 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"}\\
21016 57c791a5f81c Fix the default value for feature_namespaces, per discussions on the XML-SIG Fred Drake <fdrake@acm.org> parents: 21012 diff changeset	52 true: Perform Namespace processing.\\
15183 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
21016 57c791a5f81c Fix the default value for feature_namespaces, per discussions on the XML-SIG Fred Drake <fdrake@acm.org> parents: 21012 diff changeset	54 (implies namespace-prefixes; default).\\
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	55 access: (parsing) read-only; (not parsing) read/write
15183 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
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	190 \code{feature_namespaces} feature is enabled (the default).
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	191
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	192 %% 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	193
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	194 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	195 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	196 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	197 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	198 contexts itself, if necessary.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	199
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	200 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	201 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	202 \method{startPrefixMapping()} events will occur before the
21012 8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	203 corresponding \method{startElement()} event, and all
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	204 \method{endPrefixMapping()} events will occur after the
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	205 corresponding \method{endElement()} event, but their order is not
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	206 guaranteed.
15183 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
21012 8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	223 of the element. The object passed as \var{attrs} may be re-used by
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	224 the parser; holding on to a reference to it is not a reliable way to
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	225 keep a copy of the attributes. To keep a copy of the attributes,
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	226 use the \method{copy()} method of the \var{attrs} object.
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	227 \end{methoddesc}
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 \begin{methoddesc}[ContentHandler]{endElement}{name}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	230 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	231
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	232 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	233 as with the startElement event.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	234 \end{methoddesc}
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 \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	237 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	238
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	239 The \var{name} parameter contains the name of the element type as a
21012 8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	240 \code{(\var{uri}, \var{localname})} tuple, the \var{qname} parameter
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	241 contains the raw XML 1.0 name used in the source document, and the
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	242 \var{attrs} parameter holds an instance of the \class{AttributesNS}
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	243 class containing the attributes of the element. If no namespace is
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	244 associated with the element, the \var{uri} component of \var{name}
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	245 will be \code{None}. The object passed as \var{attrs} may be
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	246 re-used by the parser; holding on to a reference to it is not a
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	247 reliable way to keep a copy of the attributes. To keep a copy of
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	248 the attributes, use the \method{copy()} method of the \var{attrs}
8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	249 object.
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	250
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	251 Parsers may set the \var{qname} parameter to \code{None}, unless the
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	252 \code{feature_namespace_prefixes} feature is activated.
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	253 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	254
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	255 \begin{methoddesc}[ContentHandler]{endElementNS}{name, qname}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	256 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	257
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	258 The \var{name} parameter contains the name of the element type, just
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	259 as with the \method{startElementNS()} method, likewise the
6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	260 \var{qname} parameter.
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	261 \end{methoddesc}
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 \begin{methoddesc}[ContentHandler]{characters}{content}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	264 Receive notification of character data.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	265
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	266 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	267 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	268 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	269 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	270 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	271
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	272 \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	273 \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	274
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 15616 diff changeset	275 \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	276 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	277 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	278 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	279 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	280 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	281 \var{length} parameters.}
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	282 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	283
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	284 \begin{methoddesc}[ContentHandler]{ignorableWhitespace}{}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	285 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	286
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	287 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	288 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	289 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	290 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	291
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	292 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	293 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	294 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	295 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	296 information.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	297 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	298
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	299 \begin{methoddesc}[ContentHandler]{processingInstruction}{target, data}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	300 Receive notification of a processing instruction.
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 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	303 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	304 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	305
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	306 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	307 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	308 this method.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	309 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	310
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	311 \begin{methoddesc}[ContentHandler]{skippedEntity}{name}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	312 Receive notification of a skipped entity.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	313
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	314 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	315 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	316 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	317 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	318 external entities, depending on the values of the
20906 6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	319 \code{feature_external_ges} and the
6027fdf1ebda A variety of small cleanups, including one to avoid a margin overrun in the Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	320 \code{feature_external_pes} properties.
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	321 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	322
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 \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	325
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	326 \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	327
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	328 \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	329 Handle a notation declaration event.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	330 \end{methoddesc}
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}[DTDHandler]{unparsedEntityDecl}{name, publicId,
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	333 systemId, ndata}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	334 Handle an unparsed entity declaration event.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	335 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	336
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	337
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	338 \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	339
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	340 \begin{methoddesc}[EntityResolver]{resolveEntity}{publicId, systemId}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	341 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	342 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	343 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	344 \end{methoddesc}
15616 e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	345
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	346
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	347 \subsection{ErrorHandler Objects \label{sax-error-handler}}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	348
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	349 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	350 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	351 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	352 \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	353 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	354 available: warnings, (possibly) recoverable errors, and unrecoverable
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	355 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	356 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	357 raising the passed-in exception object.
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]{error}{exception}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	360 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	361 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	362 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	363 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	364 input document.
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	365 \end{methoddesc}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	366
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	367 \begin{methoddesc}[ErrorHandler]{fatalError}{exception}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	368 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	369 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	370 \end{methoddesc}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	371
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	372 \begin{methoddesc}[ErrorHandler]{warning}{exception}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	373 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	374 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	375 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	376 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	377 \end{methoddesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/xmlsaxhandler.tex @ 21467:4e35fa5d5708 legacy-trunk