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

annotate Doc/lib/xmlsaxhandler.tex @ 28646:193b8aec00ce legacy-trunk

Changes from Jonathan Riehl to allow his pgen extension (PEP 269) to work. This includes some more code that used to be part of pgen in the main parser; I'm okay with that. I'll see if the Windows build needs work next.

author	Guido van Rossum <guido@python.org>
date	Thu, 17 Apr 2003 14:55:42 +0000
parents	33ea522dd3d2
children	462a4c3118bb

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
23989 33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	196 expanded automatically; the \method{startPrefixMapping()} and
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	197 \method{endPrefixMapping()} events supply the information to the
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	198 application to expand prefixes in those contexts itself, if
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	199 necessary.
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	200
23989 33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	201 Note that \method{startPrefixMapping()} and
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	202 \method{endPrefixMapping()} events are not guaranteed to be properly
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	203 nested relative to each-other: all \method{startPrefixMapping()}
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	204 events will occur before the corresponding \method{startElement()}
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	205 event, and all \method{endPrefixMapping()} events will occur after
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	206 the corresponding \method{endElement()} event, but their order is
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	207 not guaranteed.
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	208 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	209
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	210 \begin{methoddesc}[ContentHandler]{endPrefixMapping}{prefix}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	211 End the scope of a prefix-URI mapping.
23989 33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	212
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	213 See \method{startPrefixMapping()} for details. This event will
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	214 always occur after the corresponding \method{endElement()} event,
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	215 but the order of \method{endPrefixMapping()} events is not otherwise
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	216 guaranteed.
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	217 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	218
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	219 \begin{methoddesc}[ContentHandler]{startElement}{name, attrs}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	220 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	221
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	222 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	223 element type as a string and the \var{attrs} parameter holds an
23989 33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	224 object of the \ulink{\class{Attributes}
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	225 interface}{attributes-objects.html} containing the attributes of the
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	226 element. The object passed as \var{attrs} may be re-used by the
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	227 parser; holding on to a reference to it is not a reliable way to
21012 8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	228 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	229 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	230 \end{methoddesc}
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 \begin{methoddesc}[ContentHandler]{endElement}{name}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	233 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	234
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	235 The \var{name} parameter contains the name of the element type, just
23989 33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	236 as with the \method{startElement()} event.
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	237 \end{methoddesc}
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 \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	240 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	241
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	242 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	243 \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	244 contains the raw XML 1.0 name used in the source document, and the
23989 33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	245 \var{attrs} parameter holds an instance of the
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	246 \ulink{\class{AttributesNS} interface}{attributes-ns-objects.html}
33ea522dd3d2 Talk about interfaces rather than implementation classes where appropriate. Fred Drake <fdrake@acm.org> parents: 21016 diff changeset	247 containing the attributes of the element. If no namespace is
21012 8c3219a4dcd6 Clarified a couple of issues for the startElement() handlers: Fred Drake <fdrake@acm.org>* parents: 20906 diff changeset	248 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	249 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	250 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	251 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	252 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	253 object.
15183 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 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	256 \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	257 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	258
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	259 \begin{methoddesc}[ContentHandler]{endElementNS}{name, qname}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	260 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	261
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	262 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	263 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	264 \var{qname} parameter.
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	265 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	266
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	267 \begin{methoddesc}[ContentHandler]{characters}{content}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	268 Receive notification of character data.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	269
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	270 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	271 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	272 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	273 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	274 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	275
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	276 \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	277 \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	278
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 15616 diff changeset	279 \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	280 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	281 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	282 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	283 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	284 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	285 \var{length} parameters.}
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	286 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	287
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	288 \begin{methoddesc}[ContentHandler]{ignorableWhitespace}{}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	289 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	290
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	291 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	292 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	293 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	294 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	295
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	296 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	297 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	298 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	299 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	300 information.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	301 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	302
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	303 \begin{methoddesc}[ContentHandler]{processingInstruction}{target, data}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	304 Receive notification of a processing instruction.
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 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	307 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	308 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	309
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	310 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	311 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	312 this method.
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 \begin{methoddesc}[ContentHandler]{skippedEntity}{name}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	316 Receive notification of a skipped entity.
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 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	319 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	320 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	321 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	322 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	323 \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	324 \code{feature_external_pes} properties.
15183 4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	325 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	326
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 \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	329
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	330 \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	331
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	332 \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	333 Handle a notation declaration event.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	334 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	335
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	336 \begin{methoddesc}[DTDHandler]{unparsedEntityDecl}{name, publicId,
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	337 systemId, ndata}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	338 Handle an unparsed entity declaration event.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	339 \end{methoddesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	340
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	341
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	342 \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	343
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	344 \begin{methoddesc}[EntityResolver]{resolveEntity}{publicId, systemId}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis Fred Drake <fdrake@acm.org> parents: diff changeset	345 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	346 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	347 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	348 \end{methoddesc}
15616 e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	349
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 \subsection{ErrorHandler Objects \label{sax-error-handler}}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	352
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	353 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	354 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	355 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	356 \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	357 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	358 available: warnings, (possibly) recoverable errors, and unrecoverable
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	359 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	360 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	361 raising the passed-in exception object.
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	362
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	363 \begin{methoddesc}[ErrorHandler]{error}{exception}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	364 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	365 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	366 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	367 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	368 input document.
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	369 \end{methoddesc}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	370
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	371 \begin{methoddesc}[ErrorHandler]{fatalError}{exception}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	372 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	373 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	374 \end{methoddesc}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	375
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	376 \begin{methoddesc}[ErrorHandler]{warning}{exception}
e12b650f0fac Added documentation on the ErrorHandler interface. Fred Drake <fdrake@acm.org> parents: 15482 diff changeset	377 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	378 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	379 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	380 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	381 \end{methoddesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/xmlsaxhandler.tex @ 28646:193b8aec00ce legacy-trunk