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