Doc/lib/xmlsaxreader.tex

   1 \section{\module{xml.sax.xmlreader} ---
   2          Interface for XML parsers}
   3
   4 \declaremodule{standard}{xml.sax.xmlreader}
   5 \modulesynopsis{Interface which SAX-compliant XML parsers must implement.}
   6 \sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de}
   7 \moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
   8
   9 \versionadded{2.0}
  10
  11
  12 SAX parsers implement the \class{XMLReader} interface. They are
  13 implemented in a Python module, which must provide a function
  14 \function{create_parser()}. This function is invoked by
  15 \function{xml.sax.make_parser()} with no arguments to create a new
  16 parser object.
  17
  18 \begin{classdesc}{XMLReader}{}
  19   Base class which can be inherited by SAX parsers.
  20 \end{classdesc}
  21
  22 \begin{classdesc}{IncrementalParser}{}
  23   In some cases, it is desirable not to parse an input source at once,
  24   but to feed chunks of the document as they get available. Note that
  25   the reader will normally not read the entire file, but read it in
  26   chunks as well; still \method{parse()} won't return until the entire
  27   document is processed. So these interfaces should be used if the
  28   blocking behaviour of \method{parse()} is not desirable.
  29
  30   When the parser is instantiated it is ready to begin accepting data
  31   from the feed method immediately. After parsing has been finished
  32   with a call to close the reset method must be called to make the
  33   parser ready to accept new data, either from feed or using the parse
  34   method.
  35
  36   Note that these methods must \emph{not} be called during parsing,
  37   that is, after parse has been called and before it returns.
  38
  39   By default, the class also implements the parse method of the
  40   XMLReader interface using the feed, close and reset methods of the
  41   IncrementalParser interface as a convenience to SAX 2.0 driver
  42   writers.
  43 \end{classdesc}
  44
  45 \begin{classdesc}{Locator}{}
  46   Interface for associating a SAX event with a document location. A
  47   locator object will return valid results only during calls to
  48   DocumentHandler methods; at any other time, the results are
  49   unpredictable. If information is not available, methods may return
  50   \code{None}.
  51 \end{classdesc}
  52
  53 \begin{classdesc}{InputSource}{\optional{systemId}}
  54   Encapsulation of the information needed by the \class{XMLReader} to
  55   read entities.
  56
  57   This class may include information about the public identifier,
  58   system identifier, byte stream (possibly with character encoding
  59   information) and/or the character stream of an entity.
  60
  61   Applications will create objects of this class for use in the
  62   \method{XMLReader.parse()} method and for returning from
  63   EntityResolver.resolveEntity.
  64
  65   An \class{InputSource} belongs to the application, the
  66   \class{XMLReader} is not allowed to modify \class{InputSource} objects
  67   passed to it from the application, although it may make copies and
  68   modify those.
  69 \end{classdesc}
  70
  71 \begin{classdesc}{AttributesImpl}{attrs}
  72   This is a dictionary-like object which represents the element
  73   attributes in a \method{startElement()} call. In addition to the
  74   most useful dictionary operations, it supports a number of other
  75   methods as described below. Objects of this class should be
  76   instantiated by readers; \var{attrs} must be a dictionary-like
  77   object.
  78 \end{classdesc}
  79
  80 \begin{classdesc}{AttributesNSImpl}{attrs, qnames}
  81   Namespace-aware variant of attributes, which will be passed to
  82   \method{startElementNS()}. It is derived from \class{AttributesImpl},
  83   but understands attribute names as two-tuples of \var{namespaceURI}
  84   and \var{localname}. In addition, it provides a number of methods
  85   expecting qualified names as they appear in the original document.
  86 \end{classdesc}
  87
  88
  89 \subsection{XMLReader Objects \label{xmlreader-objects}}
  90
  91 The \class{XMLReader} interface supports the following methods:
  92
  93 \begin{methoddesc}[XMLReader]{parse}{source}
  94   Process an input source, producing SAX events. The \var{source}
  95   object can be a system identifier (a string identifying the
  96   input source -- typically a file name or an URL), a file-like
  97   object, or an \class{InputSource} object. When \method{parse()}
  98   returns, the input is completely processed, and the parser object
  99   can be discarded or reset. As a limitation, the current implementation
 100   only accepts byte streams; processing of character streams is for
 101   further study.
 102 \end{methoddesc}
 103
 104 \begin{methoddesc}[XMLReader]{getContentHandler}{}
 105   Return the current \class{ContentHandler}.
 106 \end{methoddesc}
 107
 108 \begin{methoddesc}[XMLReader]{setContentHandler}{handler}
 109   Set the current \class{ContentHandler}.  If no
 110   \class{ContentHandler} is set, content events will be discarded.
 111 \end{methoddesc}
 112
 113 \begin{methoddesc}[XMLReader]{getDTDHandler}{}
 114   Return the current \class{DTDHandler}.
 115 \end{methoddesc}
 116
 117 \begin{methoddesc}[XMLReader]{setDTDHandler}{handler}
 118   Set the current \class{DTDHandler}.  If no \class{DTDHandler} is
 119   set, DTD events will be discarded.
 120 \end{methoddesc}
 121
 122 \begin{methoddesc}[XMLReader]{getEntityResolver}{}
 123   Return the current \class{EntityResolver}.
 124 \end{methoddesc}
 125
 126 \begin{methoddesc}[XMLReader]{setEntityResolver}{handler}
 127   Set the current \class{EntityResolver}.  If no
 128   \class{EntityResolver} is set, attempts to resolve an external
 129   entity will result in opening the system identifier for the entity,
 130   and fail if it is not available.
 131 \end{methoddesc}
 132
 133 \begin{methoddesc}[XMLReader]{getErrorHandler}{}
 134   Return the current \class{ErrorHandler}.
 135 \end{methoddesc}
 136
 137 \begin{methoddesc}[XMLReader]{setErrorHandler}{handler}
 138   Set the current error handler.  If no \class{ErrorHandler} is set,
 139   errors will be raised as exceptions, and warnings will be printed.
 140 \end{methoddesc}
 141
 142 \begin{methoddesc}[XMLReader]{setLocale}{locale}
 143   Allow an application to set the locale for errors and warnings.
 144
 145   SAX parsers are not required to provide localization for errors and
 146   warnings; if they cannot support the requested locale, however, they
 147   must throw a SAX exception.  Applications may request a locale change
 148   in the middle of a parse.
 149 \end{methoddesc}
 150
 151 \begin{methoddesc}[XMLReader]{getFeature}{featurename}
 152   Return the current setting for feature \var{featurename}.  If the
 153   feature is not recognized, \exception{SAXNotRecognizedException} is
 154   raised. The well-known featurenames are listed in the module
 155   \module{xml.sax.handler}.
 156 \end{methoddesc}
 157
 158 \begin{methoddesc}[XMLReader]{setFeature}{featurename, value}
 159   Set the \var{featurename} to \var{value}. If the feature is not
 160   recognized, \exception{SAXNotRecognizedException} is raised. If the
 161   feature or its setting is not supported by the parser,
 162   \var{SAXNotSupportedException} is raised.
 163 \end{methoddesc}
 164
 165 \begin{methoddesc}[XMLReader]{getProperty}{propertyname}
 166   Return the current setting for property \var{propertyname}. If the
 167   property is not recognized, a \exception{SAXNotRecognizedException}
 168   is raised. The well-known propertynames are listed in the module
 169   \module{xml.sax.handler}.
 170 \end{methoddesc}
 171
 172 \begin{methoddesc}[XMLReader]{setProperty}{propertyname, value}
 173   Set the \var{propertyname} to \var{value}. If the property is not
 174   recognized, \exception{SAXNotRecognizedException} is raised. If the
 175   property or its setting is not supported by the parser,
 176   \var{SAXNotSupportedException} is raised.
 177 \end{methoddesc}
 178
 179
 180 \subsection{IncrementalParser Objects
 181             \label{incremental-parser-objects}}
 182
 183 Instances of \class{IncrementalParser} offer the following additional
 184 methods:
 185
 186 \begin{methoddesc}[IncrementalParser]{feed}{data}
 187   Process a chunk of \var{data}.
 188 \end{methoddesc}
 189
 190 \begin{methoddesc}[IncrementalParser]{close}{}
 191   Assume the end of the document. That will check well-formedness
 192   conditions that can be checked only at the end, invoke handlers, and
 193   may clean up resources allocated during parsing.
 194 \end{methoddesc}
 195
 196 \begin{methoddesc}[IncrementalParser]{reset}{}
 197   This method is called after close has been called to reset the
 198   parser so that it is ready to parse new documents. The results of
 199   calling parse or feed after close without calling reset are
 200   undefined.
 201 \end{methoddesc}
 202
 203
 204 \subsection{Locator Objects \label{locator-objects}}
 205
 206 Instances of \class{Locator} provide these methods:
 207
 208 \begin{methoddesc}[Locator]{getColumnNumber}{}
 209   Return the column number where the current event ends.
 210 \end{methoddesc}
 211
 212 \begin{methoddesc}[Locator]{getLineNumber}{}
 213   Return the line number where the current event ends.
 214 \end{methoddesc}
 215
 216 \begin{methoddesc}[Locator]{getPublicId}{}
 217   Return the public identifier for the current event.
 218 \end{methoddesc}
 219
 220 \begin{methoddesc}[Locator]{getSystemId}{}
 221   Return the system identifier for the current event.
 222 \end{methoddesc}
 223
 224
 225 \subsection{InputSource Objects \label{input-source-objects}}
 226
 227 \begin{methoddesc}[InputSource]{setPublicId}{id}
 228   Sets the public identifier of this \class{InputSource}.
 229 \end{methoddesc}
 230
 231 \begin{methoddesc}[InputSource]{getPublicId}{}
 232   Returns the public identifier of this \class{InputSource}.
 233 \end{methoddesc}
 234
 235 \begin{methoddesc}[InputSource]{setSystemId}{id}
 236   Sets the system identifier of this \class{InputSource}.
 237 \end{methoddesc}
 238
 239 \begin{methoddesc}[InputSource]{getSystemId}{}
 240   Returns the system identifier of this \class{InputSource}.
 241 \end{methoddesc}
 242
 243 \begin{methoddesc}[InputSource]{setEncoding}{encoding}
 244   Sets the character encoding of this \class{InputSource}.
 245
 246   The encoding must be a string acceptable for an XML encoding
 247   declaration (see section 4.3.3 of the XML recommendation).
 248
 249   The encoding attribute of the \class{InputSource} is ignored if the
 250   \class{InputSource} also contains a character stream.
 251 \end{methoddesc}
 252
 253 \begin{methoddesc}[InputSource]{getEncoding}{}
 254   Get the character encoding of this InputSource.
 255 \end{methoddesc}
 256
 257 \begin{methoddesc}[InputSource]{setByteStream}{bytefile}
 258   Set the byte stream (a Python file-like object which does not
 259   perform byte-to-character conversion) for this input source.
 260
 261   The SAX parser will ignore this if there is also a character stream
 262   specified, but it will use a byte stream in preference to opening a
 263   URI connection itself.
 264
 265   If the application knows the character encoding of the byte stream,
 266   it should set it with the setEncoding method.
 267 \end{methoddesc}
 268
 269 \begin{methoddesc}[InputSource]{getByteStream}{}
 270   Get the byte stream for this input source.
 271
 272   The getEncoding method will return the character encoding for this
 273   byte stream, or None if unknown.
 274 \end{methoddesc}
 275
 276 \begin{methoddesc}[InputSource]{setCharacterStream}{charfile}
 277   Set the character stream for this input source. (The stream must be
 278   a Python 1.6 Unicode-wrapped file-like that performs conversion to
 279   Unicode strings.)
 280
 281   If there is a character stream specified, the SAX parser will ignore
 282   any byte stream and will not attempt to open a URI connection to the
 283   system identifier.
 284 \end{methoddesc}
 285
 286 \begin{methoddesc}[InputSource]{getCharacterStream}{}
 287   Get the character stream for this input source.
 288 \end{methoddesc}
 289
 290
 291 \subsection{AttributesImpl Objects \label{attributes-impl-objects}}
 292
 293 \class{AttributesImpl} objects implement a portion of the mapping
 294 protocol, and the methods \method{copy()}, \method{get()},
 295 \method{has_key()}, \method{items()}, \method{keys()}, and
 296 \method{values()}.  The following methods are also provided:
 297
 298 \begin{methoddesc}[AttributesImpl]{getLength}{}
 299   Return the number of attributes.
 300 \end{methoddesc}
 301
 302 \begin{methoddesc}[AttributesImpl]{getNames}{}
 303   Return the names of the attributes.
 304 \end{methoddesc}
 305
 306 \begin{methoddesc}[AttributesImpl]{getType}{name}
 307   Returns the type of the attribute \var{name}, which is normally
 308   \code{'CDATA'}.
 309 \end{methoddesc}
 310
 311 \begin{methoddesc}[AttributesImpl]{getValue}{name}
 312   Return the value of attribute \var{name}.
 313 \end{methoddesc}
 314
 315 % getValueByQName, getNameByQName, getQNameByName, getQNames available
 316 % here already, but documented only for derived class.
 317
 318
 319 \subsection{AttributesNSImpl Objects \label{attributes-ns-impl-objects}}
 320
 321 \begin{methoddesc}[AttributesNSImpl]{getValueByQName}{name}
 322   Return the value for a qualified name.
 323 \end{methoddesc}
 324
 325 \begin{methoddesc}[AttributesNSImpl]{getNameByQName}{name}
 326   Return the \code{(\var{namespace}, \var{localname})} pair for a
 327   qualified \var{name}.
 328 \end{methoddesc}
 329
 330 \begin{methoddesc}[AttributesNSImpl]{getQNameByName}{name}
 331   Return the qualified name for a \code{(\var{namespace},
 332   \var{localname})} pair.
 333 \end{methoddesc}
 334
 335 \begin{methoddesc}[AttributesNSImpl]{getQNames}{}
 336   Return the qualified names of all attributes.
 337 \end{methoddesc}