Doc/library/xmllib.rst

   1
   2 :mod:`xmllib` --- A parser for XML documents
   3 ============================================
   4
   5 .. module:: xmllib
   6    :synopsis: A parser for XML documents.
   7    :deprecated:
   8 .. moduleauthor:: Sjoerd Mullender <Sjoerd.Mullender@cwi.nl>
   9 .. sectionauthor:: Sjoerd Mullender <Sjoerd.Mullender@cwi.nl>
  10
  11
  12 .. index::
  13    single: XML
  14    single: Extensible Markup Language
  15
  16 .. deprecated:: 2.0
  17    Use :mod:`xml.sax` instead.  The newer XML package includes full support for XML
  18    1.0.
  19
  20 .. versionchanged:: 1.5.2
  21    Added namespace support.
  22
  23 This module defines a class :class:`XMLParser` which serves as the basis  for
  24 parsing text files formatted in XML (Extensible Markup Language).
  25
  26
  27 .. class:: XMLParser()
  28
  29    The :class:`XMLParser` class must be instantiated without arguments. [#]_
  30
  31 This class provides the following interface methods and instance variables:
  32
  33
  34 .. attribute:: XMLParser.attributes
  35
  36    A mapping of element names to mappings.  The latter mapping maps attribute names
  37    that are valid for the element to the default value of  the attribute, or if
  38    there is no default to ``None``.  The default value is the empty dictionary.
  39    This variable is meant to be overridden, not extended since the default is
  40    shared by all instances of :class:`XMLParser`.
  41
  42
  43 .. attribute:: XMLParser.elements
  44
  45    A mapping of element names to tuples.  The tuples contain a function for
  46    handling the start and end tag respectively of the element, or ``None`` if the
  47    method :meth:`unknown_starttag` or :meth:`unknown_endtag` is to be called.  The
  48    default value is the empty dictionary.  This variable is meant to be overridden,
  49    not extended since the default is shared by all instances of :class:`XMLParser`.
  50
  51
  52 .. attribute:: XMLParser.entitydefs
  53
  54    A mapping of entitynames to their values.  The default value contains
  55    definitions for ``'lt'``, ``'gt'``, ``'amp'``, ``'quot'``,  and ``'apos'``.
  56
  57
  58 .. method:: XMLParser.reset()
  59
  60    Reset the instance.  Loses all unprocessed data.  This is called implicitly at
  61    the instantiation time.
  62
  63
  64 .. method:: XMLParser.setnomoretags()
  65
  66    Stop processing tags.  Treat all following input as literal input (CDATA).
  67
  68
  69 .. method:: XMLParser.setliteral()
  70
  71    Enter literal mode (CDATA mode).  This mode is automatically exited when the
  72    close tag matching the last unclosed open tag is encountered.
  73
  74
  75 .. method:: XMLParser.feed(data)
  76
  77    Feed some text to the parser.  It is processed insofar as it consists of
  78    complete tags; incomplete data is buffered until more data is fed or
  79    :meth:`close` is called.
  80
  81
  82 .. method:: XMLParser.close()
  83
  84    Force processing of all buffered data as if it were followed by an end-of-file
  85    mark.  This method may be redefined by a derived class to define additional
  86    processing at the end of the input, but the redefined version should always call
  87    :meth:`close`.
  88
  89
  90 .. method:: XMLParser.translate_references(data)
  91
  92    Translate all entity and character references in *data* and return the
  93    translated string.
  94
  95
  96 .. method:: XMLParser.getnamespace()
  97
  98    Return a mapping of namespace abbreviations to namespace URIs that are currently
  99    in effect.
 100
 101
 102 .. method:: XMLParser.handle_xml(encoding, standalone)
 103
 104    This method is called when the ``<?xml ...?>`` tag is processed. The arguments
 105    are the values of the encoding and standalone attributes  in the tag.  Both
 106    encoding and standalone are optional.  The values passed to :meth:`handle_xml`
 107    default to ``None`` and the string ``'no'`` respectively.
 108
 109
 110 .. method:: XMLParser.handle_doctype(tag, pubid, syslit, data)
 111
 112    .. index::
 113       single: DOCTYPE declaration
 114       single: Formal Public Identifier
 115
 116    This method is called when the ``<!DOCTYPE...>`` declaration is processed.  The
 117    arguments are the tag name of the root element, the Formal Public Identifier (or
 118    ``None`` if not specified), the system identifier, and the uninterpreted
 119    contents of the internal DTD subset as a string (or ``None`` if not present).
 120
 121
 122 .. method:: XMLParser.handle_starttag(tag, method, attributes)
 123
 124    This method is called to handle start tags for which a start tag handler is
 125    defined in the instance variable :attr:`elements`.  The *tag* argument is the
 126    name of the tag, and the *method* argument is the function (method) which should
 127    be used to support semantic interpretation of the start tag.  The *attributes*
 128    argument is a dictionary of attributes, the key being the *name* and the value
 129    being the *value* of the attribute found inside the tag's ``<>`` brackets.
 130    Character and entity references in the *value* have been interpreted.  For
 131    instance, for the start tag ``<A HREF="http://www.cwi.nl/">``, this method would
 132    be called as ``handle_starttag('A', self.elements['A'][0], {'HREF':
 133    'http://www.cwi.nl/'})``.  The base implementation simply calls *method* with
 134    *attributes* as the only argument.
 135
 136
 137 .. method:: XMLParser.handle_endtag(tag, method)
 138
 139    This method is called to handle endtags for which an end tag handler is defined
 140    in the instance variable :attr:`elements`.  The *tag* argument is the name of
 141    the tag, and the *method* argument is the function (method) which should be used
 142    to support semantic interpretation of the end tag.  For instance, for the endtag
 143    ``</A>``, this method would be called as ``handle_endtag('A',
 144    self.elements['A'][1])``.  The base implementation simply calls *method*.
 145
 146
 147 .. method:: XMLParser.handle_data(data)
 148
 149    This method is called to process arbitrary data.  It is intended to be
 150    overridden by a derived class; the base class implementation does nothing.
 151
 152
 153 .. method:: XMLParser.handle_charref(ref)
 154
 155    This method is called to process a character reference of the form ``&#ref;``.
 156    *ref* can either be a decimal number, or a hexadecimal number when preceded by
 157    an ``'x'``. In the base implementation, *ref* must be a number in the range
 158    0-255.  It translates the character to ASCII and calls the method
 159    :meth:`handle_data` with the character as argument.  If *ref* is invalid or out
 160    of range, the method ``unknown_charref(ref)`` is called to handle the error.  A
 161    subclass must override this method to provide support for character references
 162    outside of the ASCII range.
 163
 164
 165 .. method:: XMLParser.handle_comment(comment)
 166
 167    This method is called when a comment is encountered.  The *comment* argument is
 168    a string containing the text between the ``<!--`` and ``-->`` delimiters, but
 169    not the delimiters themselves.  For example, the comment ``<!--text-->`` will
 170    cause this method to be called with the argument ``'text'``.  The default method
 171    does nothing.
 172
 173
 174 .. method:: XMLParser.handle_cdata(data)
 175
 176    This method is called when a CDATA element is encountered.  The *data* argument
 177    is a string containing the text between the ``<![CDATA[`` and ``]]>``
 178    delimiters, but not the delimiters themselves.  For example, the entity
 179    ``<![CDATA[text]]>`` will cause this method to be called with the argument
 180    ``'text'``.  The default method does nothing, and is intended to be overridden.
 181
 182
 183 .. method:: XMLParser.handle_proc(name, data)
 184
 185    This method is called when a processing instruction (PI) is encountered.  The
 186    *name* is the PI target, and the *data* argument is a string containing the text
 187    between the PI target and the closing delimiter, but not the delimiter itself.
 188    For example, the instruction ``<?XML text?>`` will cause this method to be
 189    called with the arguments ``'XML'`` and ``'text'``.  The default method does
 190    nothing.  Note that if a document starts with ``<?xml ..?>``, :meth:`handle_xml`
 191    is called to handle it.
 192
 193
 194 .. method:: XMLParser.handle_special(data)
 195
 196    .. index:: single: ENTITY declaration
 197
 198    This method is called when a declaration is encountered.  The *data* argument is
 199    a string containing the text between the ``<!`` and ``>`` delimiters, but not
 200    the delimiters themselves.  For example, the entity declaration ``<!ENTITY
 201    text>`` will cause this method to be called with the argument ``'ENTITY text'``.
 202    The default method does nothing.  Note that ``<!DOCTYPE ...>`` is handled
 203    separately if it is located at the start of the document.
 204
 205
 206 .. method:: XMLParser.syntax_error(message)
 207
 208    This method is called when a syntax error is encountered.  The *message* is a
 209    description of what was wrong.  The default method  raises a :exc:`RuntimeError`
 210    exception.  If this method is overridden, it is permissible for it to return.
 211    This method is only called when the error can be recovered from.  Unrecoverable
 212    errors raise a :exc:`RuntimeError` without first calling :meth:`syntax_error`.
 213
 214
 215 .. method:: XMLParser.unknown_starttag(tag, attributes)
 216
 217    This method is called to process an unknown start tag.  It is intended to be
 218    overridden by a derived class; the base class implementation does nothing.
 219
 220
 221 .. method:: XMLParser.unknown_endtag(tag)
 222
 223    This method is called to process an unknown end tag.  It is intended to be
 224    overridden by a derived class; the base class implementation does nothing.
 225
 226
 227 .. method:: XMLParser.unknown_charref(ref)
 228
 229    This method is called to process unresolvable numeric character references.  It
 230    is intended to be overridden by a derived class; the base class implementation
 231    does nothing.
 232
 233
 234 .. method:: XMLParser.unknown_entityref(ref)
 235
 236    This method is called to process an unknown entity reference.  It is intended to
 237    be overridden by a derived class; the base class implementation calls
 238    :meth:`syntax_error` to signal an error.
 239
 240
 241 .. seealso::
 242
 243    `Extensible Markup Language (XML) 1.0 <http://www.w3.org/TR/REC-xml>`_
 244       The XML specification, published by the World Wide Web Consortium (W3C), defines
 245       the syntax and processor requirements for XML.  References to additional
 246       material on XML, including translations of the specification, are available at
 247       http://www.w3.org/XML/.
 248
 249    `Python and XML Processing <http://www.python.org/topics/xml/>`_
 250       The Python XML Topic Guide provides a great deal of information on using XML
 251       from Python and links to other sources of information on XML.
 252
 253    `SIG for XML Processing in Python <http://www.python.org/sigs/xml-sig/>`_
 254       The Python XML Special Interest Group is developing substantial support for
 255       processing XML from Python.
 256
 257
 258 .. _xml-namespace:
 259
 260 XML Namespaces
 261 --------------
 262
 263 .. index:: pair: XML; namespaces
 264
 265 This module has support for XML namespaces as defined in the XML Namespaces
 266 proposed recommendation.
 267
 268 Tag and attribute names that are defined in an XML namespace are handled as if
 269 the name of the tag or element consisted of the namespace (the URL that defines
 270 the namespace) followed by a space and the name of the tag or attribute.  For
 271 instance, the tag ``<html xmlns='http://www.w3.org/TR/REC-html40'>`` is treated
 272 as if  the tag name was ``'http://www.w3.org/TR/REC-html40 html'``, and the tag
 273 ``<html:a href='http://frob.com'>`` inside the above mentioned element is
 274 treated as if the tag name were ``'http://www.w3.org/TR/REC-html40 a'`` and the
 275 attribute name as if it were ``'http://www.w3.org/TR/REC-html40 href'``.
 276
 277 An older draft of the XML Namespaces proposal is also recognized, but triggers a
 278 warning.
 279
 280
 281 .. seealso::
 282
 283    `Namespaces in XML <http://www.w3.org/TR/REC-xml-names/>`_
 284       This World Wide Web Consortium recommendation describes the proper syntax and
 285       processing requirements for namespaces in XML.
 286
 287 .. rubric:: Footnotes
 288
 289 .. [#] Actually, a number of keyword arguments are recognized which influence the
 290    parser to accept certain non-standard constructs.  The following keyword
 291    arguments are currently recognized.  The defaults for all of these is ``0``
 292    (false) except for the last one for which the default is ``1`` (true).
 293    *accept_unquoted_attributes* (accept certain attribute values without requiring
 294    quotes), *accept_missing_endtag_name* (accept end tags that look like ``</>``),
 295    *map_case* (map upper case to lower case in tags and attributes), *accept_utf8*
 296    (allow UTF-8 characters in input; this is required according to the XML
 297    standard, but Python does not as yet deal properly with these characters, so
 298    this is not the default), *translate_attribute_references* (don't attempt to
 299    translate character and entity references in attribute values).
 300