FM / library

/usr/share/doc/python3-docs/html/_sources/library/

/usr/share/doc/python3-docs/html/_sources/library

Name	Size	Mode	Actions
2to3.rst.txt	15898	0644	edit dl rm
abc.rst.txt	11805	0644	edit dl rm
aifc.rst.txt	7503	0644	edit dl rm
allos.rst.txt	678	0644	edit dl rm
archiving.rst.txt	440	0644	edit dl rm
argparse.rst.txt	77480	0644	edit dl rm
array.rst.txt	10812	0644	edit dl rm
ast.rst.txt	10159	0644	edit dl rm
asynchat.rst.txt	8528	0644	edit dl rm
asyncio-dev.rst.txt	13398	0644	edit dl rm
asyncio-eventloop.rst.txt	33701	0644	edit dl rm
asyncio-eventloops.rst.txt	7660	0644	edit dl rm
asyncio-protocol.rst.txt	25170	0644	edit dl rm
asyncio-queue.rst.txt	4328	0644	edit dl rm
asyncio-stream.rst.txt	14363	0644	edit dl rm
asyncio-subprocess.rst.txt	15544	0644	edit dl rm
asyncio-sync.rst.txt	9078	0644	edit dl rm
asyncio-task.rst.txt	25406	0644	edit dl rm
asyncio.rst.txt	2272	0644	edit dl rm
asyncore.rst.txt	13624	0644	edit dl rm
atexit.rst.txt	3669	0644	edit dl rm
audioop.rst.txt	10712	0644	edit dl rm
base64.rst.txt	10371	0644	edit dl rm
bdb.rst.txt	12985	0644	edit dl rm
binary.rst.txt	654	0644	edit dl rm
binascii.rst.txt	6539	0644	edit dl rm
binhex.rst.txt	1709	0644	edit dl rm
bisect.rst.txt	5398	0644	edit dl rm
builtins.rst.txt	1465	0644	edit dl rm
bz2.rst.txt	8825	0644	edit dl rm
calendar.rst.txt	10988	0644	edit dl rm
cgi.rst.txt	22650	0644	edit dl rm
cgitb.rst.txt	2918	0644	edit dl rm
chunk.rst.txt	5094	0644	edit dl rm
cmath.rst.txt	9326	0644	edit dl rm
cmd.rst.txt	13795	0644	edit dl rm
code.rst.txt	7817	0644	edit dl rm
codecs.rst.txt	75564	0644	edit dl rm
codeop.rst.txt	3021	0644	edit dl rm
collections.abc.rst.txt	12861	0644	edit dl rm
collections.rst.txt	46063	0644	edit dl rm
colorsys.rst.txt	1820	0644	edit dl rm
compileall.rst.txt	8975	0644	edit dl rm
concurrency.rst.txt	673	0644	edit dl rm
concurrent.futures.rst.txt	16910	0644	edit dl rm
concurrent.rst.txt	171	0644	edit dl rm
configparser.rst.txt	48756	0644	edit dl rm
constants.rst.txt	3331	0644	edit dl rm
contextlib.rst.txt	28175	0644	edit dl rm
copy.rst.txt	3378	0644	edit dl rm
copyreg.rst.txt	2182	0644	edit dl rm
crypt.rst.txt	5122	0644	edit dl rm
crypto.rst.txt	411	0644	edit dl rm
csv.rst.txt	19902	0644	edit dl rm
ctypes.rst.txt	88613	0644	edit dl rm
curses.ascii.rst.txt	8920	0644	edit dl rm
curses.panel.rst.txt	2764	0644	edit dl rm
curses.rst.txt	76397	0644	edit dl rm
custominterp.rst.txt	569	0644	edit dl rm
datatypes.rst.txt	751	0644	edit dl rm
datetime.rst.txt	90524	0644	edit dl rm
dbm.rst.txt	14293	0644	edit dl rm
debug.rst.txt	471	0644	edit dl rm
decimal.rst.txt	74869	0644	edit dl rm
development.rst.txt	704	0644	edit dl rm
difflib.rst.txt	29861	0644	edit dl rm
dis.rst.txt	32567	0644	edit dl rm
distribution.rst.txt	452	0644	edit dl rm
distutils.rst.txt	1974	0644	edit dl rm
doctest.rst.txt	71743	0644	edit dl rm
dummy_threading.rst.txt	784	0644	edit dl rm
email.charset.rst.txt	9293	0644	edit dl rm
email.compat32-message.rst.txt	33493	0644	edit dl rm
email.contentmanager.rst.txt	9112	0644	edit dl rm
email.encoders.rst.txt	2715	0644	edit dl rm
email.errors.rst.txt	4792	0644	edit dl rm
email.examples.rst.txt	1915	0644	edit dl rm
email.generator.rst.txt	13637	0644	edit dl rm
email.header.rst.txt	9188	0644	edit dl rm
email.headerregistry.rst.txt	17957	0644	edit dl rm
email.iterators.rst.txt	2795	0644	edit dl rm
email.message.rst.txt	33008	0644	edit dl rm
email.mime.rst.txt	11721	0644	edit dl rm
email.parser.rst.txt	14092	0644	edit dl rm
email.policy.rst.txt	27022	0644	edit dl rm
email.rst.txt	6785	0644	edit dl rm
email.util.rst.txt	9214	0644	edit dl rm
ensurepip.rst.txt	4987	0644	edit dl rm
enum.rst.txt	32751	0644	edit dl rm
errno.rst.txt	6811	0644	edit dl rm
exceptions.rst.txt	25570	0644	edit dl rm
faulthandler.rst.txt	6136	0644	edit dl rm
fcntl.rst.txt	7152	0644	edit dl rm
filecmp.rst.txt	5623	0644	edit dl rm
fileformats.rst.txt	287	0644	edit dl rm
fileinput.rst.txt	8051	0644	edit dl rm
filesys.rst.txt	961	0644	edit dl rm
fnmatch.rst.txt	3103	0644	edit dl rm
formatter.rst.txt	13242	0644	edit dl rm
fpectl.rst.txt	4180	0644	edit dl rm
fractions.rst.txt	6364	0644	edit dl rm
frameworks.rst.txt	391	0644	edit dl rm
ftplib.rst.txt	17552	0644	edit dl rm
functional.rst.txt	365	0644	edit dl rm
functions.rst.txt	71621	0644	edit dl rm
functools.rst.txt	18503	0644	edit dl rm
gc.rst.txt	9694	0644	edit dl rm
getopt.rst.txt	6557	0644	edit dl rm
getpass.rst.txt	1882	0644	edit dl rm
gettext.rst.txt	25588	0644	edit dl rm
glob.rst.txt	3508	0644	edit dl rm
grp.rst.txt	2417	0644	edit dl rm
gzip.rst.txt	8301	0644	edit dl rm
hashlib.rst.txt	26523	0644	edit dl rm
heapq.rst.txt	13402	0644	edit dl rm
hmac.rst.txt	4020	0644	edit dl rm
html.entities.rst.txt	1319	0644	edit dl rm
html.parser.rst.txt	11275	0644	edit dl rm
html.rst.txt	1304	0644	edit dl rm
http.client.rst.txt	18870	0644	edit dl rm
http.cookiejar.rst.txt	27832	0644	edit dl rm
http.cookies.rst.txt	8645	0644	edit dl rm
http.rst.txt	7096	0644	edit dl rm
http.server.rst.txt	17639	0644	edit dl rm
i18n.rst.txt	408	0644	edit dl rm
idle.rst.txt	25834	0644	edit dl rm
imaplib.rst.txt	20367	0644	edit dl rm
imghdr.rst.txt	2938	0644	edit dl rm
imp.rst.txt	15548	0644	edit dl rm
importlib.rst.txt	53563	0644	edit dl rm
index.rst.txt	2258	0644	edit dl rm
inspect.rst.txt	53928	0644	edit dl rm
internet.rst.txt	992	0644	edit dl rm
intro.rst.txt	2645	0644	edit dl rm
io.rst.txt	40328	0644	edit dl rm
ipaddress.rst.txt	32340	0644	edit dl rm
ipc.rst.txt	649	0644	edit dl rm
itertools.rst.txt	38459	0644	edit dl rm
json.rst.txt	27876	0644	edit dl rm
keyword.rst.txt	617	0644	edit dl rm
language.rst.txt	522	0644	edit dl rm
linecache.rst.txt	2408	0644	edit dl rm
locale.rst.txt	25470	0644	edit dl rm
logging.config.rst.txt	33886	0644	edit dl rm
logging.handlers.rst.txt	42497	0644	edit dl rm
logging.rst.txt	60479	0644	edit dl rm
lzma.rst.txt	17361	0644	edit dl rm
macpath.rst.txt	707	0644	edit dl rm
mailbox.rst.txt	63055	0644	edit dl rm
mailcap.rst.txt	3691	0644	edit dl rm
markup.rst.txt	679	0644	edit dl rm
marshal.rst.txt	4855	0644	edit dl rm
math.rst.txt	14375	0644	edit dl rm
mimetypes.rst.txt	9839	0644	edit dl rm
misc.rst.txt	247	0644	edit dl rm
mm.rst.txt	431	0644	edit dl rm
mmap.rst.txt	11232	0644	edit dl rm
modulefinder.rst.txt	3240	0644	edit dl rm
modules.rst.txt	355	0644	edit dl rm
msilib.rst.txt	18612	0644	edit dl rm
msvcrt.rst.txt	4392	0644	edit dl rm
multiprocessing.rst.txt	104494	0644	edit dl rm
netdata.rst.txt	339	0644	edit dl rm
netrc.rst.txt	3007	0644	edit dl rm
nis.rst.txt	1993	0644	edit dl rm
nntplib.rst.txt	21821	0644	edit dl rm
numbers.rst.txt	8089	0644	edit dl rm
numeric.rst.txt	696	0644	edit dl rm
operator.rst.txt	18989	0644	edit dl rm
optparse.rst.txt	76996	0644	edit dl rm
os.path.rst.txt	16419	0644	edit dl rm
os.rst.txt	137534	0644	edit dl rm
ossaudiodev.rst.txt	17845	0644	edit dl rm
othergui.rst.txt	2822	0644	edit dl rm
parser.rst.txt	15148	0644	edit dl rm
pathlib.rst.txt	30045	0644	edit dl rm
pdb.rst.txt	19454	0644	edit dl rm
persistence.rst.txt	591	0644	edit dl rm
pickle.rst.txt	37440	0644	edit dl rm
pickletools.rst.txt	3729	0644	edit dl rm
pipes.rst.txt	2557	0644	edit dl rm
pkgutil.rst.txt	8730	0644	edit dl rm
platform.rst.txt	9624	0644	edit dl rm
plistlib.rst.txt	7398	0644	edit dl rm
poplib.rst.txt	8197	0644	edit dl rm
posix.rst.txt	3694	0644	edit dl rm
pprint.rst.txt	14274	0644	edit dl rm
profile.rst.txt	27969	0644	edit dl rm
pty.rst.txt	3123	0644	edit dl rm
pwd.rst.txt	2739	0644	edit dl rm
pyclbr.rst.txt	3297	0644	edit dl rm
pydoc.rst.txt	4688	0644	edit dl rm
pyexpat.rst.txt	28620	0644	edit dl rm
python.rst.txt	475	0644	edit dl rm
py_compile.rst.txt	3851	0644	edit dl rm
queue.rst.txt	7268	0644	edit dl rm
quopri.rst.txt	2571	0644	edit dl rm
random.rst.txt	18503	0644	edit dl rm
re.rst.txt	64936	0644	edit dl rm
readline.rst.txt	11943	0644	edit dl rm
reprlib.rst.txt	5162	0644	edit dl rm
resource.rst.txt	12291	0644	edit dl rm
rlcompleter.rst.txt	2294	0644	edit dl rm
runpy.rst.txt	8285	0644	edit dl rm
sched.rst.txt	4842	0644	edit dl rm
secrets.rst.txt	5930	0644	edit dl rm
select.rst.txt	28175	0644	edit dl rm
selectors.rst.txt	8925	0644	edit dl rm
shelve.rst.txt	8390	0644	edit dl rm
shlex.rst.txt	16441	0644	edit dl rm
shutil.rst.txt	26014	0644	edit dl rm
signal.rst.txt	17218	0644	edit dl rm
site.rst.txt	9628	0644	edit dl rm
smtpd.rst.txt	10806	0644	edit dl rm
smtplib.rst.txt	23439	0644	edit dl rm
sndhdr.rst.txt	1994	0644	edit dl rm
socket.rst.txt	68202	0644	edit dl rm
socketserver.rst.txt	23712	0644	edit dl rm
spwd.rst.txt	2958	0644	edit dl rm
sqlite3.rst.txt	39215	0644	edit dl rm
ssl.rst.txt	96021	0644	edit dl rm
stat.rst.txt	9805	0644	edit dl rm
statistics.rst.txt	15301	0644	edit dl rm
stdtypes.rst.txt	179240	0644	edit dl rm
string.rst.txt	35374	0644	edit dl rm
stringprep.rst.txt	4279	0644	edit dl rm
struct.rst.txt	19581	0644	edit dl rm
subprocess.rst.txt	45793	0644	edit dl rm
sunau.rst.txt	7390	0644	edit dl rm
superseded.rst.txt	258	0644	edit dl rm
symbol.rst.txt	975	0644	edit dl rm
symtable.rst.txt	4964	0644	edit dl rm
sys.rst.txt	58273	0644	edit dl rm
sysconfig.rst.txt	8749	0644	edit dl rm
syslog.rst.txt	4302	0644	edit dl rm
tabnanny.rst.txt	2007	0644	edit dl rm
tarfile.rst.txt	31749	0644	edit dl rm
telnetlib.rst.txt	7899	0644	edit dl rm
tempfile.rst.txt	13857	0644	edit dl rm
termios.rst.txt	3751	0644	edit dl rm
test.rst.txt	25764	0644	edit dl rm
text.rst.txt	584	0644	edit dl rm
textwrap.rst.txt	10519	0644	edit dl rm
threading.rst.txt	39257	0644	edit dl rm
time.rst.txt	32967	0644	edit dl rm
timeit.rst.txt	13000	0644	edit dl rm
tk.rst.txt	1639	0644	edit dl rm
tkinter.rst.txt	33027	0644	edit dl rm
tkinter.scrolledtext.rst.txt	1255	0644	edit dl rm
tkinter.tix.rst.txt	22653	0644	edit dl rm
tkinter.ttk.rst.txt	58489	0644	edit dl rm
token.rst.txt	2607	0644	edit dl rm
tokenize.rst.txt	10002	0644	edit dl rm
trace.rst.txt	6914	0644	edit dl rm
traceback.rst.txt	17854	0644	edit dl rm
tracemalloc.rst.txt	22089	0644	edit dl rm
tty.rst.txt	1097	0644	edit dl rm
turtle.rst.txt	71221	0644	edit dl rm
types.rst.txt	9999	0644	edit dl rm
typing.rst.txt	34332	0644	edit dl rm
undoc.rst.txt	780	0644	edit dl rm
unicodedata.rst.txt	5762	0644	edit dl rm
unittest.mock-examples.rst.txt	46206	0644	edit dl rm
unittest.mock.rst.txt	85991	0644	edit dl rm
unittest.rst.txt	93304	0644	edit dl rm
unix.rst.txt	446	0644	edit dl rm
urllib.error.rst.txt	2199	0644	edit dl rm
urllib.parse.rst.txt	27332	0644	edit dl rm
urllib.request.rst.txt	59360	0644	edit dl rm
urllib.robotparser.rst.txt	2969	0644	edit dl rm
urllib.rst.txt	466	0644	edit dl rm
uu.rst.txt	2387	0644	edit dl rm
uuid.rst.txt	8760	0644	edit dl rm
venv.rst.txt	20621	0644	edit dl rm
warnings.rst.txt	20152	0644	edit dl rm
wave.rst.txt	6870	0644	edit dl rm
weakref.rst.txt	21328	0644	edit dl rm
webbrowser.rst.txt	9783	0644	edit dl rm
windows.rst.txt	272	0644	edit dl rm
winreg.rst.txt	24073	0644	edit dl rm
winsound.rst.txt	5134	0644	edit dl rm
wsgiref.rst.txt	33047	0644	edit dl rm
xdrlib.rst.txt	8078	0644	edit dl rm
xml.dom.minidom.rst.txt	10198	0644	edit dl rm
xml.dom.pulldom.rst.txt	5186	0644	edit dl rm
xml.dom.rst.txt	39507	0644	edit dl rm
xml.etree.elementtree.rst.txt	43871	0644	edit dl rm
xml.rst.txt	6071	0644	edit dl rm
xml.sax.handler.rst.txt	15399	0644	edit dl rm
xml.sax.reader.rst.txt	12133	0644	edit dl rm
xml.sax.rst.txt	7159	0644	edit dl rm
xml.sax.utils.rst.txt	3901	0644	edit dl rm
xmlrpc.client.rst.txt	23071	0644	edit dl rm
xmlrpc.rst.txt	475	0644	edit dl rm
xmlrpc.server.rst.txt	14990	0644	edit dl rm
zipapp.rst.txt	17392	0644	edit dl rm
zipfile.rst.txt	24005	0644	edit dl rm
zipimport.rst.txt	5805	0644	edit dl rm
zlib.rst.txt	13912	0644	edit dl rm
_dummy_thread.rst.txt	762	0644	edit dl rm
_thread.rst.txt	6886	0644	edit dl rm
__future__.rst.txt	5245	0644	edit dl rm
__main__.rst.txt	904	0644	edit dl rm

