rest25/library/xmllib.rst => rest262/library/xmllib.rst
f1
2:mod:`xmllib` --- A parser for XML documents
3============================================
4
5.. module:: xmllib
6   :synopsis: A parser for XML documents.
n7+   :deprecated:
7.. moduleauthor:: Sjoerd Mullender <Sjoerd.Mullender@cwi.nl>
8.. sectionauthor:: Sjoerd Mullender <Sjoerd.Mullender@cwi.nl>
9
10
11.. index::
12   single: XML
13   single: Extensible Markup Language
14
22This module defines a class :class:`XMLParser` which serves as the basis  for
23parsing text files formatted in XML (Extensible Markup Language).
24
25
26.. class:: XMLParser()
27
28   The :class:`XMLParser` class must be instantiated without arguments. [#]_
29
n30-This class provides the following interface methods and instance variables:
n31+   This class provides the following interface methods and instance variables:
31
32
n33-.. attribute:: XMLParser.attributes
n34+   .. attribute:: attributes
34
n35-   A mapping of element names to mappings.  The latter mapping maps attribute names
n36+      A mapping of element names to mappings.  The latter mapping maps attribute
36-   that are valid for the element to the default value of  the attribute, or if
37+      names that are valid for the element to the default value of the
37-   there is no default to ``None``.  The default value is the empty dictionary.
38+      attribute, or if there is no default to ``None``.  The default value is
38-   This variable is meant to be overridden, not extended since the default is
39+      the empty dictionary.  This variable is meant to be overridden, not
39-   shared by all instances of :class:`XMLParser`.
40+      extended since the default is shared by all instances of
41+      :class:`XMLParser`.
40
41
n42-.. attribute:: XMLParser.elements
n44+   .. attribute:: elements
43
n44-   A mapping of element names to tuples.  The tuples contain a function for
n46+      A mapping of element names to tuples.  The tuples contain a function for
45-   handling the start and end tag respectively of the element, or ``None`` if the
47+      handling the start and end tag respectively of the element, or ``None`` if
46-   method :meth:`unknown_starttag` or :meth:`unknown_endtag` is to be called.  The
48+      the method :meth:`unknown_starttag` or :meth:`unknown_endtag` is to be
47-   default value is the empty dictionary.  This variable is meant to be overridden,
49+      called.  The default value is the empty dictionary.  This variable is
48-   not extended since the default is shared by all instances of :class:`XMLParser`.
50+      meant to be overridden, not extended since the default is shared by all
51+      instances of :class:`XMLParser`.
49
50
n51-.. attribute:: XMLParser.entitydefs
n54+   .. attribute:: entitydefs
52
n53-   A mapping of entitynames to their values.  The default value contains
n56+      A mapping of entitynames to their values.  The default value contains
54-   definitions for ``'lt'``, ``'gt'``, ``'amp'``, ``'quot'``,  and ``'apos'``.
57+      definitions for ``'lt'``, ``'gt'``, ``'amp'``, ``'quot'``, and ``'apos'``.
55
56
n57-.. method:: XMLParser.reset()
n60+   .. method:: reset()
58
n59-   Reset the instance.  Loses all unprocessed data.  This is called implicitly at
n62+      Reset the instance.  Loses all unprocessed data.  This is called
60-   the instantiation time.
63+      implicitly at the instantiation time.
61
62
n63-.. method:: XMLParser.setnomoretags()
n66+   .. method:: setnomoretags()
64
n65-   Stop processing tags.  Treat all following input as literal input (CDATA).
n68+      Stop processing tags.  Treat all following input as literal input (CDATA).
66
67
n68-.. method:: XMLParser.setliteral()
n71+   .. method:: setliteral()
69
n70-   Enter literal mode (CDATA mode).  This mode is automatically exited when the
n73+      Enter literal mode (CDATA mode).  This mode is automatically exited when
71-   close tag matching the last unclosed open tag is encountered.
74+      the close tag matching the last unclosed open tag is encountered.
72
73
n74-.. method:: XMLParser.feed(data)
n77+   .. method:: feed(data)
75
n76-   Feed some text to the parser.  It is processed insofar as it consists of
n79+      Feed some text to the parser.  It is processed insofar as it consists of
77-   complete tags; incomplete data is buffered until more data is fed or
80+      complete tags; incomplete data is buffered until more data is fed or
78-   :meth:`close` is called.
81+      :meth:`close` is called.
79
80
n81-.. method:: XMLParser.close()
n84+   .. method:: close()
82
n83-   Force processing of all buffered data as if it were followed by an end-of-file
n86+      Force processing of all buffered data as if it were followed by an
84-   mark.  This method may be redefined by a derived class to define additional
87+      end-of-file mark.  This method may be redefined by a derived class to
85-   processing at the end of the input, but the redefined version should always call
88+      define additional processing at the end of the input, but the redefined
86-   :meth:`close`.
89+      version should always call :meth:`close`.
87
88
n89-.. method:: XMLParser.translate_references(data)
n92+   .. method:: translate_references(data)
90
n91-   Translate all entity and character references in *data* and return the
n94+      Translate all entity and character references in *data* and return the
92-   translated string.
95+      translated string.
93
94
n95-.. method:: XMLParser.getnamespace()
n98+   .. method:: getnamespace()
96
n97-   Return a mapping of namespace abbreviations to namespace URIs that are currently
n100+      Return a mapping of namespace abbreviations to namespace URIs that are
98-   in effect.
101+      currently in effect.
99
100
n101-.. method:: XMLParser.handle_xml(encoding, standalone)
n104+   .. method:: handle_xml(encoding, standalone)
102
n103-   This method is called when the ``<?xml ...?>`` tag is processed. The arguments
n106+      This method is called when the ``<?xml ...?>`` tag is processed. The
104-   are the values of the encoding and standalone attributes  in the tag.  Both
107+      arguments are the values of the encoding and standalone attributes in the
105-   encoding and standalone are optional.  The values passed to :meth:`handle_xml`
108+      tag.  Both encoding and standalone are optional.  The values passed to
106-   default to ``None`` and the string ``'no'`` respectively.
109+      :meth:`handle_xml` default to ``None`` and the string ``'no'``
110+      respectively.
107
108
n109-.. method:: XMLParser.handle_doctype(tag, pubid, syslit, data)
n113+   .. method:: handle_doctype(tag, pubid, syslit, data)
110
n111-   .. index::
n115+      .. index::
112-      single: DOCTYPE declaration
116+         single: DOCTYPE declaration
113-      single: Formal Public Identifier
117+         single: Formal Public Identifier
114
n115-   This method is called when the ``<!DOCTYPE...>`` declaration is processed.  The
n119+      This method is called when the ``<!DOCTYPE...>`` declaration is processed.
116-   arguments are the tag name of the root element, the Formal Public Identifier (or
120+      The arguments are the tag name of the root element, the Formal Public
117-   ``None`` if not specified), the system identifier, and the uninterpreted
121+      Identifier (or ``None`` if not specified), the system identifier, and the
118-   contents of the internal DTD subset as a string (or ``None`` if not present).
122+      uninterpreted contents of the internal DTD subset as a string (or ``None``
123+      if not present).
119
120
n121-.. method:: XMLParser.handle_starttag(tag, method, attributes)
n126+   .. method:: handle_starttag(tag, method, attributes)
122
n123-   This method is called to handle start tags for which a start tag handler is
n128+      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
124-   defined in the instance variable :attr:`elements`.  The *tag* argument is the
145+      defined in the instance variable :attr:`elements`.  The *tag* argument is
125-   name of the tag, and the *method* argument is the function (method) which should
146+      the name of the tag, and the *method* argument is the function (method)
126-   be used to support semantic interpretation of the start tag.  The *attributes*
147+      which should be used to support semantic interpretation of the end tag.
127-   argument is a dictionary of attributes, the key being the *name* and the value
148+      For instance, for the endtag ``</A>``, this method would be called as
128-   being the *value* of the attribute found inside the tag's ``<>`` brackets.
149+      ``handle_endtag('A', self.elements['A'][1])``.  The base implementation
129-   Character and entity references in the *value* have been interpreted.  For
150+      simply calls *method*.
130-   instance, for the start tag ``<A HREF="http://www.cwi.nl/">``, this method would
131-   be called as ``handle_starttag('A', self.elements['A'][0], {'HREF':
132-   'http://www.cwi.nl/'})``.  The base implementation simply calls *method* with
133-   *attributes* as the only argument.
134
135
n136-.. method:: XMLParser.handle_endtag(tag, method)
137- 
138-   This method is called to handle endtags for which an end tag handler is defined
139-   in the instance variable :attr:`elements`.  The *tag* argument is the name of
140-   the tag, and the *method* argument is the function (method) which should be used
141-   to support semantic interpretation of the end tag.  For instance, for the endtag
142-   ``</A>``, this method would be called as ``handle_endtag('A',
143-   self.elements['A'][1])``.  The base implementation simply calls *method*.
144- 
145- 
146-.. method:: XMLParser.handle_data(data)
153+   .. method:: handle_data(data)
147
n148-   This method is called to process arbitrary data.  It is intended to be
n155+      This method is called to process arbitrary data.  It is intended to be
149-   overridden by a derived class; the base class implementation does nothing.
156+      overridden by a derived class; the base class implementation does nothing.
150
151
n152-.. method:: XMLParser.handle_charref(ref)
n159+   .. method:: handle_charref(ref)
153
n154-   This method is called to process a character reference of the form ``&#ref;``.
n161+      This method is called to process a character reference of the form
155-   *ref* can either be a decimal number, or a hexadecimal number when preceded by
162+      ``&#ref;``.  *ref* can either be a decimal number, or a hexadecimal number
156-   an ``'x'``. In the base implementation, *ref* must be a number in the range
163+      when preceded by an ``'x'``. In the base implementation, *ref* must be a
157-   0-255.  It translates the character to ASCII and calls the method
164+      number in the range 0-255.  It translates the character to ASCII and calls
158-   :meth:`handle_data` with the character as argument.  If *ref* is invalid or out
165+      the method :meth:`handle_data` with the character as argument.  If *ref*
159-   of range, the method ``unknown_charref(ref)`` is called to handle the error.  A
166+      is invalid or out of range, the method ``unknown_charref(ref)`` is called
160-   subclass must override this method to provide support for character references
167+      to handle the error.  A subclass must override this method to provide
161-   outside of the ASCII range.
168+      support for character references outside of the ASCII range.
162
163
n164-.. method:: XMLParser.handle_comment(comment)
n171+   .. method:: handle_comment(comment)
165
n166-   This method is called when a comment is encountered.  The *comment* argument is
n173+      This method is called when a comment is encountered.  The *comment*
167-   a string containing the text between the ``<!--`` and ``-->`` delimiters, but
174+      argument is a string containing the text between the ``<!--`` and ``-->``
168-   not the delimiters themselves.  For example, the comment ``<!--text-->`` will
175+      delimiters, but not the delimiters themselves.  For example, the comment
169-   cause this method to be called with the argument ``'text'``.  The default method
176+      ``<!--text-->`` will cause this method to be called with the argument
170-   does nothing.
177+      ``'text'``.  The default method does nothing.
171
172
n173-.. method:: XMLParser.handle_cdata(data)
n180+   .. method:: handle_cdata(data)
174
n175-   This method is called when a CDATA element is encountered.  The *data* argument
n182+      This method is called when a CDATA element is encountered.  The *data*
176-   is a string containing the text between the ``<![CDATA[`` and ``]]>``
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 ``>``
177-   delimiters, but not the delimiters themselves.  For example, the entity
207+      delimiters, but not the delimiters themselves.  For example, the entity
178-   ``<![CDATA[text]]>`` will cause this method to be called with the argument
208+      declaration ``<!ENTITY text>`` will cause this method to be called with
179-   ``'text'``.  The default method does nothing, and is intended to be overridden.
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.
180
181
n182-.. method:: XMLParser.handle_proc(name, data)
183- 
184-   This method is called when a processing instruction (PI) is encountered.  The
185-   *name* is the PI target, and the *data* argument is a string containing the text
186-   between the PI target and the closing delimiter, but not the delimiter itself.
187-   For example, the instruction ``<?XML text?>`` will cause this method to be
188-   called with the arguments ``'XML'`` and ``'text'``.  The default method does
189-   nothing.  Note that if a document starts with ``<?xml ..?>``, :meth:`handle_xml`
190-   is called to handle it.
191- 
192- 
193-.. method:: XMLParser.handle_special(data)
194- 
195-   .. index:: single: ENTITY declaration
196- 
197-   This method is called when a declaration is encountered.  The *data* argument is
198-   a string containing the text between the ``<!`` and ``>`` delimiters, but not
199-   the delimiters themselves.  For example, the entity declaration ``<!ENTITY
200-   text>`` will cause this method to be called with the argument ``'ENTITY text'``.
201-   The default method does nothing.  Note that ``<!DOCTYPE ...>`` is handled
202-   separately if it is located at the start of the document.
203- 
204- 
205-.. method:: XMLParser.syntax_error(message)
214+   .. method:: syntax_error(message)
206
n207-   This method is called when a syntax error is encountered.  The *message* is a
n216+      This method is called when a syntax error is encountered.  The *message*
208-   description of what was wrong.  The default method  raises a :exc:`RuntimeError`
217+      is a description of what was wrong.  The default method raises a
209-   exception.  If this method is overridden, it is permissible for it to return.
218+      :exc:`RuntimeError` exception.  If this method is overridden, it is
210-   This method is only called when the error can be recovered from.  Unrecoverable
219+      permissible for it to return.  This method is only called when the error
211-   errors raise a :exc:`RuntimeError` without first calling :meth:`syntax_error`.
220+      can be recovered from.  Unrecoverable errors raise a :exc:`RuntimeError`
221+      without first calling :meth:`syntax_error`.
212
213
n214-.. method:: XMLParser.unknown_starttag(tag, attributes)
n224+   .. method:: unknown_starttag(tag, attributes)
215
n216-   This method is called to process an unknown start tag.  It is intended to be
n226+      This method is called to process an unknown start tag.  It is intended to
217-   overridden by a derived class; the base class implementation does nothing.
227+      be overridden by a derived class; the base class implementation does nothing.
218
219
n220-.. method:: XMLParser.unknown_endtag(tag)
n230+   .. method:: unknown_endtag(tag)
221
n222-   This method is called to process an unknown end tag.  It is intended to be
n232+      This method is called to process an unknown end tag.  It is intended to be
223-   overridden by a derived class; the base class implementation does nothing.
233+      overridden by a derived class; the base class implementation does nothing.
224
225
n226-.. method:: XMLParser.unknown_charref(ref)
n236+   .. method:: unknown_charref(ref)
227
n228-   This method is called to process unresolvable numeric character references.  It
n238+      This method is called to process unresolvable numeric character
229-   is intended to be overridden by a derived class; the base class implementation
239+      references.  It is intended to be overridden by a derived class; the base
230-   does nothing.
240+      class implementation does nothing.
231
232
n233-.. method:: XMLParser.unknown_entityref(ref)
n243+   .. method:: unknown_entityref(ref)
234
n235-   This method is called to process an unknown entity reference.  It is intended to
n245+      This method is called to process an unknown entity reference.  It is
236-   be overridden by a derived class; the base class implementation calls
246+      intended to be overridden by a derived class; the base class
237-   :meth:`syntax_error` to signal an error.
247+      implementation calls :meth:`syntax_error` to signal an error.
238
239
240.. seealso::
241
242   `Extensible Markup Language (XML) 1.0 <http://www.w3.org/TR/REC-xml>`_
243      The XML specification, published by the World Wide Web Consortium (W3C), defines
244      the syntax and processor requirements for XML.  References to additional
245      material on XML, including translations of the specification, are available at
t246-      `<http://www.w3.org/XML/>`_.
t256+      http://www.w3.org/XML/.
247
248   `Python and XML Processing <http://www.python.org/topics/xml/>`_
249      The Python XML Topic Guide provides a great deal of information on using XML
250      from Python and links to other sources of information on XML.
251
252   `SIG for XML Processing in Python <http://www.python.org/sigs/xml-sig/>`_
253      The Python XML Special Interest Group is developing substantial support for
254      processing XML from Python.
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op