rest25/library/pyexpat.rst => rest262/library/pyexpat.rst
2:mod:`xml.parsers.expat` --- Fast XML parsing using Expat
3=========================================================
4
5.. module:: xml.parsers.expat
6   :synopsis: An interface to the Expat non-validating XML parser.
7.. moduleauthor:: Paul Prescod <paul@prescod.net>
8
9
n10-.. % Markup notes:
n10+.. Markup notes:
11-.. % 
11+ 
12-.. % Many of the attributes of the XMLParser objects are callbacks.
12+   Many of the attributes of the XMLParser objects are callbacks.  Since
13-.. % Since signature information must be presented, these are described
13+   signature information must be presented, these are described using the method
14-.. % using the methoddesc environment.  Since they are attributes which
14+   directive.  Since they are attributes which are set by client code, in-text
15-.. % are set by client code, in-text references to these attributes
15+   references to these attributes should be marked using the :member: role.
16-.. % should be marked using the \member macro and should not include the
17-.. % parentheses used when marking functions and methods.
18
19.. versionadded:: 2.0
20
21.. index:: single: Expat
22
n23-The :mod:`xml.parsers.expat` module is a Python interface to the Expat non-
n21+The :mod:`xml.parsers.expat` module is a Python interface to the Expat
24-validating XML parser. The module provides a single extension type,
22+non-validating XML parser. The module provides a single extension type,
25:class:`xmlparser`, that represents the current state of an XML parser.  After
26an :class:`xmlparser` object has been created, various attributes of the object
27can be set to handler functions.  When an XML document is then fed to the
28parser, the handler functions are called for the character data and markup in
29the XML document.
30
31.. index:: module: pyexpat
32
34parser.  Direct use of the :mod:`pyexpat` module is deprecated.
35
36This module provides one exception and one type object:
37
38
39.. exception:: ExpatError
40
41   The exception raised when Expat reports an error.  See section
n42-   :ref:`expaterror-objects`, "ExpatError Exceptions," for more information on
n40+   :ref:`expaterror-objects` for more information on interpreting Expat errors.
43-   interpreting Expat errors.
44
45
46.. exception:: error
47
48   Alias for :exc:`ExpatError`.
49
50
51.. data:: XMLParserType
61
62
63.. function:: ParserCreate([encoding[, namespace_separator]])
64
65   Creates and returns a new :class:`xmlparser` object.   *encoding*, if specified,
66   must be a string naming the encoding  used by the XML data.  Expat doesn't
67   support as many encodings as Python does, and its repertoire of encodings can't
68   be extended; it supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII.  If
n69-   *encoding* is given it will override the implicit or explicit encoding of the
n66+   *encoding* [1]_ is given it will override the implicit or explicit encoding of the
70   document.
71
72   Expat can optionally do XML namespace processing for you, enabled by providing a
73   value for *namespace_separator*.  The value must be a one-character string; a
74   :exc:`ValueError` will be raised if the string has an illegal length (``None``
75   is considered the same as omission).  When namespace processing is enabled,
76   element type names and attribute names that belong to a namespace will be
77   expanded.  The element name passed to the element handlers
117
118   Parses the contents of the string *data*, calling the appropriate handler
119   functions to process the parsed data.  *isfinal* must be true on the final call
120   to this method.  *data* can be the empty string at any time.
121
122
123.. method:: xmlparser.ParseFile(file)
124
n125-   Parse XML data reading from the object *file*.  *file* only needs to provide the
n122+   Parse XML data reading from the object *file*.  *file* only needs to provide
126-   :meth:`read(nbytes)` method, returning the empty string when there's no more
123+   the ``read(nbytes)`` method, returning the empty string when there's no more
127   data.
128
129
130.. method:: xmlparser.SetBase(base)
131
132   Sets the base to be used for resolving relative URIs in system identifiers in
133   declarations.  Resolving relative identifiers is left to the application: this
134   value will be passed through as the *base* argument to the
180
181   .. versionadded:: 2.3
182
183:class:`xmlparser` objects have the following attributes:
184
185
186.. attribute:: xmlparser.buffer_size
187
n188-   The size of the buffer used when :attr:`buffer_text` is true.  This value cannot
n185+   The size of the buffer used when :attr:`buffer_text` is true.
189-   be changed at this time.
186+   A new buffer size can be set by assigning a new integer value
187+   to this attribute.
188+   When the size is changed, the buffer will be flushed.
190
191   .. versionadded:: 2.3
192
n192+   .. versionchanged:: 2.6
193+      The buffer size can now be changed.
193
194.. attribute:: xmlparser.buffer_text
195
196   Setting this to true causes the :class:`xmlparser` object to buffer textual
197   content returned by Expat to avoid multiple calls to the
198   :meth:`CharacterDataHandler` callback whenever possible.  This can improve
199   performance substantially since Expat normally breaks character data into chunks
200   at every line ending.  This attribute is false by default, and may be changed at
879   The requested operation was made on a parser which was finished parsing input,
880   but isn't allowed.  This includes attempts to provide additional input or to
881   stop the parser.
882
883
884.. data:: XML_ERROR_SUSPEND_PE
885   :noindex:
886
t888+ 
889+.. rubric:: Footnotes
890+ 
891+.. [#] The encoding string included in XML output should conform to the
892+   appropriate standards. For example, "UTF-8" is valid, but "UTF8" is
893+   not. See http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl
894+   and http://www.iana.org/assignments/character-sets .
895+ 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op