Edit: /usr/share/doc/python3-docs/html/_sources/library/pyexpat.rst.txt (28620B)

:mod:`xml.parsers.expat` --- Fast XML parsing using Expat
=========================================================

.. module:: xml.parsers.expat
   :synopsis: An interface to the Expat non-validating XML parser.

.. moduleauthor:: Paul Prescod <paul@prescod.net>

--------------

.. Markup notes:

Many of the attributes of the XMLParser objects are callbacks.  Since
   signature information must be presented, these are described using the method
   directive.  Since they are attributes which are set by client code, in-text
   references to these attributes should be marked using the :member: role.

.. warning::

The :mod:`pyexpat` module is not secure against maliciously
   constructed data.  If you need to parse untrusted or unauthenticated data see
   :ref:`xml-vulnerabilities`.

.. index:: single: Expat

The :mod:`xml.parsers.expat` module is a Python interface to the Expat
non-validating XML parser. The module provides a single extension type,
:class:`xmlparser`, that represents the current state of an XML parser.  After
an :class:`xmlparser` object has been created, various attributes of the object
can be set to handler functions.  When an XML document is then fed to the
parser, the handler functions are called for the character data and markup in
the XML document.

.. index:: module: pyexpat

This module uses the :mod:`pyexpat` module to provide access to the Expat
parser.  Direct use of the :mod:`pyexpat` module is deprecated.

