PageRenderTime 34ms CodeModel.GetById 16ms app.highlight 13ms RepoModel.GetById 1ms app.codeStats 0ms

/Doc/library/xmllib.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 309 lines | 203 code | 106 blank | 0 comment | 0 complexity | 7d21fd36bbbfb877edb7a1f8aedf2e95 MD5 | raw file
  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
 23This module defines a class :class:`XMLParser` which serves as the basis  for
 24parsing 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
269XML Namespaces
270--------------
271
272.. index:: pair: XML; namespaces
273
274This module has support for XML namespaces as defined in the XML Namespaces
275proposed recommendation.
276
277Tag and attribute names that are defined in an XML namespace are handled as if
278the name of the tag or element consisted of the namespace (the URL that defines
279the namespace) followed by a space and the name of the tag or attribute.  For
280instance, the tag ``<html xmlns='http://www.w3.org/TR/REC-html40'>`` is treated
281as 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
283treated as if the tag name were ``'http://www.w3.org/TR/REC-html40 a'`` and the
284attribute name as if it were ``'http://www.w3.org/TR/REC-html40 href'``.
285
286An older draft of the XML Namespaces proposal is also recognized, but triggers a
287warning.
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