cpython-lru_cache-weakref: Lib/xml/etree/ElementTree.py annotate

annotate Lib/xml/etree/ElementTree.py @ 87690:66c1c9f32567 default tip

Add use_weakref option to functools.lru_cache The use_weakref option makes lru_cache create weak references to the function arguments when creating the cache key, which prevents them from staying in the memory forever even after all other references to them are gone. This is a proof of concept for http://bugs.python.org/issue19859

author	Radomir Dopieralski <devel@sheep.art.pl>
date	Tue, 03 Dec 2013 16:02:48 +0100
parents	c5e206b9df2e
children

rev	line source
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1 """Lightweight XML support for Python.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	2
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	3 XML is an inherently hierarchical data format, and the most natural way to
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	4 represent it is with a tree. This module has two classes for this purpose:
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	5
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	6 1. ElementTree represents the whole XML document as a tree and
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	7
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	8 2. Element represents a single node in this tree.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	9
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	10 Interactions with the whole document (reading and writing to/from files) are
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	11 usually done on the ElementTree level. Interactions with a single XML element
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	12 and its sub-elements are done on the Element level.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	13
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	14 Element is a flexible container object designed to store hierarchical data
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	15 structures in memory. It can be described as a cross between a list and a
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	16 dictionary. Each Element has a number of properties associated with it:
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	17
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	18 'tag' - a string containing the element's name.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	19
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	20 'attributes' - a Python dictionary storing the element's attributes.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	21
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	22 'text' - a string containing the element's text content.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	23
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	24 'tail' - an optional string containing text after the element's end tag.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	25
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	26 And a number of child elements stored in a Python sequence.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	27
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	28 To create an element instance, use the Element constructor,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	29 or the SubElement factory function.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	30
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	31 You can also use the ElementTree class to wrap an element structure
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	32 and convert it to and from XML.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	33
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	34 """
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	35
83459 56b70b557a23 Make license notices more consistent and remove old changelog. Eli Bendersky <eliben@gmail.com> parents: 83441 diff changeset	36 #---------------------------------------------------------------------
56b70b557a23 Make license notices more consistent and remove old changelog. Eli Bendersky <eliben@gmail.com> parents: 83441 diff changeset	37 # Licensed to PSF under a Contributor Agreement.
56b70b557a23 Make license notices more consistent and remove old changelog. Eli Bendersky <eliben@gmail.com> parents: 83441 diff changeset	38 # See http://www.python.org/psf/license for licensing details.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	39 #
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	40 # ElementTree
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	41 # Copyright (c) 1999-2008 by Fredrik Lundh. All rights reserved.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	42 #
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	43 # fredrik@pythonware.com
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	44 # http://www.pythonware.com
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	45 # --------------------------------------------------------------------
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	46 # The ElementTree toolkit is
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	47 #
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	48 # Copyright (c) 1999-2008 by Fredrik Lundh
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	49 #
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	50 # By obtaining, using, and/or copying this software and/or its
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	51 # associated documentation, you agree that you have read, understood,
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	52 # and will comply with the following terms and conditions:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	53 #
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	54 # Permission to use, copy, modify, and distribute this software and
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	55 # its associated documentation for any purpose and without fee is
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	56 # hereby granted, provided that the above copyright notice appears in
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	57 # all copies, and that both that copyright notice and this permission
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	58 # notice appear in supporting documentation, and that the name of
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	59 # Secret Labs AB or the author not be used in advertising or publicity
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	60 # pertaining to distribution of the software without specific, written
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	61 # prior permission.
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	62 #
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	63 # SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	64 # TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT-
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	65 # ABILITY AND FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	66 # BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	67 # DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	68 # WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	69 # ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	70 # OF THIS SOFTWARE.
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	71 # --------------------------------------------------------------------
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	72
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	73 __all__ = [
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	74 # public symbols
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	75 "Comment",
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	76 "dump",
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	77 "Element", "ElementTree",
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	78 "fromstring", "fromstringlist",
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	79 "iselement", "iterparse",
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	80 "parse", "ParseError",
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	81 "PI", "ProcessingInstruction",
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	82 "QName",
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	83 "SubElement",
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	84 "tostring", "tostringlist",
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	85 "TreeBuilder",
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	86 "VERSION",
74903 65fc79fb4eb2 Issue #13988: cElementTree is deprecated and the _elementtree accelerator is automatically used whenever available. Florent Xicluna <florent.xicluna@gmail.com> parents: 73291 diff changeset	87 "XML", "XMLID",
83846 7e0447ce6689 Cleanup more old ET library leftovers Eli Bendersky <eliben@gmail.com> parents: 83845 diff changeset	88 "XMLParser",
74903 65fc79fb4eb2 Issue #13988: cElementTree is deprecated and the _elementtree accelerator is automatically used whenever available. Florent Xicluna <florent.xicluna@gmail.com> parents: 73291 diff changeset	89 "register_namespace",
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	90 ]
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	91
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	92 VERSION = "1.3.0"
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	93
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	94 import sys
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	95 import re
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	96 import warnings
78105 6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	97 import io
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	98 import contextlib
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	99
77434 ea0dc4338987 Removed _SimpleElementPath and its flaky test. The test monkey-patches the module, which causes other failures and fails itself depending on the order tests are run. Eli Bendersky <eliben@gmail.com> parents: 77431 diff changeset	100 from . import ElementPath
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	101
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	102
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	103 class ParseError(SyntaxError):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	104 """An error when parsing an XML document.
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	105
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	106 In addition to its exception value, a ParseError contains
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	107 two extra attributes:
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	108 'code' - the specific exception code
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	109 'position' - the line and column of the error
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	110
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	111 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	112 pass
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	113
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	114 # --------------------------------------------------------------------
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	115
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	116
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	117 def iselement(element):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	118 """Return True if element appears to be an Element."""
74903 65fc79fb4eb2 Issue #13988: cElementTree is deprecated and the _elementtree accelerator is automatically used whenever available. Florent Xicluna <florent.xicluna@gmail.com> parents: 73291 diff changeset	119 return hasattr(element, 'tag')
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	120
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	121
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	122 class Element:
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	123 """An XML element.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	124
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	125 This class is the reference implementation of the Element interface.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	126
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	127 An element's length is its number of subelements. That means if you
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	128 you want to check if an element is truly empty, you should check BOTH
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	129 its length AND its text attribute.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	130
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	131 The element tag, attribute names, and attribute values can be either
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	132 bytes or strings.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	133
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	134 tag is the element name. attrib is an optional dictionary containing
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	135 element attributes. extra are additional element attributes given as
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	136 keyword arguments.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	137
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	138 Example form:
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	139 <tag attrib>text<child/>...</tag>tail
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	140
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	141 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	142
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	143 tag = None
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	144 """The element's name."""
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	145
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	146 attrib = None
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	147 """Dictionary of the element's attributes."""
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	148
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	149 text = None
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	150 """
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	151 Text before first subelement. This is either a string or the value None.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	152 Note that if there is no text, this attribute may be either
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	153 None or the empty string, depending on the parser.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	154
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	155 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	156
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	157 tail = None
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	158 """
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	159 Text after this element's end tag, but before the next sibling element's
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	160 start tag. This is either a string or the value None. Note that if there
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	161 was no text, this attribute may be either None or an empty string,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	162 depending on the parser.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	163
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	164 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	165
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	166 def __init__(self, tag, attrib={}, **extra):
77217 7d252dbfbee3 Issue 14814: Add namespaces keyword arg to find() methods in _elementtree. Eli Bendersky <eliben@gmail.com>* parents: 75894 diff changeset	167 if not isinstance(attrib, dict):
7d252dbfbee3 Issue 14814: Add namespaces keyword arg to find() methods in _elementtree. Eli Bendersky <eliben@gmail.com>* parents: 75894 diff changeset	168 raise TypeError("attrib must be dict, not %s" % (
7d252dbfbee3 Issue 14814: Add namespaces keyword arg to find() methods in _elementtree. Eli Bendersky <eliben@gmail.com>* parents: 75894 diff changeset	169 attrib.__class__.__name__,))
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	170 attrib = attrib.copy()
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	171 attrib.update(extra)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	172 self.tag = tag
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	173 self.attrib = attrib
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	174 self._children = []
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	175
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	176 def __repr__(self):
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	177 return "<Element %s at 0x%x>" % (repr(self.tag), id(self))
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	178
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	179 def makeelement(self, tag, attrib):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	180 """Create a new element with the same type.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	181
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	182 tag is a string containing the element name.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	183 attrib is a dictionary containing the element attributes.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	184
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	185 Do not call this method, use the SubElement factory function instead.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	186
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	187 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	188 return self.__class__(tag, attrib)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	189
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	190 def copy(self):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	191 """Return copy of current element.
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	192
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	193 This creates a shallow copy. Subelements will be shared with the
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	194 original tree.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	195
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	196 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	197 elem = self.makeelement(self.tag, self.attrib)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	198 elem.text = self.text
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	199 elem.tail = self.tail
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	200 elem[:] = self
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	201 return elem
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	202
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	203 def __len__(self):
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	204 return len(self._children)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	205
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	206 def __bool__(self):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	207 warnings.warn(
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	208 "The behavior of this method will change in future versions. "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	209 "Use specific 'len(elem)' or 'elem is not None' test instead.",
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	210 FutureWarning, stacklevel=2
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	211 )
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	212 return len(self._children) != 0 # emulate old behaviour, for now
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	213
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	214 def __getitem__(self, index):
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	215 return self._children[index]
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	216
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	217 def __setitem__(self, index, element):
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	218 # if isinstance(index, slice):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	219 # for elt in element:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	220 # assert iselement(elt)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	221 # else:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	222 # assert iselement(element)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	223 self._children[index] = element
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	224
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	225 def __delitem__(self, index):
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	226 del self._children[index]
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	227
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	228 def append(self, subelement):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	229 """Add subelement to the end of this element.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	230
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	231 The new element will appear in document order after the last existing
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	232 subelement (or directly after the text, if it's the first subelement),
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	233 but before the end tag for this element.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	234
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	235 """
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	236 self._assert_is_element(subelement)
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	237 self._children.append(subelement)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	238
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	239 def extend(self, elements):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	240 """Append subelements from a sequence.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	241
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	242 elements is a sequence with zero or more elements.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	243
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	244 """
75894 75268a773455 Issue #13782: streamline argument type-checking in ET.Element Eli Bendersky <eliben@gmail.com> parents: 75416 diff changeset	245 for element in elements:
75268a773455 Issue #13782: streamline argument type-checking in ET.Element Eli Bendersky <eliben@gmail.com> parents: 75416 diff changeset	246 self._assert_is_element(element)
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	247 self._children.extend(elements)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	248
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	249 def insert(self, index, subelement):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	250 """Insert subelement at position index."""
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	251 self._assert_is_element(subelement)
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	252 self._children.insert(index, subelement)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	253
75894 75268a773455 Issue #13782: streamline argument type-checking in ET.Element Eli Bendersky <eliben@gmail.com> parents: 75416 diff changeset	254 def _assert_is_element(self, e):
79460 7bd9626d8b4f Issue #16089: Allow ElementTree.TreeBuilder to work again with a non-Element element_factory (fixes a regression in SimpleTAL). Antoine Pitrou <solipsis@pitrou.net> parents: 79052 diff changeset	255 # Need to refer to the actual Python implementation, not the
7bd9626d8b4f Issue #16089: Allow ElementTree.TreeBuilder to work again with a non-Element element_factory (fixes a regression in SimpleTAL). Antoine Pitrou <solipsis@pitrou.net> parents: 79052 diff changeset	256 # shadowing C implementation.
83845 16a03959819a Issue #17988: remove unused alias for Element and rename the used one Eli Bendersky <eliben@gmail.com> parents: 83843 diff changeset	257 if not isinstance(e, _Element_Py):
75894 75268a773455 Issue #13782: streamline argument type-checking in ET.Element Eli Bendersky <eliben@gmail.com> parents: 75416 diff changeset	258 raise TypeError('expected an Element, not %s' % type(e).__name__)
75268a773455 Issue #13782: streamline argument type-checking in ET.Element Eli Bendersky <eliben@gmail.com> parents: 75416 diff changeset	259
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	260 def remove(self, subelement):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	261 """Remove matching subelement.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	262
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	263 Unlike the find methods, this method compares elements based on
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	264 identity, NOT ON tag value or contents. To remove subelements by
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	265 other means, the easiest way is to use a list comprehension to
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	266 select what elements to keep, and then use slice assignment to update
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	267 the parent element.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	268
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	269 ValueError is raised if a matching element could not be found.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	270
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	271 """
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	272 # assert iselement(element)
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	273 self._children.remove(subelement)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	274
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	275 def getchildren(self):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	276 """(Deprecated) Return all subelements.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	277
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	278 Elements are returned in document order.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	279
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	280 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	281 warnings.warn(
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	282 "This method will be removed in future versions. "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	283 "Use 'list(elem)' or iteration over elem instead.",
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	284 DeprecationWarning, stacklevel=2
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	285 )
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	286 return self._children
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	287
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	288 def find(self, path, namespaces=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	289 """Find first matching element by tag name or path.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	290
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	291 path is a string having either an element tag or an XPath,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	292 namespaces is an optional mapping from namespace prefix to full name.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	293
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	294 Return the first matching element, or None if no element was found.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	295
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	296 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	297 return ElementPath.find(self, path, namespaces)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	298
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	299 def findtext(self, path, default=None, namespaces=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	300 """Find text for first matching element by tag name or path.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	301
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	302 path is a string having either an element tag or an XPath,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	303 default is the value to return if the element was not found,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	304 namespaces is an optional mapping from namespace prefix to full name.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	305
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	306 Return text content of first matching element, or default value if
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	307 none was found. Note that if an element is found having no text
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	308 content, the empty string is returned.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	309
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	310 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	311 return ElementPath.findtext(self, path, default, namespaces)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	312
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	313 def findall(self, path, namespaces=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	314 """Find all matching subelements by tag name or path.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	315
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	316 path is a string having either an element tag or an XPath,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	317 namespaces is an optional mapping from namespace prefix to full name.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	318
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	319 Returns list containing all matching elements in document order.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	320
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	321 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	322 return ElementPath.findall(self, path, namespaces)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	323
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	324 def iterfind(self, path, namespaces=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	325 """Find all matching subelements by tag name or path.
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	326
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	327 path is a string having either an element tag or an XPath,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	328 namespaces is an optional mapping from namespace prefix to full name.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	329
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	330 Return an iterable yielding all matching elements in document order.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	331
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	332 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	333 return ElementPath.iterfind(self, path, namespaces)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	334
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	335 def clear(self):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	336 """Reset element.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	337
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	338 This function removes all subelements, clears all attributes, and sets
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	339 the text and tail attributes to None.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	340
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	341 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	342 self.attrib.clear()
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	343 self._children = []
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	344 self.text = self.tail = None
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	345
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	346 def get(self, key, default=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	347 """Get element attribute.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	348
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	349 Equivalent to attrib.get, but some implementations may handle this a
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	350 bit more efficiently. key is what attribute to look for, and
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	351 default is what to return if the attribute was not found.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	352
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	353 Returns a string containing the attribute value, or the default if
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	354 attribute was not found.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	355
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	356 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	357 return self.attrib.get(key, default)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	358
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	359 def set(self, key, value):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	360 """Set element attribute.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	361
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	362 Equivalent to attrib[key] = value, but some implementations may handle
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	363 this a bit more efficiently. key is what attribute to set, and
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	364 value is the attribute value to set it to.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	365
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	366 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	367 self.attrib[key] = value
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	368
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	369 def keys(self):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	370 """Get list of attribute names.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	371
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	372 Names are returned in an arbitrary order, just like an ordinary
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	373 Python dict. Equivalent to attrib.keys()
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	374
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	375 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	376 return self.attrib.keys()
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	377
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	378 def items(self):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	379 """Get element attributes as a sequence.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	380
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	381 The attributes are returned in arbitrary order. Equivalent to
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	382 attrib.items().
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	383
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	384 Return a list of (name, value) tuples.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	385
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	386 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	387 return self.attrib.items()
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	388
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	389 def iter(self, tag=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	390 """Create tree iterator.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	391
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	392 The iterator loops over the element and all subelements in document
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	393 order, returning all elements with a matching tag.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	394
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	395 If the tree structure is modified during iteration, new or removed
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	396 elements may or may not be included. To get a stable set, use the
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	397 list() function on the iterator, and loop over the resulting list.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	398
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	399 tag is what tags to look for (default is to return all elements)
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	400
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	401 Return an iterator containing all the matching elements.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	402
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	403 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	404 if tag == "*":
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	405 tag = None
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	406 if tag is None or self.tag == tag:
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	407 yield self
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	408 for e in self._children:
79389 33a221662f39 more yield from Philip Jenvey <pjenvey@underboss.org> parents: 79052 diff changeset	409 yield from e.iter(tag)
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	410
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	411 # compatibility
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	412 def getiterator(self, tag=None):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	413 # Change for a DeprecationWarning in 1.4
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	414 warnings.warn(
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	415 "This method will be removed in future versions. "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	416 "Use 'elem.iter()' or 'list(elem.iter())' instead.",
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	417 PendingDeprecationWarning, stacklevel=2
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	418 )
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	419 return list(self.iter(tag))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	420
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	421 def itertext(self):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	422 """Create text iterator.
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	423
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	424 The iterator loops over the element and all subelements in document
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	425 order, returning all inner text.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	426
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	427 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	428 tag = self.tag
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	429 if not isinstance(tag, str) and tag is not None:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	430 return
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	431 if self.text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	432 yield self.text
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	433 for e in self:
79389 33a221662f39 more yield from Philip Jenvey <pjenvey@underboss.org> parents: 79052 diff changeset	434 yield from e.itertext()
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	435 if e.tail:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	436 yield e.tail
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	437
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	438
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	439 def SubElement(parent, tag, attrib={}, **extra):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	440 """Subelement factory which creates an element instance, and appends it
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	441 to an existing parent.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	442
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	443 The element tag, attribute names, and attribute values can be either
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	444 bytes or Unicode strings.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	445
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	446 parent is the parent element, tag is the subelements name, attrib is
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	447 an optional directory containing element attributes, extra are
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	448 additional attributes given as keyword arguments.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	449
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	450 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	451 attrib = attrib.copy()
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	452 attrib.update(extra)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	453 element = parent.makeelement(tag, attrib)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	454 parent.append(element)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	455 return element
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	456
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	457
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	458 def Comment(text=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	459 """Comment element factory.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	460
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	461 This function creates a special element which the standard serializer
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	462 serializes as an XML comment.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	463
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	464 text is a string containing the comment string.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	465
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	466 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	467 element = Element(Comment)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	468 element.text = text
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	469 return element
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	470
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	471
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	472 def ProcessingInstruction(target, text=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	473 """Processing Instruction element factory.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	474
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	475 This function creates a special element which the standard serializer
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	476 serializes as an XML comment.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	477
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	478 target is a string containing the processing instruction, text is a
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	479 string containing the processing instruction contents, if any.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	480
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	481 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	482 element = Element(ProcessingInstruction)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	483 element.text = target
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	484 if text:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	485 element.text = element.text + " " + text
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	486 return element
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	487
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	488 PI = ProcessingInstruction
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	489
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	490
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	491 class QName:
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	492 """Qualified name wrapper.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	493
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	494 This class can be used to wrap a QName attribute value in order to get
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	495 proper namespace handing on output.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	496
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	497 text_or_uri is a string containing the QName value either in the form
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	498 {uri}local, or if the tag argument is given, the URI part of a QName.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	499
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	500 tag is an optional argument which if given, will make the first
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	501 argument (text_or_uri) be interpreted as a URI, and this argument (tag)
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	502 be interpreted as a local name.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	503
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	504 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	505 def __init__(self, text_or_uri, tag=None):
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	506 if tag:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	507 text_or_uri = "{%s}%s" % (text_or_uri, tag)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	508 self.text = text_or_uri
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	509 def __str__(self):
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	510 return self.text
66809 c537bd37f508 #10661: give QName a nicer repr. Georg Brandl <georg@python.org> parents: 66099 diff changeset	511 def __repr__(self):
66810 1b659a00570b Guard against rogue tuples. Georg Brandl <georg@python.org> parents: 66809 diff changeset	512 return '<QName %r>' % (self.text,)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	513 def __hash__(self):
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	514 return hash(self.text)
51122 adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	515 def __le__(self, other):
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	516 if isinstance(other, QName):
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	517 return self.text <= other.text
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	518 return self.text <= other
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	519 def __lt__(self, other):
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	520 if isinstance(other, QName):
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	521 return self.text < other.text
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	522 return self.text < other
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	523 def __ge__(self, other):
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	524 if isinstance(other, QName):
51122 adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	525 return self.text >= other.text
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	526 return self.text >= other
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	527 def __gt__(self, other):
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	528 if isinstance(other, QName):
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	529 return self.text > other.text
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	530 return self.text > other
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	531 def __eq__(self, other):
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	532 if isinstance(other, QName):
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	533 return self.text == other.text
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	534 return self.text == other
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	535 def __ne__(self, other):
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	536 if isinstance(other, QName):
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	537 return self.text != other.text
adbd77a90bde Merged revisions 69025 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 42501 diff changeset	538 return self.text != other
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	539
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	540 # --------------------------------------------------------------------
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	541
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	542
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	543 class ElementTree:
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	544 """An XML element hierarchy.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	545
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	546 This class also provides support for serialization to and from
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	547 standard XML.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	548
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	549 element is an optional root element node,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	550 file is an optional file handle or file name of an XML file whose
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	551 contents will be used to initialize the tree with.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	552
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	553 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	554 def __init__(self, element=None, file=None):
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	555 # assert element is None or iselement(element)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	556 self._root = element # first node
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	557 if file:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	558 self.parse(file)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	559
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	560 def getroot(self):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	561 """Return root element of this tree."""
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	562 return self._root
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	563
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	564 def _setroot(self, element):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	565 """Replace root element of this tree.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	566
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	567 This will discard the current contents of the tree and replace it
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	568 with the given element. Use with care!
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	569
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	570 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	571 # assert iselement(element)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	572 self._root = element
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	573
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	574 def parse(self, source, parser=None):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	575 """Load external XML document into element tree.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	576
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	577 source is a file name or file object, parser is an optional parser
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	578 instance that defaults to XMLParser.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	579
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	580 ParseError is raised if the parser fails to parse the document.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	581
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	582 Returns the root element of the given source document.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	583
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	584 """
65707 cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	585 close_source = False
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	586 if not hasattr(source, "read"):
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	587 source = open(source, "rb")
65707 cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	588 close_source = True
cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	589 try:
83852 8425e8cc2bf2 Get rid of ugly code duplication for ElementTree.parse when the accelerator Eli Bendersky <eliben@gmail.com> parents: 83848 diff changeset	590 if parser is None:
8425e8cc2bf2 Get rid of ugly code duplication for ElementTree.parse when the accelerator Eli Bendersky <eliben@gmail.com> parents: 83848 diff changeset	591 # If no parser was specified, create a default XMLParser
8425e8cc2bf2 Get rid of ugly code duplication for ElementTree.parse when the accelerator Eli Bendersky <eliben@gmail.com> parents: 83848 diff changeset	592 parser = XMLParser()
8425e8cc2bf2 Get rid of ugly code duplication for ElementTree.parse when the accelerator Eli Bendersky <eliben@gmail.com> parents: 83848 diff changeset	593 if hasattr(parser, '_parse_whole'):
8425e8cc2bf2 Get rid of ugly code duplication for ElementTree.parse when the accelerator Eli Bendersky <eliben@gmail.com> parents: 83848 diff changeset	594 # The default XMLParser, when it comes from an accelerator,
8425e8cc2bf2 Get rid of ugly code duplication for ElementTree.parse when the accelerator Eli Bendersky <eliben@gmail.com> parents: 83848 diff changeset	595 # can define an internal _parse_whole API for efficiency.
8425e8cc2bf2 Get rid of ugly code duplication for ElementTree.parse when the accelerator Eli Bendersky <eliben@gmail.com> parents: 83848 diff changeset	596 # It can be used to parse the whole source without feeding
8425e8cc2bf2 Get rid of ugly code duplication for ElementTree.parse when the accelerator Eli Bendersky <eliben@gmail.com> parents: 83848 diff changeset	597 # it with chunks.
8425e8cc2bf2 Get rid of ugly code duplication for ElementTree.parse when the accelerator Eli Bendersky <eliben@gmail.com> parents: 83848 diff changeset	598 self._root = parser._parse_whole(source)
8425e8cc2bf2 Get rid of ugly code duplication for ElementTree.parse when the accelerator Eli Bendersky <eliben@gmail.com> parents: 83848 diff changeset	599 return self._root
8425e8cc2bf2 Get rid of ugly code duplication for ElementTree.parse when the accelerator Eli Bendersky <eliben@gmail.com> parents: 83848 diff changeset	600 while True:
65707 cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	601 data = source.read(65536)
cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	602 if not data:
cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	603 break
cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	604 parser.feed(data)
cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	605 self._root = parser.close()
cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	606 return self._root
cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	607 finally:
cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	608 if close_source:
cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	609 source.close()
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	610
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	611 def iter(self, tag=None):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	612 """Create and return tree iterator for the root element.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	613
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	614 The iterator loops over all elements in this tree, in document order.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	615
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	616 tag is a string with the tag name to iterate over
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	617 (default is to return all elements).
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	618
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	619 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	620 # assert self._root is not None
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	621 return self._root.iter(tag)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	622
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	623 # compatibility
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	624 def getiterator(self, tag=None):
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	625 # Change for a DeprecationWarning in 1.4
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	626 warnings.warn(
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	627 "This method will be removed in future versions. "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	628 "Use 'tree.iter()' or 'list(tree.iter())' instead.",
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	629 PendingDeprecationWarning, stacklevel=2
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	630 )
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	631 return list(self.iter(tag))
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	632
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	633 def find(self, path, namespaces=None):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	634 """Find first matching element by tag name or path.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	635
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	636 Same as getroot().find(path), which is Element.find()
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	637
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	638 path is a string having either an element tag or an XPath,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	639 namespaces is an optional mapping from namespace prefix to full name.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	640
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	641 Return the first matching element, or None if no element was found.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	642
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	643 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	644 # assert self._root is not None
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	645 if path[:1] == "/":
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	646 path = "." + path
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	647 warnings.warn(
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	648 "This search is broken in 1.3 and earlier, and will be "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	649 "fixed in a future version. If you rely on the current "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	650 "behaviour, change it to %r" % path,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	651 FutureWarning, stacklevel=2
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	652 )
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	653 return self._root.find(path, namespaces)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	654
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	655 def findtext(self, path, default=None, namespaces=None):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	656 """Find first matching element by tag name or path.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	657
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	658 Same as getroot().findtext(path), which is Element.findtext()
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	659
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	660 path is a string having either an element tag or an XPath,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	661 namespaces is an optional mapping from namespace prefix to full name.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	662
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	663 Return the first matching element, or None if no element was found.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	664
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	665 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	666 # assert self._root is not None
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	667 if path[:1] == "/":
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	668 path = "." + path
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	669 warnings.warn(
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	670 "This search is broken in 1.3 and earlier, and will be "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	671 "fixed in a future version. If you rely on the current "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	672 "behaviour, change it to %r" % path,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	673 FutureWarning, stacklevel=2
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	674 )
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	675 return self._root.findtext(path, default, namespaces)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	676
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	677 def findall(self, path, namespaces=None):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	678 """Find all matching subelements by tag name or path.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	679
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	680 Same as getroot().findall(path), which is Element.findall().
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	681
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	682 path is a string having either an element tag or an XPath,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	683 namespaces is an optional mapping from namespace prefix to full name.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	684
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	685 Return list containing all matching elements in document order.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	686
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	687 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	688 # assert self._root is not None
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	689 if path[:1] == "/":
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	690 path = "." + path
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	691 warnings.warn(
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	692 "This search is broken in 1.3 and earlier, and will be "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	693 "fixed in a future version. If you rely on the current "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	694 "behaviour, change it to %r" % path,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	695 FutureWarning, stacklevel=2
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	696 )
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	697 return self._root.findall(path, namespaces)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	698
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	699 def iterfind(self, path, namespaces=None):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	700 """Find all matching subelements by tag name or path.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	701
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	702 Same as getroot().iterfind(path), which is element.iterfind()
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	703
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	704 path is a string having either an element tag or an XPath,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	705 namespaces is an optional mapping from namespace prefix to full name.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	706
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	707 Return an iterable yielding all matching elements in document order.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	708
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	709 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	710 # assert self._root is not None
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	711 if path[:1] == "/":
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	712 path = "." + path
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	713 warnings.warn(
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	714 "This search is broken in 1.3 and earlier, and will be "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	715 "fixed in a future version. If you rely on the current "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	716 "behaviour, change it to %r" % path,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	717 FutureWarning, stacklevel=2
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	718 )
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	719 return self._root.iterfind(path, namespaces)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	720
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	721 def write(self, file_or_filename,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	722 encoding=None,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	723 xml_declaration=None,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	724 default_namespace=None,
81488 58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	725 method=None, *,
58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	726 short_empty_elements=True):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	727 """Write element tree to a file as XML.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	728
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	729 Arguments:
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	730 file_or_filename -- file name or a file object opened for writing
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	731
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	732 encoding -- the output encoding (default: US-ASCII)
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	733
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	734 xml_declaration -- bool indicating if an XML declaration should be
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	735 added to the output. If None, an XML declaration
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	736 is added if encoding IS NOT either of:
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	737 US-ASCII, UTF-8, or Unicode
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	738
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	739 default_namespace -- sets the default XML namespace (for "xmlns")
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	740
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	741 method -- either "xml" (default), "html, "text", or "c14n"
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	742
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	743 short_empty_elements -- controls the formatting of elements
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	744 that contain no content. If True (default)
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	745 they are emitted as a single self-closed
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	746 tag, otherwise they are emitted as a pair
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	747 of start/end tags
81490 f0e80c7404a5 Cleanup the docs ElementTree a bit and describe the default_namespace parameter. In the code, replace the old outdated Doxygen-ish comment above ElementTree.write by a proper docstring. Eli Bendersky <eliben@gmail.com> parents: 81488 diff changeset	748
f0e80c7404a5 Cleanup the docs ElementTree a bit and describe the default_namespace parameter. In the code, replace the old outdated Doxygen-ish comment above ElementTree.write by a proper docstring. Eli Bendersky <eliben@gmail.com> parents: 81488 diff changeset	749 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	750 if not method:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	751 method = "xml"
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	752 elif method not in _serialize:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	753 raise ValueError("unknown method %r" % method)
63845 57e631f088d7 Issue #8047: Fix the xml.etree serializer to return bytes by default. Florent Xicluna <florent.xicluna@gmail.com> parents: 59601 diff changeset	754 if not encoding:
57e631f088d7 Issue #8047: Fix the xml.etree serializer to return bytes by default. Florent Xicluna <florent.xicluna@gmail.com> parents: 59601 diff changeset	755 if method == "c14n":
57e631f088d7 Issue #8047: Fix the xml.etree serializer to return bytes by default. Florent Xicluna <florent.xicluna@gmail.com> parents: 59601 diff changeset	756 encoding = "utf-8"
57e631f088d7 Issue #8047: Fix the xml.etree serializer to return bytes by default. Florent Xicluna <florent.xicluna@gmail.com> parents: 59601 diff changeset	757 else:
57e631f088d7 Issue #8047: Fix the xml.etree serializer to return bytes by default. Florent Xicluna <florent.xicluna@gmail.com> parents: 59601 diff changeset	758 encoding = "us-ascii"
57e631f088d7 Issue #8047: Fix the xml.etree serializer to return bytes by default. Florent Xicluna <florent.xicluna@gmail.com> parents: 59601 diff changeset	759 else:
57e631f088d7 Issue #8047: Fix the xml.etree serializer to return bytes by default. Florent Xicluna <florent.xicluna@gmail.com> parents: 59601 diff changeset	760 encoding = encoding.lower()
78105 6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	761 with _get_writer(file_or_filename, encoding) as write:
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	762 if method == "xml" and (xml_declaration or
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	763 (xml_declaration is None and
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	764 encoding not in ("utf-8", "us-ascii", "unicode"))):
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	765 declared_encoding = encoding
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	766 if encoding == "unicode":
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	767 # Retrieve the default encoding for the xml declaration
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	768 import locale
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	769 declared_encoding = locale.getpreferredencoding()
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	770 write("<?xml version='1.0' encoding='%s'?>\n" % (
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	771 declared_encoding,))
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	772 if method == "text":
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	773 _serialize_text(write, self._root)
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	774 else:
78105 6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	775 qnames, namespaces = _namespaces(self._root, default_namespace)
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	776 serialize = _serialize[method]
81488 58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	777 serialize(write, self._root, qnames, namespaces,
58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	778 short_empty_elements=short_empty_elements)
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	779
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	780 def write_c14n(self, file):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	781 # lxml.etree compatibility. use output method instead
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	782 return self.write(file, method="c14n")
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	783
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	784 # --------------------------------------------------------------------
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	785 # serialization support
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	786
78105 6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	787 @contextlib.contextmanager
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	788 def _get_writer(file_or_filename, encoding):
85228 9e4685d703d4 #18741: fix more typos. Patch by Févry Thibault. Ezio Melotti <ezio.melotti@gmail.com> parents: 84449 diff changeset	789 # returns text write method and release all resources after using
78105 6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	790 try:
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	791 write = file_or_filename.write
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	792 except AttributeError:
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	793 # file_or_filename is a file name
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	794 if encoding == "unicode":
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	795 file = open(file_or_filename, "w")
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	796 else:
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	797 file = open(file_or_filename, "w", encoding=encoding,
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	798 errors="xmlcharrefreplace")
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	799 with file:
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	800 yield file.write
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	801 else:
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	802 # file_or_filename is a file-like object
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	803 # encoding determines if it is a text or binary writer
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	804 if encoding == "unicode":
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	805 # use a text writer as is
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	806 yield write
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	807 else:
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	808 # wrap a binary writer with TextIOWrapper
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	809 with contextlib.ExitStack() as stack:
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	810 if isinstance(file_or_filename, io.BufferedIOBase):
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	811 file = file_or_filename
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	812 elif isinstance(file_or_filename, io.RawIOBase):
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	813 file = io.BufferedWriter(file_or_filename)
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	814 # Keep the original file open when the BufferedWriter is
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	815 # destroyed
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	816 stack.callback(file.detach)
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	817 else:
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	818 # This is to handle passed objects that aren't in the
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	819 # IOBase hierarchy, but just have a write method
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	820 file = io.BufferedIOBase()
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	821 file.writable = lambda: True
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	822 file.write = write
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	823 try:
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	824 # TextIOWrapper uses this methods to determine
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	825 # if BOM (for UTF-16, etc) should be added
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	826 file.seekable = file_or_filename.seekable
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	827 file.tell = file_or_filename.tell
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	828 except AttributeError:
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	829 pass
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	830 file = io.TextIOWrapper(file,
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	831 encoding=encoding,
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	832 errors="xmlcharrefreplace",
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	833 newline="\n")
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	834 # Keep the original file open when the TextIOWrapper is
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	835 # destroyed
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	836 stack.callback(file.detach)
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	837 yield file.write
6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	838
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	839 def _namespaces(elem, default_namespace=None):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	840 # identify namespaces used in this tree
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	841
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	842 # maps qnames to encoded prefix:local names
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	843 qnames = {None: None}
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	844
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	845 # maps uri:s to prefixes
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	846 namespaces = {}
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	847 if default_namespace:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	848 namespaces[default_namespace] = ""
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	849
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	850 def add_qname(qname):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	851 # calculate serialized qname representation
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	852 try:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	853 if qname[:1] == "{":
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	854 uri, tag = qname[1:].rsplit("}", 1)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	855 prefix = namespaces.get(uri)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	856 if prefix is None:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	857 prefix = _namespace_map.get(uri)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	858 if prefix is None:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	859 prefix = "ns%d" % len(namespaces)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	860 if prefix != "xml":
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	861 namespaces[uri] = prefix
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	862 if prefix:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	863 qnames[qname] = "%s:%s" % (prefix, tag)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	864 else:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	865 qnames[qname] = tag # default element
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	866 else:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	867 if default_namespace:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	868 # FIXME: can this be handled in XML 1.0?
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	869 raise ValueError(
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	870 "cannot use non-qualified names with "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	871 "default_namespace option"
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	872 )
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	873 qnames[qname] = qname
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	874 except TypeError:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	875 _raise_serialization_error(qname)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	876
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	877 # populate qname and namespaces table
77431 652d148bdc1d Replace the iter/itertext methods of Element in _elementtree with true C implementations, instead of the bootstrapped Python code. In addition to being cleaner (removing the last remains of the bootstrapping code in _elementtree), this gives a 10x performance boost for iter() on large documents. Eli Bendersky <eliben@gmail.com> parents: 77217 diff changeset	878 for elem in elem.iter():
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	879 tag = elem.tag
66099 9a66feb07a0a Fix Issue10205 - XML QName error when different tags have same QName. Senthil Kumaran <orsenthil@gmail.com> parents: 65707 diff changeset	880 if isinstance(tag, QName):
9a66feb07a0a Fix Issue10205 - XML QName error when different tags have same QName. Senthil Kumaran <orsenthil@gmail.com> parents: 65707 diff changeset	881 if tag.text not in qnames:
9a66feb07a0a Fix Issue10205 - XML QName error when different tags have same QName. Senthil Kumaran <orsenthil@gmail.com> parents: 65707 diff changeset	882 add_qname(tag.text)
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	883 elif isinstance(tag, str):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	884 if tag not in qnames:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	885 add_qname(tag)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	886 elif tag is not None and tag is not Comment and tag is not PI:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	887 _raise_serialization_error(tag)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	888 for key, value in elem.items():
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	889 if isinstance(key, QName):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	890 key = key.text
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	891 if key not in qnames:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	892 add_qname(key)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	893 if isinstance(value, QName) and value.text not in qnames:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	894 add_qname(value.text)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	895 text = elem.text
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	896 if isinstance(text, QName) and text.text not in qnames:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	897 add_qname(text.text)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	898 return qnames, namespaces
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	899
81488 58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	900 def _serialize_xml(write, elem, qnames, namespaces,
58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	901 short_empty_elements, **kwargs):
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	902 tag = elem.tag
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	903 text = elem.text
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	904 if tag is Comment:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	905 write("<!--%s-->" % text)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	906 elif tag is ProcessingInstruction:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	907 write("<?%s?>" % text)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	908 else:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	909 tag = qnames[tag]
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	910 if tag is None:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	911 if text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	912 write(_escape_cdata(text))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	913 for e in elem:
81488 58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	914 _serialize_xml(write, e, qnames, None,
58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	915 short_empty_elements=short_empty_elements)
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	916 else:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	917 write("<" + tag)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	918 items = list(elem.items())
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	919 if items or namespaces:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	920 if namespaces:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	921 for v, k in sorted(namespaces.items(),
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	922 key=lambda x: x[1]): # sort on prefix
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	923 if k:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	924 k = ":" + k
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	925 write(" xmlns%s=\"%s\"" % (
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	926 k,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	927 _escape_attrib(v)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	928 ))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	929 for k, v in sorted(items): # lexical order
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	930 if isinstance(k, QName):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	931 k = k.text
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	932 if isinstance(v, QName):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	933 v = qnames[v.text]
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	934 else:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	935 v = _escape_attrib(v)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	936 write(" %s=\"%s\"" % (qnames[k], v))
81488 58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	937 if text or len(elem) or not short_empty_elements:
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	938 write(">")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	939 if text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	940 write(_escape_cdata(text))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	941 for e in elem:
81488 58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	942 _serialize_xml(write, e, qnames, None,
58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	943 short_empty_elements=short_empty_elements)
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	944 write("</" + tag + ">")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	945 else:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	946 write(" />")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	947 if elem.tail:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	948 write(_escape_cdata(elem.tail))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	949
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	950 HTML_EMPTY = ("area", "base", "basefont", "br", "col", "frame", "hr",
79051 17c528cff63f #15970: xml.etree.ElementTree now serializes correctly the empty HTML elements "meta" and "param". Ezio Melotti <ezio.melotti@gmail.com> parents: 73291 diff changeset	951 "img", "input", "isindex", "link", "meta", "param")
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	952
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	953 try:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	954 HTML_EMPTY = set(HTML_EMPTY)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	955 except NameError:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	956 pass
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	957
81488 58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	958 def _serialize_html(write, elem, qnames, namespaces, **kwargs):
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	959 tag = elem.tag
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	960 text = elem.text
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	961 if tag is Comment:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	962 write("<!--%s-->" % _escape_cdata(text))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	963 elif tag is ProcessingInstruction:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	964 write("<?%s?>" % _escape_cdata(text))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	965 else:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	966 tag = qnames[tag]
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	967 if tag is None:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	968 if text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	969 write(_escape_cdata(text))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	970 for e in elem:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	971 _serialize_html(write, e, qnames, None)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	972 else:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	973 write("<" + tag)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	974 items = list(elem.items())
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	975 if items or namespaces:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	976 if namespaces:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	977 for v, k in sorted(namespaces.items(),
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	978 key=lambda x: x[1]): # sort on prefix
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	979 if k:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	980 k = ":" + k
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	981 write(" xmlns%s=\"%s\"" % (
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	982 k,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	983 _escape_attrib(v)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	984 ))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	985 for k, v in sorted(items): # lexical order
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	986 if isinstance(k, QName):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	987 k = k.text
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	988 if isinstance(v, QName):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	989 v = qnames[v.text]
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	990 else:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	991 v = _escape_attrib_html(v)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	992 # FIXME: handle boolean attributes
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	993 write(" %s=\"%s\"" % (qnames[k], v))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	994 write(">")
84449 df79735b21c1 Issue #18347: ElementTree's html serializer now preserves the case of closing tags. Christian Heimes <christian@cheimes.de> parents: 82629 diff changeset	995 ltag = tag.lower()
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	996 if text:
84449 df79735b21c1 Issue #18347: ElementTree's html serializer now preserves the case of closing tags. Christian Heimes <christian@cheimes.de> parents: 82629 diff changeset	997 if ltag == "script" or ltag == "style":
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	998 write(text)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	999 else:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1000 write(_escape_cdata(text))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1001 for e in elem:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1002 _serialize_html(write, e, qnames, None)
84449 df79735b21c1 Issue #18347: ElementTree's html serializer now preserves the case of closing tags. Christian Heimes <christian@cheimes.de> parents: 82629 diff changeset	1003 if ltag not in HTML_EMPTY:
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1004 write("</" + tag + ">")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1005 if elem.tail:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1006 write(_escape_cdata(elem.tail))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1007
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1008 def _serialize_text(write, elem):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1009 for part in elem.itertext():
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1010 write(part)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1011 if elem.tail:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1012 write(elem.tail)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1013
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1014 _serialize = {
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1015 "xml": _serialize_xml,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1016 "html": _serialize_html,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1017 "text": _serialize_text,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1018 # this optional method is imported at the end of the module
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1019 # "c14n": _serialize_c14n,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1020 }
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1021
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1022
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1023 def register_namespace(prefix, uri):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1024 """Register a namespace prefix.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1025
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1026 The registry is global, and any existing mapping for either the
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1027 given prefix or the namespace URI will be removed.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1028
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1029 prefix is the namespace prefix, uri is a namespace uri. Tags and
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1030 attributes in this namespace will be serialized with prefix if possible.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1031
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1032 ValueError is raised if prefix is reserved or is invalid.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1033
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1034 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1035 if re.match("ns\d+$", prefix):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1036 raise ValueError("Prefix format reserved for internal use")
67170 7d551d5ef4fc #10777: fix iteration over dict keys while mutating the dict. Georg Brandl <georg@python.org> parents: 66810 diff changeset	1037 for k, v in list(_namespace_map.items()):
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1038 if k == uri or v == prefix:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1039 del _namespace_map[k]
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1040 _namespace_map[uri] = prefix
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1041
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1042 _namespace_map = {
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1043 # "well-known" namespace prefixes
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1044 "http://www.w3.org/XML/1998/namespace": "xml",
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1045 "http://www.w3.org/1999/xhtml": "html",
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1046 "http://www.w3.org/1999/02/22-rdf-syntax-ns#": "rdf",
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1047 "http://schemas.xmlsoap.org/wsdl/": "wsdl",
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1048 # xml schema
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1049 "http://www.w3.org/2001/XMLSchema": "xs",
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1050 "http://www.w3.org/2001/XMLSchema-instance": "xsi",
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1051 # dublin core
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1052 "http://purl.org/dc/elements/1.1/": "dc",
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1053 }
74991 cdc9e0238b1d fix the _namespace_map cleanup for cElementTree tests. Florent Xicluna <florent.xicluna@gmail.com> parents: 74903 diff changeset	1054 # For tests and troubleshooting
cdc9e0238b1d fix the _namespace_map cleanup for cElementTree tests. Florent Xicluna <florent.xicluna@gmail.com> parents: 74903 diff changeset	1055 register_namespace._namespace_map = _namespace_map
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1056
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1057 def _raise_serialization_error(text):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1058 raise TypeError(
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1059 "cannot serialize %r (type %s)" % (text, type(text).__name__)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1060 )
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1061
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1062 def _escape_cdata(text):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1063 # escape character data
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1064 try:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1065 # it's worth avoiding do-nothing calls for strings that are
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1066 # shorter than 500 character, or so. assume that's, by far,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1067 # the most common case in most applications.
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1068 if "&" in text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1069 text = text.replace("&", "&")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1070 if "<" in text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1071 text = text.replace("<", "<")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1072 if ">" in text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1073 text = text.replace(">", ">")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1074 return text
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1075 except (TypeError, AttributeError):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1076 _raise_serialization_error(text)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1077
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1078 def _escape_attrib(text):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1079 # escape attribute value
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1080 try:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1081 if "&" in text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1082 text = text.replace("&", "&")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1083 if "<" in text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1084 text = text.replace("<", "<")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1085 if ">" in text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1086 text = text.replace(">", ">")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1087 if "\"" in text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1088 text = text.replace("\"", """)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1089 if "\n" in text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1090 text = text.replace("\n", " ")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1091 return text
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1092 except (TypeError, AttributeError):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1093 _raise_serialization_error(text)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1094
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1095 def _escape_attrib_html(text):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1096 # escape attribute value
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1097 try:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1098 if "&" in text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1099 text = text.replace("&", "&")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1100 if ">" in text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1101 text = text.replace(">", ">")
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1102 if "\"" in text:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1103 text = text.replace("\"", """)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1104 return text
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1105 except (TypeError, AttributeError):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1106 _raise_serialization_error(text)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1107
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1108 # --------------------------------------------------------------------
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1109
81488 58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	1110 def tostring(element, encoding=None, method=None, *,
58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	1111 short_empty_elements=True):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1112 """Generate string representation of XML element.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1113
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1114 All subelements are included. If encoding is "unicode", a string
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1115 is returned. Otherwise a bytestring is returned.
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1116
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1117 element is an Element instance, encoding is an optional output
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1118 encoding defaulting to US-ASCII, method is an optional output which can
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1119 be one of "xml" (default), "html", "text" or "c14n".
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1120
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1121 Returns an (optionally) encoded string containing the XML data.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1122
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1123 """
78105 6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	1124 stream = io.StringIO() if encoding == 'unicode' else io.BytesIO()
81488 58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	1125 ElementTree(element).write(stream, encoding, method=method,
58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	1126 short_empty_elements=short_empty_elements)
78105 6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	1127 return stream.getvalue()
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1128
78156 51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1129 class _ListDataStream(io.BufferedIOBase):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1130 """An auxiliary stream accumulating into a list reference."""
78156 51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1131 def __init__(self, lst):
51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1132 self.lst = lst
78157 63ba0c32b81a fix whitespace woes Eli Bendersky <eliben@gmail.com> parents: 78156 diff changeset	1133
78156 51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1134 def writable(self):
51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1135 return True
78105 6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	1136
78156 51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1137 def seekable(self):
51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1138 return True
78145 64ff90e07d71 Preserve the invariant tostring(elem) == b''.join(tostringlist(elem)) and add a test to make sure it keeps working Eli Bendersky <eliben@gmail.com> parents: 78105 diff changeset	1139
78156 51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1140 def write(self, b):
51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1141 self.lst.append(b)
51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1142
51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1143 def tell(self):
51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1144 return len(self.lst)
78105 6120cf695574 Close #1767933: Badly formed XML using etree and utf-16. Patch by Serhiy Storchaka, with some minor fixes by me Eli Bendersky <eliben@gmail.com> parents: 77963 diff changeset	1145
81488 58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	1146 def tostringlist(element, encoding=None, method=None, *,
58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	1147 short_empty_elements=True):
78156 51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1148 lst = []
51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1149 stream = _ListDataStream(lst)
81488 58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	1150 ElementTree(element).write(stream, encoding, method=method,
58168d69b496 Close #14377: Add a new parameter to ElementTree.write and some module-level Eli Bendersky <eliben@gmail.com> parents: 79461 diff changeset	1151 short_empty_elements=short_empty_elements)
78156 51978f89e5ed Optimize tostringlist by taking the stream class outside the function. It's now 2x faster on short calls. Related to #1767933 Eli Bendersky <eliben@gmail.com> parents: 78145 diff changeset	1152 return lst
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1153
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1154
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1155 def dump(elem):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1156 """Write element tree or element structure to sys.stdout.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1157
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1158 This function should be used for debugging only.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1159
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1160 elem is either an ElementTree, or a single Element. The exact output
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1161 format is implementation dependent. In this version, it's written as an
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1162 ordinary XML file.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1163
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1164 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1165 # debugging
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1166 if not isinstance(elem, ElementTree):
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1167 elem = ElementTree(elem)
63845 57e631f088d7 Issue #8047: Fix the xml.etree serializer to return bytes by default. Florent Xicluna <florent.xicluna@gmail.com> parents: 59601 diff changeset	1168 elem.write(sys.stdout, encoding="unicode")
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1169 tail = elem.getroot().tail
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1170 if not tail or tail[-1] != "\n":
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1171 sys.stdout.write("\n")
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1172
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1173 # --------------------------------------------------------------------
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1174 # parsing
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1175
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1176
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1177 def parse(source, parser=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1178 """Parse XML document into element tree.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1179
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1180 source is a filename or file object containing XML data,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1181 parser is an optional parser instance defaulting to XMLParser.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1182
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1183 Return an ElementTree instance.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1184
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1185 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1186 tree = ElementTree()
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1187 tree.parse(source, parser)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1188 return tree
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1189
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1190
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1191 def iterparse(source, events=None, parser=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1192 """Incrementally parse XML document into ElementTree.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1193
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1194 This class also reports what's going on to the user based on the
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1195 events it is initialized with. The supported events are the strings
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1196 "start", "end", "start-ns" and "end-ns" (the "ns" events are used to get
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1197 detailed namespace information). If events is omitted, only
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1198 "end" events are reported.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1199
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1200 source is a filename or file object containing XML data, events is
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1201 a list of events to report back, parser is an optional parser instance.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1202
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1203 Returns an iterator providing (event, elem) pairs.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1204
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1205 """
65707 cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	1206 close_source = False
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1207 if not hasattr(source, "read"):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1208 source = open(source, "rb")
65707 cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	1209 close_source = True
cff78ffb932a Issue #10093: ResourceWarnings are now issued when files and sockets are Antoine Pitrou <solipsis@pitrou.net> parents: 63845 diff changeset	1210 return _IterParseIterator(source, events, parser, close_source)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1211
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1212
85461 8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1213 class XMLPullParser:
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1214
85461 8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1215 def __init__(self, events=None, *, _parser=None):
8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1216 # The _parser argument is for internal use only and must not be relied
8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1217 # upon in user code. It will be removed in a future release.
8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1218 # See http://bugs.python.org/issue17741 for more details.
8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1219
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1220 # _elementtree.c expects a list, not a deque
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1221 self._events_queue = []
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1222 self._index = 0
85461 8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1223 self._parser = _parser or XMLParser(target=TreeBuilder())
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1224 # wire up the parser for event reporting
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1225 if events is None:
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1226 events = ("end",)
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1227 self._parser._setevents(self._events_queue, events)
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1228
85461 8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1229 def feed(self, data):
85817 c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1230 """Feed encoded data to parser."""
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1231 if self._parser is None:
85461 8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1232 raise ValueError("feed() called after end of stream")
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1233 if data:
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1234 try:
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1235 self._parser.feed(data)
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1236 except SyntaxError as exc:
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1237 self._events_queue.append(exc)
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1238
85817 c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1239 def _close_and_return_root(self):
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1240 # iterparse needs this to set its root attribute properly :(
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1241 root = self._parser.close()
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1242 self._parser = None
85817 c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1243 return root
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1244
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1245 def close(self):
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1246 """Finish feeding data to parser.
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1247
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1248 Unlike XMLParser, does not return the root element. Use
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1249 read_events() to consume elements from XMLPullParser.
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1250 """
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1251 self._close_and_return_root()
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1252
85461 8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1253 def read_events(self):
85817 c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1254 """Iterate over currently available (event, elem) pairs.
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1255
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1256 Events are consumed from the internal event queue as they are
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1257 retrieved from the iterator.
c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1258 """
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1259 events = self._events_queue
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1260 while True:
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1261 index = self._index
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1262 try:
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1263 event = events[self._index]
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1264 # Avoid retaining references to past events
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1265 events[self._index] = None
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1266 except IndexError:
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1267 break
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1268 index += 1
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1269 # Compact the list in a O(1) amortized fashion
85817 c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1270 # As noted above, _elementree.c needs a list, not a deque
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1271 if index * 2 >= len(events):
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1272 events[:index] = []
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1273 self._index = 0
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1274 else:
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1275 self._index = index
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1276 if isinstance(event, Exception):
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1277 raise event
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1278 else:
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1279 yield event
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1280
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1281
85353 815f328a6578 Issue #17741: use composition, rather than inheritance, for xml.etree.iterparse's result class. Antoine Pitrou <solipsis@pitrou.net> parents: 85229 diff changeset	1282 class _IterParseIterator:
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1283
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1284 def __init__(self, source, events, parser, close_source=False):
85461 8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1285 # Use the internal, undocumented _parser argument for now; When the
8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1286 # parser argument of iterparse is removed, this can be killed.
8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1287 self._parser = XMLPullParser(events=events, _parser=parser)
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1288 self._file = source
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1289 self._close_file = close_source
85817 c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1290 self.root = self._root = None
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1291
41501 0c5019afc55b PEP 3114: rename .next() to .__next__() and add next() builtin. Georg Brandl <georg@python.org> parents: 41480 diff changeset	1292 def __next__(self):
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1293 while 1:
85461 8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1294 for event in self._parser.read_events():
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1295 return event
85353 815f328a6578 Issue #17741: use composition, rather than inheritance, for xml.etree.iterparse's result class. Antoine Pitrou <solipsis@pitrou.net> parents: 85229 diff changeset	1296 if self._parser._parser is None:
85817 c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1297 self.root = self._root
73291 23ffaf975267 Closes #2892: preserve iterparse events in case of SyntaxError. Florent Xicluna <florent.xicluna@gmail.com> parents: 67170 diff changeset	1298 if self._close_file:
23ffaf975267 Closes #2892: preserve iterparse events in case of SyntaxError. Florent Xicluna <florent.xicluna@gmail.com> parents: 67170 diff changeset	1299 self._file.close()
23ffaf975267 Closes #2892: preserve iterparse events in case of SyntaxError. Florent Xicluna <florent.xicluna@gmail.com> parents: 67170 diff changeset	1300 raise StopIteration
23ffaf975267 Closes #2892: preserve iterparse events in case of SyntaxError. Florent Xicluna <florent.xicluna@gmail.com> parents: 67170 diff changeset	1301 # load event buffer
85461 8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1302 data = self._file.read(16 * 1024)
73291 23ffaf975267 Closes #2892: preserve iterparse events in case of SyntaxError. Florent Xicluna <florent.xicluna@gmail.com> parents: 67170 diff changeset	1303 if data:
85461 8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1304 self._parser.feed(data)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1305 else:
85817 c5e206b9df2e Close #18990: remove root attribute from XMLPullParser Nick Coghlan <ncoghlan@gmail.com> parents: 85461 diff changeset	1306 self._root = self._parser._close_and_return_root()
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1307
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1308 def __iter__(self):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1309 return self
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1310
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1311
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1312 def XML(text, parser=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1313 """Parse XML document from string constant.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1314
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1315 This function can be used to embed "XML Literals" in Python code.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1316
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1317 text is a string containing XML data, parser is an
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1318 optional parser instance, defaulting to the standard XMLParser.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1319
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1320 Returns an Element instance.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1321
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1322 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1323 if not parser:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1324 parser = XMLParser(target=TreeBuilder())
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1325 parser.feed(text)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1326 return parser.close()
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1327
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1328
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1329 def XMLID(text, parser=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1330 """Parse XML document from string constant for its IDs.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1331
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1332 text is a string containing XML data, parser is an
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1333 optional parser instance, defaulting to the standard XMLParser.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1334
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1335 Returns an (Element, dict) tuple, in which the
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1336 dict maps element id:s to elements.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1337
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1338 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1339 if not parser:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1340 parser = XMLParser(target=TreeBuilder())
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1341 parser.feed(text)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1342 tree = parser.close()
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1343 ids = {}
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1344 for elem in tree.iter():
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1345 id = elem.get("id")
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1346 if id:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1347 ids[id] = elem
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1348 return tree, ids
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1349
82957 313bcff51900 Issue #17516: use comment syntax for comments, instead of multiline string Victor Stinner <victor.stinner@gmail.com> parents: 82630 diff changeset	1350 # Parse XML document from string constant. Alias for XML().
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1351 fromstring = XML
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1352
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1353 def fromstringlist(sequence, parser=None):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1354 """Parse XML document from sequence of string fragments.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1355
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1356 sequence is a list of other sequence, parser is an optional parser
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1357 instance, defaulting to the standard XMLParser.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1358
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1359 Returns an Element instance.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1360
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1361 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1362 if not parser:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1363 parser = XMLParser(target=TreeBuilder())
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1364 for text in sequence:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1365 parser.feed(text)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1366 return parser.close()
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1367
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1368 # --------------------------------------------------------------------
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1369
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1370
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1371 class TreeBuilder:
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1372 """Generic element structure builder.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1373
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1374 This builder converts a sequence of start, data, and end method
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1375 calls to a well-formed element structure.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1376
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1377 You can use this class to build an element structure using a custom XML
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1378 parser, or a parser for some other XML-like format.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1379
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1380 element_factory is an optional element factory which is called
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1381 to create new Element instances, as necessary.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1382
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1383 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1384 def __init__(self, element_factory=None):
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1385 self._data = [] # data collector
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1386 self._elem = [] # element stack
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1387 self._last = None # last element
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1388 self._tail = None # true if we're after an end tag
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1389 if element_factory is None:
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1390 element_factory = Element
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1391 self._factory = element_factory
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1392
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1393 def close(self):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1394 """Flush builder buffers and return toplevel document Element."""
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1395 assert len(self._elem) == 0, "missing end tags"
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1396 assert self._last is not None, "missing toplevel element"
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1397 return self._last
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1398
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1399 def _flush(self):
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1400 if self._data:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1401 if self._last is not None:
41480 99027c2b3fd2 Remove functions in string module that are also string methods. Also remove: Neal Norwitz <nnorwitz@gmail.com> parents: 40809 diff changeset	1402 text = "".join(self._data)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1403 if self._tail:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1404 assert self._last.tail is None, "internal error (tail)"
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1405 self._last.tail = text
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1406 else:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1407 assert self._last.text is None, "internal error (text)"
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1408 self._last.text = text
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1409 self._data = []
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1410
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1411 def data(self, data):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1412 """Add text to current element."""
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1413 self._data.append(data)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1414
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1415 def start(self, tag, attrs):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1416 """Open new element and return it.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1417
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1418 tag is the element name, attrs is a dict containing element
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1419 attributes.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1420
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1421 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1422 self._flush()
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1423 self._last = elem = self._factory(tag, attrs)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1424 if self._elem:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1425 self._elem[-1].append(elem)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1426 self._elem.append(elem)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1427 self._tail = 0
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1428 return elem
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1429
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1430 def end(self, tag):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1431 """Close and return current Element.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1432
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1433 tag is the element name.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1434
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1435 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1436 self._flush()
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1437 self._last = self._elem.pop()
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1438 assert self._last.tag == tag,\
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1439 "end tag mismatch (expected %s, got %s)" % (
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1440 self._last.tag, tag)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1441 self._tail = 1
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1442 return self._last
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1443
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1444
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1445 # also see ElementTree and TreeBuilder
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1446 class XMLParser:
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1447 """Element structure builder for XML source data based on the expat parser.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1448
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1449 html are predefined HTML entities (not supported currently),
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1450 target is an optional target object which defaults to an instance of the
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1451 standard TreeBuilder class, encoding is an optional encoding string
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1452 which if given, overrides the encoding specified in the XML file:
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1453 http://www.iana.org/assignments/character-sets
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1454
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1455 """
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1456
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1457 def __init__(self, html=0, target=None, encoding=None):
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1458 try:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1459 from xml.parsers import expat
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1460 except ImportError:
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1461 try:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1462 import pyexpat as expat
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1463 except ImportError:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1464 raise ImportError(
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1465 "No module named expat; use SimpleXMLTreeBuilder instead"
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1466 )
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1467 parser = expat.ParserCreate(encoding, "}")
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1468 if target is None:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1469 target = TreeBuilder()
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1470 # underscored names are provided for compatibility only
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1471 self.parser = self._parser = parser
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1472 self.target = self._target = target
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1473 self._error = expat.error
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1474 self._names = {} # name memo cache
75411 47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1475 # main callbacks
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1476 parser.DefaultHandlerExpand = self._default
75411 47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1477 if hasattr(target, 'start'):
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1478 parser.StartElementHandler = self._start
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1479 if hasattr(target, 'end'):
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1480 parser.EndElementHandler = self._end
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1481 if hasattr(target, 'data'):
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1482 parser.CharacterDataHandler = target.data
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1483 # miscellaneous callbacks
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1484 if hasattr(target, 'comment'):
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1485 parser.CommentHandler = target.comment
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1486 if hasattr(target, 'pi'):
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1487 parser.ProcessingInstructionHandler = target.pi
85408 022bd6cd6c79 Remove the obsolete XMLParser._start/_start_list duality. Eli Bendersky <eliben@gmail.com> parents: 85353 diff changeset	1488 # Configure pyexpat: buffering, new-style attribute handling.
022bd6cd6c79 Remove the obsolete XMLParser._start/_start_list duality. Eli Bendersky <eliben@gmail.com> parents: 85353 diff changeset	1489 parser.buffer_text = 1
022bd6cd6c79 Remove the obsolete XMLParser._start/_start_list duality. Eli Bendersky <eliben@gmail.com> parents: 85353 diff changeset	1490 parser.ordered_attributes = 1
022bd6cd6c79 Remove the obsolete XMLParser._start/_start_list duality. Eli Bendersky <eliben@gmail.com> parents: 85353 diff changeset	1491 parser.specified_attributes = 1
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1492 self._doctype = None
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1493 self.entity = {}
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1494 try:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1495 self.version = "Expat %d.%d.%d" % expat.version_info
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1496 except AttributeError:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1497 pass # unknown
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1498
83843 b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1499 def _setevents(self, events_queue, events_to_report):
85461 8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1500 # Internal API for XMLPullParser
83843 b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1501 # events_to_report: a list of events to report during parsing (same as
85461 8fd72b1bb262 Issue #17741: Rename IncrementalParser and its methods. Eli Bendersky <eliben@gmail.com> parents: 85408 diff changeset	1502 # the events of XMLPullParser's constructor.
83843 b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1503 # events_queue: a list of actual parsing events that will be populated
b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1504 # by the underlying parser.
b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1505 #
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1506 parser = self._parser
83843 b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1507 append = events_queue.append
b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1508 for event_name in events_to_report:
b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1509 if event_name == "start":
83464 ec65d105588f Remove superfluous try/except Eli Bendersky <eliben@gmail.com> parents: 83459 diff changeset	1510 parser.ordered_attributes = 1
ec65d105588f Remove superfluous try/except Eli Bendersky <eliben@gmail.com> parents: 83459 diff changeset	1511 parser.specified_attributes = 1
83843 b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1512 def handler(tag, attrib_in, event=event_name, append=append,
85408 022bd6cd6c79 Remove the obsolete XMLParser._start/_start_list duality. Eli Bendersky <eliben@gmail.com> parents: 85353 diff changeset	1513 start=self._start):
83464 ec65d105588f Remove superfluous try/except Eli Bendersky <eliben@gmail.com> parents: 83459 diff changeset	1514 append((event, start(tag, attrib_in)))
ec65d105588f Remove superfluous try/except Eli Bendersky <eliben@gmail.com> parents: 83459 diff changeset	1515 parser.StartElementHandler = handler
83843 b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1516 elif event_name == "end":
b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1517 def handler(tag, event=event_name, append=append,
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1518 end=self._end):
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1519 append((event, end(tag)))
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1520 parser.EndElementHandler = handler
83843 b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1521 elif event_name == "start-ns":
b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1522 def handler(prefix, uri, event=event_name, append=append):
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1523 append((event, (prefix or "", uri or "")))
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1524 parser.StartNamespaceDeclHandler = handler
83843 b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1525 elif event_name == "end-ns":
b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1526 def handler(prefix, event=event_name, append=append):
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1527 append((event, None))
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1528 parser.EndNamespaceDeclHandler = handler
f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1529 else:
83843 b6c333579c2b _elementtree.XMLParser._setevents should support any sequence, not just tuples Eli Bendersky <eliben@gmail.com> parents: 83464 diff changeset	1530 raise ValueError("unknown event %r" % event_name)
83441 f903cf864191 Issue #17741: Add ElementTree.IncrementalParser, an event-driven parser for non-blocking applications. Antoine Pitrou <solipsis@pitrou.net> parents: 82957 diff changeset	1531
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1532 def _raiseerror(self, value):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1533 err = ParseError(value)
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1534 err.code = value.code
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1535 err.position = value.lineno, value.offset
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1536 raise err
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1537
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1538 def _fixname(self, key):
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1539 # expand qname, and convert name string to ascii, if possible
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1540 try:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1541 name = self._names[key]
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1542 except KeyError:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1543 name = key
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1544 if "}" in name:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1545 name = "{" + name
42388 d3471ef6fe38 Patch #1762412: Fix test case for struni branch. Martin v. Löwis <martin@v.loewis.de> parents: 41501 diff changeset	1546 self._names[key] = name
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1547 return name
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1548
85408 022bd6cd6c79 Remove the obsolete XMLParser._start/_start_list duality. Eli Bendersky <eliben@gmail.com> parents: 85353 diff changeset	1549 def _start(self, tag, attr_list):
022bd6cd6c79 Remove the obsolete XMLParser._start/_start_list duality. Eli Bendersky <eliben@gmail.com> parents: 85353 diff changeset	1550 # Handler for expat's StartElementHandler. Since ordered_attributes
022bd6cd6c79 Remove the obsolete XMLParser._start/_start_list duality. Eli Bendersky <eliben@gmail.com> parents: 85353 diff changeset	1551 # is set, the attributes are reported as a list of alternating
022bd6cd6c79 Remove the obsolete XMLParser._start/_start_list duality. Eli Bendersky <eliben@gmail.com> parents: 85353 diff changeset	1552 # attribute name,value.
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1553 fixname = self._fixname
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1554 tag = fixname(tag)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1555 attrib = {}
85408 022bd6cd6c79 Remove the obsolete XMLParser._start/_start_list duality. Eli Bendersky <eliben@gmail.com> parents: 85353 diff changeset	1556 if attr_list:
022bd6cd6c79 Remove the obsolete XMLParser._start/_start_list duality. Eli Bendersky <eliben@gmail.com> parents: 85353 diff changeset	1557 for i in range(0, len(attr_list), 2):
022bd6cd6c79 Remove the obsolete XMLParser._start/_start_list duality. Eli Bendersky <eliben@gmail.com> parents: 85353 diff changeset	1558 attrib[fixname(attr_list[i])] = attr_list[i+1]
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1559 return self.target.start(tag, attrib)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1560
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1561 def _end(self, tag):
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1562 return self.target.end(self._fixname(tag))
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1563
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1564 def _default(self, text):
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1565 prefix = text[:1]
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1566 if prefix == "&":
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1567 # deal with undefined entities
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1568 try:
75411 47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1569 data_handler = self.target.data
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1570 except AttributeError:
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1571 return
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1572 try:
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1573 data_handler(self.entity[text[1:-1]])
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1574 except KeyError:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1575 from xml.parsers import expat
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1576 err = expat.error(
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1577 "undefined entity %s: line %d, column %d" %
75411 47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1578 (text, self.parser.ErrorLineNumber,
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1579 self.parser.ErrorColumnNumber)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1580 )
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1581 err.code = 11 # XML_ERROR_UNDEFINED_ENTITY
75411 47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1582 err.lineno = self.parser.ErrorLineNumber
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1583 err.offset = self.parser.ErrorColumnNumber
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1584 raise err
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1585 elif prefix == "<" and text[:9] == "<!DOCTYPE":
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1586 self._doctype = [] # inside a doctype declaration
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1587 elif self._doctype is not None:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1588 # parse doctype contents
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1589 if prefix == ">":
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1590 self._doctype = None
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1591 return
41480 99027c2b3fd2 Remove functions in string module that are also string methods. Also remove: Neal Norwitz <nnorwitz@gmail.com> parents: 40809 diff changeset	1592 text = text.strip()
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1593 if not text:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1594 return
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1595 self._doctype.append(text)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1596 n = len(self._doctype)
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1597 if n > 2:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1598 type = self._doctype[1]
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1599 if type == "PUBLIC" and n == 4:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1600 name, type, pubid, system = self._doctype
77963 5c1efcd53b8b Minor refactoring in xml.etree.ElementTree doctype parser. Florent Xicluna <florent.xicluna@gmail.com> parents: 77434 diff changeset	1601 if pubid:
5c1efcd53b8b Minor refactoring in xml.etree.ElementTree doctype parser. Florent Xicluna <florent.xicluna@gmail.com> parents: 77434 diff changeset	1602 pubid = pubid[1:-1]
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1603 elif type == "SYSTEM" and n == 3:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1604 name, type, system = self._doctype
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1605 pubid = None
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1606 else:
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1607 return
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1608 if hasattr(self.target, "doctype"):
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1609 self.target.doctype(name, pubid, system[1:-1])
75411 47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1610 elif self.doctype != self._XMLParser__doctype:
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1611 # warn about deprecated call
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1612 self._XMLParser__doctype(name, pubid, system[1:-1])
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1613 self.doctype(name, pubid, system[1:-1])
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1614 self._doctype = None
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1615
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1616 def doctype(self, name, pubid, system):
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1617 """(Deprecated) Handle doctype declaration
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1618
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1619 name is the Doctype name, pubid is the public identifier,
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1620 and system is the system identifier.
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1621
f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1622 """
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1623 warnings.warn(
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1624 "This method of XMLParser is deprecated. Define doctype() "
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1625 "method on the TreeBuilder target.",
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1626 DeprecationWarning,
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1627 )
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1628
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1629 # sentinel, if doctype is redefined in a subclass
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1630 __doctype = doctype
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1631
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1632 def feed(self, data):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1633 """Feed encoded data to parser."""
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1634 try:
75411 47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1635 self.parser.Parse(data, 0)
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1636 except self._error as v:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1637 self._raiseerror(v)
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1638
cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1639 def close(self):
82571 f27d7c1eac4d Issue #16954: Add docstrings for ElementTree Eli Bendersky <eliben@gmail.com> parents: 81686 diff changeset	1640 """Finish feeding data to parser and return element structure."""
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1641 try:
75411 47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1642 self.parser.Parse("", 1) # end of data
59601 7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1643 except self._error as v:
7a18c2762886 Merged revisions 78838-78839,78917,78919,78934,78937 via svnmerge from Florent Xicluna <florent.xicluna@gmail.com> parents: 58849 diff changeset	1644 self._raiseerror(v)
75411 47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1645 try:
75416 09b19d06590e Flatten nested try ... finally, try ... except. Florent Xicluna <florent.xicluna@gmail.com> parents: 75411 diff changeset	1646 close_handler = self.target.close
09b19d06590e Flatten nested try ... finally, try ... except. Florent Xicluna <florent.xicluna@gmail.com> parents: 75411 diff changeset	1647 except AttributeError:
09b19d06590e Flatten nested try ... finally, try ... except. Florent Xicluna <florent.xicluna@gmail.com> parents: 75411 diff changeset	1648 pass
09b19d06590e Flatten nested try ... finally, try ... except. Florent Xicluna <florent.xicluna@gmail.com> parents: 75411 diff changeset	1649 else:
09b19d06590e Flatten nested try ... finally, try ... except. Florent Xicluna <florent.xicluna@gmail.com> parents: 75411 diff changeset	1650 return close_handler()
75411 47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1651 finally:
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1652 # get rid of circular references
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1653 del self.parser, self._parser
47016103185f Issue #14007: accept incomplete TreeBuilder objects (missing start/end/data/close) for the Python implementation as well. Add disabled tests for the doctype() method. Florent Xicluna <florent.xicluna@gmail.com> parents: 75379 diff changeset	1654 del self.target, self._target
39275 cb1e432b4919 expunge the xmlcore changes: Fred Drake <fdrake@acm.org> parents: diff changeset	1655
74903 65fc79fb4eb2 Issue #13988: cElementTree is deprecated and the _elementtree accelerator is automatically used whenever available. Florent Xicluna <florent.xicluna@gmail.com> parents: 73291 diff changeset	1656
65fc79fb4eb2 Issue #13988: cElementTree is deprecated and the _elementtree accelerator is automatically used whenever available. Florent Xicluna <florent.xicluna@gmail.com> parents: 73291 diff changeset	1657 # Import the C accelerators
65fc79fb4eb2 Issue #13988: cElementTree is deprecated and the _elementtree accelerator is automatically used whenever available. Florent Xicluna <florent.xicluna@gmail.com> parents: 73291 diff changeset	1658 try:
83845 16a03959819a Issue #17988: remove unused alias for Element and rename the used one Eli Bendersky <eliben@gmail.com> parents: 83843 diff changeset	1659 # Element is going to be shadowed by the C implementation. We need to keep
16a03959819a Issue #17988: remove unused alias for Element and rename the used one Eli Bendersky <eliben@gmail.com> parents: 83843 diff changeset	1660 # the Python version of it accessible for some "creative" by external code
16a03959819a Issue #17988: remove unused alias for Element and rename the used one Eli Bendersky <eliben@gmail.com> parents: 83843 diff changeset	1661 # (see tests)
16a03959819a Issue #17988: remove unused alias for Element and rename the used one Eli Bendersky <eliben@gmail.com> parents: 83843 diff changeset	1662 _Element_Py = Element
16a03959819a Issue #17988: remove unused alias for Element and rename the used one Eli Bendersky <eliben@gmail.com> parents: 83843 diff changeset	1663
74903 65fc79fb4eb2 Issue #13988: cElementTree is deprecated and the _elementtree accelerator is automatically used whenever available. Florent Xicluna <florent.xicluna@gmail.com> parents: 73291 diff changeset	1664 # Element, SubElement, ParseError, TreeBuilder, XMLParser
65fc79fb4eb2 Issue #13988: cElementTree is deprecated and the _elementtree accelerator is automatically used whenever available. Florent Xicluna <florent.xicluna@gmail.com> parents: 73291 diff changeset	1665 from _elementtree import *
65fc79fb4eb2 Issue #13988: cElementTree is deprecated and the _elementtree accelerator is automatically used whenever available. Florent Xicluna <florent.xicluna@gmail.com> parents: 73291 diff changeset	1666 except ImportError:
65fc79fb4eb2 Issue #13988: cElementTree is deprecated and the _elementtree accelerator is automatically used whenever available. Florent Xicluna <florent.xicluna@gmail.com> parents: 73291 diff changeset	1667 pass

Mercurial > cpython-lru_cache-weakref

annotate Lib/xml/etree/ElementTree.py @ 87690:66c1c9f32567 default tip