This module provides one exception and one type object:

.. exception:: ExpatError

The exception raised when Expat reports an error.  See section
   :ref:`expaterror-objects` for more information on interpreting Expat errors.

.. exception:: error

Alias for :exc:`ExpatError`.

.. data:: XMLParserType

The type of the return values from the :func:`ParserCreate` function.

The :mod:`xml.parsers.expat` module contains two functions:

.. function:: ErrorString(errno)

Returns an explanatory string for a given error number *errno*.

.. function:: ParserCreate(encoding=None, namespace_separator=None)

Creates and returns a new :class:`xmlparser` object.   *encoding*, if specified,
   must be a string naming the encoding  used by the XML data.  Expat doesn't
   support as many encodings as Python does, and its repertoire of encodings can't
   be extended; it supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII.  If
   *encoding* [1]_ is given it will override the implicit or explicit encoding of the
   document.

Expat can optionally do XML namespace processing for you, enabled by providing a
   value for *namespace_separator*.  The value must be a one-character string; a
   :exc:`ValueError` will be raised if the string has an illegal length (``None``
   is considered the same as omission).  When namespace processing is enabled,
   element type names and attribute names that belong to a namespace will be
   expanded.  The element name passed to the element handlers
   :attr:`StartElementHandler` and :attr:`EndElementHandler` will be the
   concatenation of the namespace URI, the namespace separator character, and the
   local part of the name.  If the namespace separator is a zero byte (``chr(0)``)
   then the namespace URI and the local part will be concatenated without any
   separator.

For example, if *namespace_separator* is set to a space character (``' '``) and
   the following document is parsed:

.. code-block:: xml

<?xml version="1.0"?>
      <root xmlns    = "http://default-namespace.org/"
            xmlns:py = "http://www.python.org/ns/">
        <py:elem1 />
        <elem2 xmlns="" />
      </root>

:attr:`StartElementHandler` will receive the following strings for each
   element::

http://default-namespace.org/ root
      http://www.python.org/ns/ elem1
      elem2

Due to limitations in the ``Expat`` library used by :mod:`pyexpat`,
   the :class:`xmlparser` instance returned can only be used to parse a single
   XML document.  Call ``ParserCreate`` for each document to provide unique
   parser instances.

.. seealso::

`The Expat XML Parser <http://www.libexpat.org/>`_
      Home page of the Expat project.

.. _xmlparser-objects:

XMLParser Objects
-----------------

:class:`xmlparser` objects have the following methods:

.. method:: xmlparser.Parse(data[, isfinal])

Parses the contents of the string *data*, calling the appropriate handler
   functions to process the parsed data.  *isfinal* must be true on the final call
   to this method; it allows the parsing of a single file in fragments,
   not the submission of multiple files.
   *data* can be the empty string at any time.

.. method:: xmlparser.ParseFile(file)

Parse XML data reading from the object *file*.  *file* only needs to provide
   the ``read(nbytes)`` method, returning the empty string when there's no more
   data.

.. method:: xmlparser.SetBase(base)

Sets the base to be used for resolving relative URIs in system identifiers in
   declarations.  Resolving relative identifiers is left to the application: this
   value will be passed through as the *base* argument to the
   :func:`ExternalEntityRefHandler`, :func:`NotationDeclHandler`, and
   :func:`UnparsedEntityDeclHandler` functions.

.. method:: xmlparser.GetBase()

Returns a string containing the base set by a previous call to :meth:`SetBase`,
   or ``None`` if  :meth:`SetBase` hasn't been called.

.. method:: xmlparser.GetInputContext()

Returns the input data that generated the current event as a string. The data is
   in the encoding of the entity which contains the text. When called while an
   event handler is not active, the return value is ``None``.

.. method:: xmlparser.ExternalEntityParserCreate(context[, encoding])

Create a "child" parser which can be used to parse an external parsed entity
   referred to by content parsed by the parent parser.  The *context* parameter
   should be the string passed to the :meth:`ExternalEntityRefHandler` handler
   function, described below. The child parser is created with the
   :attr:`ordered_attributes` and :attr:`specified_attributes` set to the values of
   this parser.

.. method:: xmlparser.SetParamEntityParsing(flag)

Control parsing of parameter entities (including the external DTD subset).
   Possible *flag* values are :const:`XML_PARAM_ENTITY_PARSING_NEVER`,
   :const:`XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE` and
   :const:`XML_PARAM_ENTITY_PARSING_ALWAYS`.  Return true if setting the flag
   was successful.

.. method:: xmlparser.UseForeignDTD([flag])

Calling this with a true value for *flag* (the default) will cause Expat to call
   the :attr:`ExternalEntityRefHandler` with :const:`None` for all arguments to
   allow an alternate DTD to be loaded.  If the document does not contain a
   document type declaration, the :attr:`ExternalEntityRefHandler` will still be
   called, but the :attr:`StartDoctypeDeclHandler` and
   :attr:`EndDoctypeDeclHandler` will not be called.

Passing a false value for *flag* will cancel a previous call that passed a true
   value, but otherwise has no effect.

This method can only be called before the :meth:`Parse` or :meth:`ParseFile`
   methods are called; calling it after either of those have been called causes
   :exc:`ExpatError` to be raised with the :attr:`code` attribute set to
   ``errors.codes[errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING]``.

:class:`xmlparser` objects have the following attributes:

.. attribute:: xmlparser.buffer_size

The size of the buffer used when :attr:`buffer_text` is true.
   A new buffer size can be set by assigning a new integer value
   to this attribute.
   When the size is changed, the buffer will be flushed.

.. attribute:: xmlparser.buffer_text

Setting this to true causes the :class:`xmlparser` object to buffer textual
   content returned by Expat to avoid multiple calls to the
   :meth:`CharacterDataHandler` callback whenever possible.  This can improve
   performance substantially since Expat normally breaks character data into chunks
   at every line ending.  This attribute is false by default, and may be changed at
   any time.

.. attribute:: xmlparser.buffer_used

If :attr:`buffer_text` is enabled, the number of bytes stored in the buffer.
   These bytes represent UTF-8 encoded text.  This attribute has no meaningful
   interpretation when :attr:`buffer_text` is false.

.. attribute:: xmlparser.ordered_attributes

Setting this attribute to a non-zero integer causes the attributes to be
   reported as a list rather than a dictionary.  The attributes are presented in
   the order found in the document text.  For each attribute, two list entries are
   presented: the attribute name and the attribute value.  (Older versions of this
   module also used this format.)  By default, this attribute is false; it may be
   changed at any time.

.. attribute:: xmlparser.specified_attributes

If set to a non-zero integer, the parser will report only those attributes which
   were specified in the document instance and not those which were derived from
   attribute declarations.  Applications which set this need to be especially
   careful to use what additional information is available from the declarations as
   needed to comply with the standards for the behavior of XML processors.  By
   default, this attribute is false; it may be changed at any time.

The following attributes contain values relating to the most recent error
encountered by an :class:`xmlparser` object, and will only have correct values
once a call to :meth:`Parse` or :meth:`ParseFile` has raised an
:exc:`xml.parsers.expat.ExpatError` exception.

.. attribute:: xmlparser.ErrorByteIndex

Byte index at which an error occurred.

.. attribute:: xmlparser.ErrorCode

Numeric code specifying the problem.  This value can be passed to the
   :func:`ErrorString` function, or compared to one of the constants defined in the
   ``errors`` object.

.. attribute:: xmlparser.ErrorColumnNumber

Column number at which an error occurred.

.. attribute:: xmlparser.ErrorLineNumber

Line number at which an error occurred.

The following attributes contain values relating to the current parse location
in an :class:`xmlparser` object.  During a callback reporting a parse event they
indicate the location of the first of the sequence of characters that generated
the event.  When called outside of a callback, the position indicated will be
just past the last parse event (regardless of whether there was an associated
callback).

.. attribute:: xmlparser.CurrentByteIndex

Current byte index in the parser input.

.. attribute:: xmlparser.CurrentColumnNumber

Current column number in the parser input.

.. attribute:: xmlparser.CurrentLineNumber

Current line number in the parser input.

Here is the list of handlers that can be set.  To set a handler on an
:class:`xmlparser` object *o*, use ``o.handlername = func``.  *handlername* must
be taken from the following list, and *func* must be a callable object accepting
the correct number of arguments.  The arguments are all strings, unless
otherwise stated.

.. method:: xmlparser.XmlDeclHandler(version, encoding, standalone)

Called when the XML declaration is parsed.  The XML declaration is the
   (optional) declaration of the applicable version of the XML recommendation, the
   encoding of the document text, and an optional "standalone" declaration.
   *version* and *encoding* will be strings, and *standalone* will be ``1`` if the
   document is declared standalone, ``0`` if it is declared not to be standalone,
   or ``-1`` if the standalone clause was omitted. This is only available with
   Expat version 1.95.0 or newer.

.. method:: xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset)

Called when Expat begins parsing the document type declaration (``<!DOCTYPE
   ...``).  The *doctypeName* is provided exactly as presented.  The *systemId* and
   *publicId* parameters give the system and public identifiers if specified, or
   ``None`` if omitted.  *has_internal_subset* will be true if the document
   contains and internal document declaration subset. This requires Expat version
   1.2 or newer.

.. method:: xmlparser.EndDoctypeDeclHandler()

Called when Expat is done parsing the document type declaration. This requires
   Expat version 1.2 or newer.

.. method:: xmlparser.ElementDeclHandler(name, model)

Called once for each element type declaration.  *name* is the name of the
   element type, and *model* is a representation of the content model.

.. method:: xmlparser.AttlistDeclHandler(elname, attname, type, default, required)

Called for each declared attribute for an element type.  If an attribute list
   declaration declares three attributes, this handler is called three times, once
   for each attribute.  *elname* is the name of the element to which the
   declaration applies and *attname* is the name of the attribute declared.  The
   attribute type is a string passed as *type*; the possible values are
   ``'CDATA'``, ``'ID'``, ``'IDREF'``, ... *default* gives the default value for
   the attribute used when the attribute is not specified by the document instance,
   or ``None`` if there is no default value (``#IMPLIED`` values).  If the
   attribute is required to be given in the document instance, *required* will be
   true. This requires Expat version 1.95.0 or newer.

.. method:: xmlparser.StartElementHandler(name, attributes)

Called for the start of every element.  *name* is a string containing the
   element name, and *attributes* is the element attributes. If
   :attr:`ordered_attributes` is true, this is a list (see
   :attr:`ordered_attributes` for a full description). Otherwise it's a
   dictionary mapping names to values.

.. method:: xmlparser.EndElementHandler(name)

Called for the end of every element.

.. method:: xmlparser.ProcessingInstructionHandler(target, data)

Called for every processing instruction.

.. method:: xmlparser.CharacterDataHandler(data)

Called for character data.  This will be called for normal character data, CDATA
   marked content, and ignorable whitespace.  Applications which must distinguish
   these cases can use the :attr:`StartCdataSectionHandler`,
   :attr:`EndCdataSectionHandler`, and :attr:`ElementDeclHandler` callbacks to
   collect the required information.

.. method:: xmlparser.UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName)

Called for unparsed (NDATA) entity declarations.  This is only present for
   version 1.2 of the Expat library; for more recent versions, use
   :attr:`EntityDeclHandler` instead.  (The underlying function in the Expat
   library has been declared obsolete.)

.. method:: xmlparser.EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName)

Called for all entity declarations.  For parameter and internal entities,
   *value* will be a string giving the declared contents of the entity; this will
   be ``None`` for external entities.  The *notationName* parameter will be
   ``None`` for parsed entities, and the name of the notation for unparsed
   entities. *is_parameter_entity* will be true if the entity is a parameter entity
   or false for general entities (most applications only need to be concerned with
   general entities). This is only available starting with version 1.95.0 of the
   Expat library.

.. method:: xmlparser.NotationDeclHandler(notationName, base, systemId, publicId)

Called for notation declarations.  *notationName*, *base*, and *systemId*, and
   *publicId* are strings if given.  If the public identifier is omitted,
   *publicId* will be ``None``.

.. method:: xmlparser.StartNamespaceDeclHandler(prefix, uri)

Called when an element contains a namespace declaration.  Namespace declarations
   are processed before the :attr:`StartElementHandler` is called for the element
   on which declarations are placed.

.. method:: xmlparser.EndNamespaceDeclHandler(prefix)

Called when the closing tag is reached for an element  that contained a
   namespace declaration.  This is called once for each namespace declaration on
   the element in the reverse of the order for which the
   :attr:`StartNamespaceDeclHandler` was called to indicate the start of each
   namespace declaration's scope.  Calls to this handler are made after the
   corresponding :attr:`EndElementHandler` for the end of the element.

.. method:: xmlparser.CommentHandler(data)

Called for comments.  *data* is the text of the comment, excluding the leading
   ``'<!-``\ ``-'`` and trailing ``'-``\ ``->'``.

.. method:: xmlparser.StartCdataSectionHandler()

Called at the start of a CDATA section.  This and :attr:`EndCdataSectionHandler`
   are needed to be able to identify the syntactical start and end for CDATA
   sections.

.. method:: xmlparser.EndCdataSectionHandler()

Called at the end of a CDATA section.

.. method:: xmlparser.DefaultHandler(data)

Called for any characters in the XML document for which no applicable handler
   has been specified.  This means characters that are part of a construct which
   could be reported, but for which no handler has been supplied.

.. method:: xmlparser.DefaultHandlerExpand(data)

This is the same as the :func:`DefaultHandler`,  but doesn't inhibit expansion
   of internal entities. The entity reference will not be passed to the default
   handler.

.. method:: xmlparser.NotStandaloneHandler()

Called if the XML document hasn't been declared as being a standalone document.
   This happens when there is an external subset or a reference to a parameter
   entity, but the XML declaration does not set standalone to ``yes`` in an XML
   declaration.  If this handler returns ``0``, then the parser will raise an
   :const:`XML_ERROR_NOT_STANDALONE` error.  If this handler is not set, no
   exception is raised by the parser for this condition.

.. method:: xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId)

Called for references to external entities.  *base* is the current base, as set
   by a previous call to :meth:`SetBase`.  The public and system identifiers,
   *systemId* and *publicId*, are strings if given; if the public identifier is not
   given, *publicId* will be ``None``.  The *context* value is opaque and should
   only be used as described below.

For external entities to be parsed, this handler must be implemented. It is
   responsible for creating the sub-parser using
   ``ExternalEntityParserCreate(context)``, initializing it with the appropriate
   callbacks, and parsing the entity.  This handler should return an integer; if it
   returns ``0``, the parser will raise an
   :const:`XML_ERROR_EXTERNAL_ENTITY_HANDLING` error, otherwise parsing will
   continue.

If this handler is not provided, external entities are reported by the
   :attr:`DefaultHandler` callback, if provided.

.. _expaterror-objects:

ExpatError Exceptions
---------------------

.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

:exc:`ExpatError` exceptions have a number of interesting attributes:

.. attribute:: ExpatError.code

Expat's internal error number for the specific error.  The
   :data:`errors.messages <xml.parsers.expat.errors.messages>` dictionary maps
   these error numbers to Expat's error messages.  For example::

from xml.parsers.expat import ParserCreate, ExpatError, errors

p = ParserCreate()
      try:
          p.Parse(some_xml_document)
      except ExpatError as err:
          print("Error:", errors.messages[err.code])

The :mod:`~xml.parsers.expat.errors` module also provides error message
   constants and a dictionary :data:`~xml.parsers.expat.errors.codes` mapping
   these messages back to the error codes, see below.

.. attribute:: ExpatError.lineno

Line number on which the error was detected.  The first line is numbered ``1``.

.. attribute:: ExpatError.offset

Character offset into the line where the error occurred.  The first column is
   numbered ``0``.

.. _expat-example:

Example
-------

The following program defines three handlers that just print out their
arguments. ::

import xml.parsers.expat

# 3 handler functions
   def start_element(name, attrs):
       print('Start element:', name, attrs)
   def end_element(name):
       print('End element:', name)
   def char_data(data):
       print('Character data:', repr(data))

p = xml.parsers.expat.ParserCreate()

p.StartElementHandler = start_element
   p.EndElementHandler = end_element
   p.CharacterDataHandler = char_data

p.Parse("""<?xml version="1.0"?>
   <parent id="top"><child1 name="paul">Text goes here</child1>
   <child2 name="fred">More text</child2>
   </parent>""", 1)

The output from this program is::

Start element: parent {'id': 'top'}
   Start element: child1 {'name': 'paul'}
   Character data: 'Text goes here'
   End element: child1
   Character data: '\n'
   Start element: child2 {'name': 'fred'}
   Character data: 'More text'
   End element: child2
   Character data: '\n'
   End element: parent

.. _expat-content-models:

Content Model Descriptions
--------------------------

.. module:: xml.parsers.expat.model

.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

Content models are described using nested tuples.  Each tuple contains four
values: the type, the quantifier, the name, and a tuple of children.  Children
are simply additional content model descriptions.

The values of the first two fields are constants defined in the
:mod:`xml.parsers.expat.model` module.  These constants can be collected in two
groups: the model type group and the quantifier group.

The constants in the model type group are:

.. data:: XML_CTYPE_ANY
   :noindex:

The element named by the model name was declared to have a content model of
   ``ANY``.

.. data:: XML_CTYPE_CHOICE
   :noindex:

The named element allows a choice from a number of options; this is used for
   content models such as ``(A | B | C)``.

.. data:: XML_CTYPE_EMPTY
   :noindex:

Elements which are declared to be ``EMPTY`` have this model type.

.. data:: XML_CTYPE_MIXED
   :noindex:

.. data:: XML_CTYPE_NAME
   :noindex:

.. data:: XML_CTYPE_SEQ
   :noindex:

Models which represent a series of models which follow one after the other are
   indicated with this model type.  This is used for models such as ``(A, B, C)``.

The constants in the quantifier group are:

.. data:: XML_CQUANT_NONE
   :noindex:

No modifier is given, so it can appear exactly once, as for ``A``.

.. data:: XML_CQUANT_OPT
   :noindex:

The model is optional: it can appear once or not at all, as for ``A?``.

.. data:: XML_CQUANT_PLUS
   :noindex:

The model must occur one or more times (like ``A+``).

.. data:: XML_CQUANT_REP
   :noindex:

The model must occur zero or more times, as for ``A*``.

.. _expat-errors:

Expat error constants
---------------------

.. module:: xml.parsers.expat.errors

The following constants are provided in the :mod:`xml.parsers.expat.errors`
module.  These constants are useful in interpreting some of the attributes of
the :exc:`ExpatError` exception objects raised when an error has occurred.
Since for backwards compatibility reasons, the constants' value is the error
*message* and not the numeric error *code*, you do this by comparing its
:attr:`code` attribute with
:samp:`errors.codes[errors.XML_ERROR_{CONSTANT_NAME}]`.

The ``errors`` module has the following attributes:

.. data:: codes

A dictionary mapping numeric error codes to their string descriptions.

.. versionadded:: 3.2

.. data:: messages

A dictionary mapping string descriptions to their error codes.

.. versionadded:: 3.2

.. data:: XML_ERROR_ASYNC_ENTITY

.. data:: XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

An entity reference in an attribute value referred to an external entity instead
   of an internal entity.

.. data:: XML_ERROR_BAD_CHAR_REF

A character reference referred to a character which is illegal in XML (for
   example, character ``0``, or '``&#0;``').

.. data:: XML_ERROR_BINARY_ENTITY_REF

An entity reference referred to an entity which was declared with a notation, so
   cannot be parsed.

.. data:: XML_ERROR_DUPLICATE_ATTRIBUTE

An attribute was used more than once in a start tag.

.. data:: XML_ERROR_INCORRECT_ENCODING

.. data:: XML_ERROR_INVALID_TOKEN

Raised when an input byte could not properly be assigned to a character; for
   example, a NUL byte (value ``0``) in a UTF-8 input stream.

.. data:: XML_ERROR_JUNK_AFTER_DOC_ELEMENT

Something other than whitespace occurred after the document element.

.. data:: XML_ERROR_MISPLACED_XML_PI

An XML declaration was found somewhere other than the start of the input data.

.. data:: XML_ERROR_NO_ELEMENTS

The document contains no elements (XML requires all documents to contain exactly
   one top-level element)..

.. data:: XML_ERROR_NO_MEMORY

Expat was not able to allocate memory internally.

.. data:: XML_ERROR_PARAM_ENTITY_REF

A parameter entity reference was found where it was not allowed.

.. data:: XML_ERROR_PARTIAL_CHAR

An incomplete character was found in the input.

.. data:: XML_ERROR_RECURSIVE_ENTITY_REF

An entity reference contained another reference to the same entity; possibly via
   a different name, and possibly indirectly.

.. data:: XML_ERROR_SYNTAX

Some unspecified syntax error was encountered.

.. data:: XML_ERROR_TAG_MISMATCH

An end tag did not match the innermost open start tag.

.. data:: XML_ERROR_UNCLOSED_TOKEN

Some token (such as a start tag) was not closed before the end of the stream or
   the next token was encountered.

.. data:: XML_ERROR_UNDEFINED_ENTITY

A reference was made to an entity which was not defined.

.. data:: XML_ERROR_UNKNOWN_ENCODING

The document encoding is not supported by Expat.

.. data:: XML_ERROR_UNCLOSED_CDATA_SECTION

A CDATA marked section was not closed.

.. data:: XML_ERROR_EXTERNAL_ENTITY_HANDLING

.. data:: XML_ERROR_NOT_STANDALONE

The parser determined that the document was not "standalone" though it declared
   itself to be in the XML declaration, and the :attr:`NotStandaloneHandler` was
   set and returned ``0``.

.. data:: XML_ERROR_UNEXPECTED_STATE

.. data:: XML_ERROR_ENTITY_DECLARED_IN_PE

.. data:: XML_ERROR_FEATURE_REQUIRES_XML_DTD

An operation was requested that requires DTD support to be compiled in, but
   Expat was configured without DTD support.  This should never be reported by a
   standard build of the :mod:`xml.parsers.expat` module.

.. data:: XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

A behavioral change was requested after parsing started that can only be changed
   before parsing has started.  This is (currently) only raised by
   :meth:`UseForeignDTD`.

.. data:: XML_ERROR_UNBOUND_PREFIX

An undeclared prefix was found when namespace processing was enabled.

.. data:: XML_ERROR_UNDECLARING_PREFIX

The document attempted to remove the namespace declaration associated with a
   prefix.

.. data:: XML_ERROR_INCOMPLETE_PE

A parameter entity contained incomplete markup.

.. data:: XML_ERROR_XML_DECL

The document contained no document element at all.

.. data:: XML_ERROR_TEXT_DECL

There was an error parsing a text declaration in an external entity.

.. data:: XML_ERROR_PUBLICID

Characters were found in the public id that are not allowed.

.. data:: XML_ERROR_SUSPENDED

The requested operation was made on a suspended parser, but isn't allowed.  This
   includes attempts to provide additional input or to stop the parser.

.. data:: XML_ERROR_NOT_SUSPENDED

An attempt to resume the parser was made when the parser had not been suspended.

.. data:: XML_ERROR_ABORTED

This should not be reported to Python applications.

.. data:: XML_ERROR_FINISHED

The requested operation was made on a parser which was finished parsing input,
   but isn't allowed.  This includes attempts to provide additional input or to
   stop the parser.

.. data:: XML_ERROR_SUSPEND_PE

.. rubric:: Footnotes

.. [1] The encoding string included in XML output should conform to the
   appropriate standards. For example, "UTF-8" is valid, but "UTF8" is
   not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl
   and https://www.iana.org/assignments/character-sets/character-sets.xhtml.

:mod:`xml.parsers.expat` --- Fast XML parsing using Expat ========================================================= .. module:: xml.parsers.expat :synopsis: An interface to the Expat non-validating XML parser. .. moduleauthor:: Paul Prescod -------------- .. Markup notes: Many of the attributes of the XMLParser objects are callbacks. Since signature information must be presented, these are described using the method directive. Since they are attributes which are set by client code, in-text references to these attributes should be marked using the :member: role. .. warning:: The :mod:`pyexpat` module is not secure against maliciously constructed data. If you need to parse untrusted or unauthenticated data see :ref:`xml-vulnerabilities`. .. index:: single: Expat The :mod:`xml.parsers.expat` module is a Python interface to the Expat non-validating XML parser. The module provides a single extension type, :class:`xmlparser`, that represents the current state of an XML parser. After an :class:`xmlparser` object has been created, various attributes of the object can be set to handler functions. When an XML document is then fed to the parser, the handler functions are called for the character data and markup in the XML document. .. index:: module: pyexpat This module uses the :mod:`pyexpat` module to provide access to the Expat parser. Direct use of the :mod:`pyexpat` module is deprecated. This module provides one exception and one type object: .. exception:: ExpatError The exception raised when Expat reports an error. See section :ref:`expaterror-objects` for more information on interpreting Expat errors. .. exception:: error Alias for :exc:`ExpatError`. .. data:: XMLParserType The type of the return values from the :func:`ParserCreate` function. The :mod:`xml.parsers.expat` module contains two functions: .. function:: ErrorString(errno) Returns an explanatory string for a given error number *errno*. .. function:: ParserCreate(encoding=None, namespace_separator=None) Creates and returns a new :class:`xmlparser` object. *encoding*, if specified, must be a string naming the encoding used by the XML data. Expat doesn't support as many encodings as Python does, and its repertoire of encodings can't be extended; it supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII. If *encoding* [1]_ is given it will override the implicit or explicit encoding of the document. Expat can optionally do XML namespace processing for you, enabled by providing a value for *namespace_separator*. The value must be a one-character string; a :exc:`ValueError` will be raised if the string has an illegal length (``None`` is considered the same as omission). When namespace processing is enabled, element type names and attribute names that belong to a namespace will be expanded. The element name passed to the element handlers :attr:`StartElementHandler` and :attr:`EndElementHandler` will be the concatenation of the namespace URI, the namespace separator character, and the local part of the name. If the namespace separator is a zero byte (``chr(0)``) then the namespace URI and the local part will be concatenated without any separator. For example, if *namespace_separator* is set to a space character (``' '``) and the following document is parsed: .. code-block:: xml :attr:`StartElementHandler` will receive the following strings for each element:: http://default-namespace.org/ root http://www.python.org/ns/ elem1 elem2 Due to limitations in the ``Expat`` library used by :mod:`pyexpat`, the :class:`xmlparser` instance returned can only be used to parse a single XML document. Call ``ParserCreate`` for each document to provide unique parser instances. .. seealso:: `The Expat XML Parser `_ Home page of the Expat project. .. _xmlparser-objects: XMLParser Objects ----------------- :class:`xmlparser` objects have the following methods: .. method:: xmlparser.Parse(data[, isfinal]) Parses the contents of the string *data*, calling the appropriate handler functions to process the parsed data. *isfinal* must be true on the final call to this method; it allows the parsing of a single file in fragments, not the submission of multiple files. *data* can be the empty string at any time. .. method:: xmlparser.ParseFile(file) Parse XML data reading from the object *file*. *file* only needs to provide the ``read(nbytes)`` method, returning the empty string when there's no more data. .. method:: xmlparser.SetBase(base) Sets the base to be used for resolving relative URIs in system identifiers in declarations. Resolving relative identifiers is left to the application: this value will be passed through as the *base* argument to the :func:`ExternalEntityRefHandler`, :func:`NotationDeclHandler`, and :func:`UnparsedEntityDeclHandler` functions. .. method:: xmlparser.GetBase() Returns a string containing the base set by a previous call to :meth:`SetBase`, or ``None`` if :meth:`SetBase` hasn't been called. .. method:: xmlparser.GetInputContext() Returns the input data that generated the current event as a string. The data is in the encoding of the entity which contains the text. When called while an event handler is not active, the return value is ``None``. .. method:: xmlparser.ExternalEntityParserCreate(context[, encoding]) Create a "child" parser which can be used to parse an external parsed entity referred to by content parsed by the parent parser. The *context* parameter should be the string passed to the :meth:`ExternalEntityRefHandler` handler function, described below. The child parser is created with the :attr:`ordered_attributes` and :attr:`specified_attributes` set to the values of this parser. .. method:: xmlparser.SetParamEntityParsing(flag) Control parsing of parameter entities (including the external DTD subset). Possible *flag* values are :const:`XML_PARAM_ENTITY_PARSING_NEVER`, :const:`XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE` and :const:`XML_PARAM_ENTITY_PARSING_ALWAYS`. Return true if setting the flag was successful. .. method:: xmlparser.UseForeignDTD([flag]) Calling this with a true value for *flag* (the default) will cause Expat to call the :attr:`ExternalEntityRefHandler` with :const:`None` for all arguments to allow an alternate DTD to be loaded. If the document does not contain a document type declaration, the :attr:`ExternalEntityRefHandler` will still be called, but the :attr:`StartDoctypeDeclHandler` and :attr:`EndDoctypeDeclHandler` will not be called. Passing a false value for *flag* will cancel a previous call that passed a true value, but otherwise has no effect. This method can only be called before the :meth:`Parse` or :meth:`ParseFile` methods are called; calling it after either of those have been called causes :exc:`ExpatError` to be raised with the :attr:`code` attribute set to ``errors.codes[errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING]``. :class:`xmlparser` objects have the following attributes: .. attribute:: xmlparser.buffer_size The size of the buffer used when :attr:`buffer_text` is true. A new buffer size can be set by assigning a new integer value to this attribute. When the size is changed, the buffer will be flushed. .. attribute:: xmlparser.buffer_text Setting this to true causes the :class:`xmlparser` object to buffer textual content returned by Expat to avoid multiple calls to the :meth:`CharacterDataHandler` callback whenever possible. This can improve performance substantially since Expat normally breaks character data into chunks at every line ending. This attribute is false by default, and may be changed at any time. .. attribute:: xmlparser.buffer_used If :attr:`buffer_text` is enabled, the number of bytes stored in the buffer. These bytes represent UTF-8 encoded text. This attribute has no meaningful interpretation when :attr:`buffer_text` is false. .. attribute:: xmlparser.ordered_attributes Setting this attribute to a non-zero integer causes the attributes to be reported as a list rather than a dictionary. The attributes are presented in the order found in the document text. For each attribute, two list entries are presented: the attribute name and the attribute value. (Older versions of this module also used this format.) By default, this attribute is false; it may be changed at any time. .. attribute:: xmlparser.specified_attributes If set to a non-zero integer, the parser will report only those attributes which were specified in the document instance and not those which were derived from attribute declarations. Applications which set this need to be especially careful to use what additional information is available from the declarations as needed to comply with the standards for the behavior of XML processors. By default, this attribute is false; it may be changed at any time. The following attributes contain values relating to the most recent error encountered by an :class:`xmlparser` object, and will only have correct values once a call to :meth:`Parse` or :meth:`ParseFile` has raised an :exc:`xml.parsers.expat.ExpatError` exception. .. attribute:: xmlparser.ErrorByteIndex Byte index at which an error occurred. .. attribute:: xmlparser.ErrorCode Numeric code specifying the problem. This value can be passed to the :func:`ErrorString` function, or compared to one of the constants defined in the ``errors`` object. .. attribute:: xmlparser.ErrorColumnNumber Column number at which an error occurred. .. attribute:: xmlparser.ErrorLineNumber Line number at which an error occurred. The following attributes contain values relating to the current parse location in an :class:`xmlparser` object. During a callback reporting a parse event they indicate the location of the first of the sequence of characters that generated the event. When called outside of a callback, the position indicated will be just past the last parse event (regardless of whether there was an associated callback). .. attribute:: xmlparser.CurrentByteIndex Current byte index in the parser input. .. attribute:: xmlparser.CurrentColumnNumber Current column number in the parser input. .. attribute:: xmlparser.CurrentLineNumber Current line number in the parser input. Here is the list of handlers that can be set. To set a handler on an :class:`xmlparser` object *o*, use ``o.handlername = func``. *handlername* must be taken from the following list, and *func* must be a callable object accepting the correct number of arguments. The arguments are all strings, unless otherwise stated. .. method:: xmlparser.XmlDeclHandler(version, encoding, standalone) Called when the XML declaration is parsed. The XML declaration is the (optional) declaration of the applicable version of the XML recommendation, the encoding of the document text, and an optional "standalone" declaration. *version* and *encoding* will be strings, and *standalone* will be ``1`` if the document is declared standalone, ``0`` if it is declared not to be standalone, or ``-1`` if the standalone clause was omitted. This is only available with Expat version 1.95.0 or newer. .. method:: xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset) Called when Expat begins parsing the document type declaration (``'``. .. method:: xmlparser.StartCdataSectionHandler() Called at the start of a CDATA section. This and :attr:`EndCdataSectionHandler` are needed to be able to identify the syntactical start and end for CDATA sections. .. method:: xmlparser.EndCdataSectionHandler() Called at the end of a CDATA section. .. method:: xmlparser.DefaultHandler(data) Called for any characters in the XML document for which no applicable handler has been specified. This means characters that are part of a construct which could be reported, but for which no handler has been supplied. .. method:: xmlparser.DefaultHandlerExpand(data) This is the same as the :func:`DefaultHandler`, but doesn't inhibit expansion of internal entities. The entity reference will not be passed to the default handler. .. method:: xmlparser.NotStandaloneHandler() Called if the XML document hasn't been declared as being a standalone document. This happens when there is an external subset or a reference to a parameter entity, but the XML declaration does not set standalone to ``yes`` in an XML declaration. If this handler returns ``0``, then the parser will raise an :const:`XML_ERROR_NOT_STANDALONE` error. If this handler is not set, no exception is raised by the parser for this condition. .. method:: xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId) Called for references to external entities. *base* is the current base, as set by a previous call to :meth:`SetBase`. The public and system identifiers, *systemId* and *publicId*, are strings if given; if the public identifier is not given, *publicId* will be ``None``. The *context* value is opaque and should only be used as described below. For external entities to be parsed, this handler must be implemented. It is responsible for creating the sub-parser using ``ExternalEntityParserCreate(context)``, initializing it with the appropriate callbacks, and parsing the entity. This handler should return an integer; if it returns ``0``, the parser will raise an :const:`XML_ERROR_EXTERNAL_ENTITY_HANDLING` error, otherwise parsing will continue. If this handler is not provided, external entities are reported by the :attr:`DefaultHandler` callback, if provided. .. _expaterror-objects: ExpatError Exceptions --------------------- .. sectionauthor:: Fred L. Drake, Jr. :exc:`ExpatError` exceptions have a number of interesting attributes: .. attribute:: ExpatError.code Expat's internal error number for the specific error. The :data:`errors.messages ` dictionary maps these error numbers to Expat's error messages. For example:: from xml.parsers.expat import ParserCreate, ExpatError, errors p = ParserCreate() try: p.Parse(some_xml_document) except ExpatError as err: print("Error:", errors.messages[err.code]) The :mod:`~xml.parsers.expat.errors` module also provides error message constants and a dictionary :data:`~xml.parsers.expat.errors.codes` mapping these messages back to the error codes, see below. .. attribute:: ExpatError.lineno Line number on which the error was detected. The first line is numbered ``1``. .. attribute:: ExpatError.offset Character offset into the line where the error occurred. The first column is numbered ``0``. .. _expat-example: Example ------- The following program defines three handlers that just print out their arguments. :: import xml.parsers.expat # 3 handler functions def start_element(name, attrs): print('Start element:', name, attrs) def end_element(name): print('End element:', name) def char_data(data): print('Character data:', repr(data)) p = xml.parsers.expat.ParserCreate() p.StartElementHandler = start_element p.EndElementHandler = end_element p.CharacterDataHandler = char_data p.Parse(""" Text goes here More text """, 1) The output from this program is:: Start element: parent {'id': 'top'} Start element: child1 {'name': 'paul'} Character data: 'Text goes here' End element: child1 Character data: '\n' Start element: child2 {'name': 'fred'} Character data: 'More text' End element: child2 Character data: '\n' End element: parent .. _expat-content-models: Content Model Descriptions -------------------------- .. module:: xml.parsers.expat.model .. sectionauthor:: Fred L. Drake, Jr. Content models are described using nested tuples. Each tuple contains four values: the type, the quantifier, the name, and a tuple of children. Children are simply additional content model descriptions. The values of the first two fields are constants defined in the :mod:`xml.parsers.expat.model` module. These constants can be collected in two groups: the model type group and the quantifier group. The constants in the model type group are: .. data:: XML_CTYPE_ANY :noindex: The element named by the model name was declared to have a content model of ``ANY``. .. data:: XML_CTYPE_CHOICE :noindex: The named element allows a choice from a number of options; this is used for content models such as ``(A | B | C)``. .. data:: XML_CTYPE_EMPTY :noindex: Elements which are declared to be ``EMPTY`` have this model type. .. data:: XML_CTYPE_MIXED :noindex: .. data:: XML_CTYPE_NAME :noindex: .. data:: XML_CTYPE_SEQ :noindex: Models which represent a series of models which follow one after the other are indicated with this model type. This is used for models such as ``(A, B, C)``. The constants in the quantifier group are: .. data:: XML_CQUANT_NONE :noindex: No modifier is given, so it can appear exactly once, as for ``A``. .. data:: XML_CQUANT_OPT :noindex: The model is optional: it can appear once or not at all, as for ``A?``. .. data:: XML_CQUANT_PLUS :noindex: The model must occur one or more times (like ``A+``). .. data:: XML_CQUANT_REP :noindex: The model must occur zero or more times, as for ``A*``. .. _expat-errors: Expat error constants --------------------- .. module:: xml.parsers.expat.errors The following constants are provided in the :mod:`xml.parsers.expat.errors` module. These constants are useful in interpreting some of the attributes of the :exc:`ExpatError` exception objects raised when an error has occurred. Since for backwards compatibility reasons, the constants' value is the error *message* and not the numeric error *code*, you do this by comparing its :attr:`code` attribute with :samp:`errors.codes[errors.XML_ERROR_{CONSTANT_NAME}]`. The ``errors`` module has the following attributes: .. data:: codes A dictionary mapping numeric error codes to their string descriptions. .. versionadded:: 3.2 .. data:: messages A dictionary mapping string descriptions to their error codes. .. versionadded:: 3.2 .. data:: XML_ERROR_ASYNC_ENTITY .. data:: XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF An entity reference in an attribute value referred to an external entity instead of an internal entity. .. data:: XML_ERROR_BAD_CHAR_REF A character reference referred to a character which is illegal in XML (for example, character ``0``, or '``�``'). .. data:: XML_ERROR_BINARY_ENTITY_REF An entity reference referred to an entity which was declared with a notation, so cannot be parsed. .. data:: XML_ERROR_DUPLICATE_ATTRIBUTE An attribute was used more than once in a start tag. .. data:: XML_ERROR_INCORRECT_ENCODING .. data:: XML_ERROR_INVALID_TOKEN Raised when an input byte could not properly be assigned to a character; for example, a NUL byte (value ``0``) in a UTF-8 input stream. .. data:: XML_ERROR_JUNK_AFTER_DOC_ELEMENT Something other than whitespace occurred after the document element. .. data:: XML_ERROR_MISPLACED_XML_PI An XML declaration was found somewhere other than the start of the input data. .. data:: XML_ERROR_NO_ELEMENTS The document contains no elements (XML requires all documents to contain exactly one top-level element).. .. data:: XML_ERROR_NO_MEMORY Expat was not able to allocate memory internally. .. data:: XML_ERROR_PARAM_ENTITY_REF A parameter entity reference was found where it was not allowed. .. data:: XML_ERROR_PARTIAL_CHAR An incomplete character was found in the input. .. data:: XML_ERROR_RECURSIVE_ENTITY_REF An entity reference contained another reference to the same entity; possibly via a different name, and possibly indirectly. .. data:: XML_ERROR_SYNTAX Some unspecified syntax error was encountered. .. data:: XML_ERROR_TAG_MISMATCH An end tag did not match the innermost open start tag. .. data:: XML_ERROR_UNCLOSED_TOKEN Some token (such as a start tag) was not closed before the end of the stream or the next token was encountered. .. data:: XML_ERROR_UNDEFINED_ENTITY A reference was made to an entity which was not defined. .. data:: XML_ERROR_UNKNOWN_ENCODING The document encoding is not supported by Expat. .. data:: XML_ERROR_UNCLOSED_CDATA_SECTION A CDATA marked section was not closed. .. data:: XML_ERROR_EXTERNAL_ENTITY_HANDLING .. data:: XML_ERROR_NOT_STANDALONE The parser determined that the document was not "standalone" though it declared itself to be in the XML declaration, and the :attr:`NotStandaloneHandler` was set and returned ``0``. .. data:: XML_ERROR_UNEXPECTED_STATE .. data:: XML_ERROR_ENTITY_DECLARED_IN_PE .. data:: XML_ERROR_FEATURE_REQUIRES_XML_DTD An operation was requested that requires DTD support to be compiled in, but Expat was configured without DTD support. This should never be reported by a standard build of the :mod:`xml.parsers.expat` module. .. data:: XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING A behavioral change was requested after parsing started that can only be changed before parsing has started. This is (currently) only raised by :meth:`UseForeignDTD`. .. data:: XML_ERROR_UNBOUND_PREFIX An undeclared prefix was found when namespace processing was enabled. .. data:: XML_ERROR_UNDECLARING_PREFIX The document attempted to remove the namespace declaration associated with a prefix. .. data:: XML_ERROR_INCOMPLETE_PE A parameter entity contained incomplete markup. .. data:: XML_ERROR_XML_DECL The document contained no document element at all. .. data:: XML_ERROR_TEXT_DECL There was an error parsing a text declaration in an external entity. .. data:: XML_ERROR_PUBLICID Characters were found in the public id that are not allowed. .. data:: XML_ERROR_SUSPENDED The requested operation was made on a suspended parser, but isn't allowed. This includes attempts to provide additional input or to stop the parser. .. data:: XML_ERROR_NOT_SUSPENDED An attempt to resume the parser was made when the parser had not been suspended. .. data:: XML_ERROR_ABORTED This should not be reported to Python applications. .. data:: XML_ERROR_FINISHED The requested operation was made on a parser which was finished parsing input, but isn't allowed. This includes attempts to provide additional input or to stop the parser. .. data:: XML_ERROR_SUSPEND_PE .. rubric:: Footnotes .. [1] The encoding string included in XML output should conform to the appropriate standards. For example, "UTF-8" is valid, but "UTF8" is not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl and https://www.iana.org/assignments/character-sets/character-sets.xhtml.