| 1 |
"""Lightweight XML support for Python. |
| 2 |
|
| 3 |
XML is an inherently hierarchical data format, and the most natural way to |
| 4 |
represent it is with a tree. This module has two classes for this purpose: |
| 5 |
|
| 6 |
1. ElementTree represents the whole XML document as a tree and |
| 7 |
|
| 8 |
2. Element represents a single node in this tree. |
| 9 |
|
| 10 |
Interactions with the whole document (reading and writing to/from files) are |
| 11 |
usually done on the ElementTree level. Interactions with a single XML element |
| 12 |
and its sub-elements are done on the Element level. |
| 13 |
|
| 14 |
Element is a flexible container object designed to store hierarchical data |
| 15 |
structures in memory. It can be described as a cross between a list and a |
| 16 |
dictionary. Each Element has a number of properties associated with it: |
| 17 |
|
| 18 |
'tag' - a string containing the element's name. |
| 19 |
|
| 20 |
'attributes' - a Python dictionary storing the element's attributes. |
| 21 |
|
| 22 |
'text' - a string containing the element's text content. |
| 23 |
|
| 24 |
'tail' - an optional string containing text after the element's end tag. |
| 25 |
|
| 26 |
And a number of child elements stored in a Python sequence. |
| 27 |
|
| 28 |
To create an element instance, use the Element constructor, |
| 29 |
or the SubElement factory function. |
| 30 |
|
| 31 |
You can also use the ElementTree class to wrap an element structure |
| 32 |
and convert it to and from XML. |
| 33 |
|
| 34 |
""" |
| 35 |
|
| 36 |
#--------------------------------------------------------------------- |
| 37 |
# Licensed to PSF under a Contributor Agreement. |
| 38 |
# See https://www.python.org/psf/license for licensing details. |
| 39 |
# |
| 40 |
# ElementTree |
| 41 |
# Copyright (c) 1999-2008 by Fredrik Lundh. All rights reserved. |
| 42 |
# |
| 43 |
# [email protected] |
| 44 |
# http://www.pythonware.com |
| 45 |
# -------------------------------------------------------------------- |
| 46 |
# The ElementTree toolkit is |
| 47 |
# |
| 48 |
# Copyright (c) 1999-2008 by Fredrik Lundh |
| 49 |
# |
| 50 |
# By obtaining, using, and/or copying this software and/or its |
| 51 |
# associated documentation, you agree that you have read, understood, |
| 52 |
# and will comply with the following terms and conditions: |
| 53 |
# |
| 54 |
# Permission to use, copy, modify, and distribute this software and |
| 55 |
# its associated documentation for any purpose and without fee is |
| 56 |
# hereby granted, provided that the above copyright notice appears in |
| 57 |
# all copies, and that both that copyright notice and this permission |
| 58 |
# notice appear in supporting documentation, and that the name of |
| 59 |
# Secret Labs AB or the author not be used in advertising or publicity |
| 60 |
# pertaining to distribution of the software without specific, written |
| 61 |
# prior permission. |
| 62 |
# |
| 63 |
# SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD |
| 64 |
# TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT- |
| 65 |
# ABILITY AND FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR |
| 66 |
# BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY |
| 67 |
# DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, |
| 68 |
# WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS |
| 69 |
# ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE |
| 70 |
# OF THIS SOFTWARE. |
| 71 |
# -------------------------------------------------------------------- |
| 72 |
|
| 73 |
__all__ = [ |
| 74 |
# public symbols |
| 75 |
"Comment", |
| 76 |
"dump", |
| 77 |
"Element", "ElementTree", |
| 78 |
"fromstring", "fromstringlist", |
| 79 |
"indent", "iselement", "iterparse", |
| 80 |
"parse", "ParseError", |
| 81 |
"PI", "ProcessingInstruction", |
| 82 |
"QName", |
| 83 |
"SubElement", |
| 84 |
"tostring", "tostringlist", |
| 85 |
"TreeBuilder", |
| 86 |
"VERSION", |
| 87 |
"XML", "XMLID", |
| 88 |
"XMLParser", "XMLPullParser", |
| 89 |
"register_namespace", |
| 90 |
"canonicalize", "C14NWriterTarget", |
| 91 |
] |
| 92 |
|
| 93 |
VERSION = "1.3.0" |
| 94 |
|
| 95 |
import sys |
| 96 |
import re |
| 97 |
import warnings |
| 98 |
import io |
| 99 |
import collections |
| 100 |
import collections.abc |
| 101 |
import contextlib |
| 102 |
import weakref |
| 103 |
|
| 104 |
from . import ElementPath |
| 105 |
|
| 106 |
|
| 107 |
class ParseError(SyntaxError): |
| 108 |
"""An error when parsing an XML document. |
| 109 |
|
| 110 |
In addition to its exception value, a ParseError contains |
| 111 |
two extra attributes: |
| 112 |
'code' - the specific exception code |
| 113 |
'position' - the line and column of the error |
| 114 |
|
| 115 |
""" |
| 116 |
pass |
| 117 |
|
| 118 |
# -------------------------------------------------------------------- |
| 119 |
|
| 120 |
|
| 121 |
def iselement(element): |
| 122 |
"""Return True if *element* appears to be an Element.""" |
| 123 |
return hasattr(element, 'tag') |
| 124 |
|
| 125 |
|
| 126 |
class Element: |
| 127 |
"""An XML element. |
| 128 |
|
| 129 |
This class is the reference implementation of the Element interface. |
| 130 |
|
| 131 |
An element's length is its number of subelements. That means if you |
| 132 |
want to check if an element is truly empty, you should check BOTH |
| 133 |
its length AND its text attribute. |
| 134 |
|
| 135 |
The element tag, attribute names, and attribute values can be either |
| 136 |
bytes or strings. |
| 137 |
|
| 138 |
*tag* is the element name. *attrib* is an optional dictionary containing |
| 139 |
element attributes. *extra* are additional element attributes given as |
| 140 |
keyword arguments. |
| 141 |
|
| 142 |
Example form: |
| 143 |
<tag attrib>text<child/>...</tag>tail |
| 144 |
|
| 145 |
""" |
| 146 |
|
| 147 |
tag = None |
| 148 |
"""The element's name.""" |
| 149 |
|
| 150 |
attrib = None |
| 151 |
"""Dictionary of the element's attributes.""" |
| 152 |
|
| 153 |
text = None |
| 154 |
""" |
| 155 |
Text before first subelement. This is either a string or the value None. |
| 156 |
Note that if there is no text, this attribute may be either |
| 157 |
None or the empty string, depending on the parser. |
| 158 |
|
| 159 |
""" |
| 160 |
|
| 161 |
tail = None |
| 162 |
""" |
| 163 |
Text after this element's end tag, but before the next sibling element's |
| 164 |
start tag. This is either a string or the value None. Note that if there |
| 165 |
was no text, this attribute may be either None or an empty string, |
| 166 |
depending on the parser. |
| 167 |
|
| 168 |
""" |
| 169 |
|
| 170 |
def __init__(self, tag, attrib={}, **extra): |
| 171 |
if not isinstance(attrib, dict): |
| 172 |
raise TypeError("attrib must be dict, not %s" % ( |
| 173 |
attrib.__class__.__name__,)) |
| 174 |
self.tag = tag |
| 175 |
self.attrib = {**attrib, **extra} |
| 176 |
self._children = [] |
| 177 |
|
| 178 |
def __repr__(self): |
| 179 |
return "<%s %r at %#x>" % (self.__class__.__name__, self.tag, id(self)) |
| 180 |
|
| 181 |
def makeelement(self, tag, attrib): |
| 182 |
"""Create a new element with the same type. |
| 183 |
|
| 184 |
*tag* is a string containing the element name. |
| 185 |
*attrib* is a dictionary containing the element attributes. |
| 186 |
|
| 187 |
Do not call this method, use the SubElement factory function instead. |
| 188 |
|
| 189 |
""" |
| 190 |
return self.__class__(tag, attrib) |
| 191 |
|
| 192 |
def __copy__(self): |
| 193 |
elem = self.makeelement(self.tag, self.attrib) |
| 194 |
elem.text = self.text |
| 195 |
elem.tail = self.tail |
| 196 |
elem[:] = self |
| 197 |
return elem |
| 198 |
|
| 199 |
def __len__(self): |
| 200 |
return len(self._children) |
| 201 |
|
| 202 |
def __bool__(self): |
| 203 |
warnings.warn( |
| 204 |
"Testing an element's truth value will always return True in " |
| 205 |
"future versions. " |
| 206 |
"Use specific 'len(elem)' or 'elem is not None' test instead.", |
| 207 |
DeprecationWarning, stacklevel=2 |
| 208 |
) |
| 209 |
return len(self._children) != 0 # emulate old behaviour, for now |
| 210 |
|
| 211 |
def __getitem__(self, index): |
| 212 |
return self._children[index] |
| 213 |
|
| 214 |
def __setitem__(self, index, element): |
| 215 |
if isinstance(index, slice): |
| 216 |
for elt in element: |
| 217 |
self._assert_is_element(elt) |
| 218 |
else: |
| 219 |
self._assert_is_element(element) |
| 220 |
self._children[index] = element |
| 221 |
|
| 222 |
def __delitem__(self, index): |
| 223 |
del self._children[index] |
| 224 |
|
| 225 |
def append(self, subelement): |
| 226 |
"""Add *subelement* to the end of this element. |
| 227 |
|
| 228 |
The new element will appear in document order after the last existing |
| 229 |
subelement (or directly after the text, if it's the first subelement), |
| 230 |
but before the end tag for this element. |
| 231 |
|
| 232 |
""" |
| 233 |
self._assert_is_element(subelement) |
| 234 |
self._children.append(subelement) |
| 235 |
|
| 236 |
def extend(self, elements): |
| 237 |
"""Append subelements from a sequence. |
| 238 |
|
| 239 |
*elements* is a sequence with zero or more elements. |
| 240 |
|
| 241 |
""" |
| 242 |
for element in elements: |
| 243 |
self._assert_is_element(element) |
| 244 |
self._children.append(element) |
| 245 |
|
| 246 |
def insert(self, index, subelement): |
| 247 |
"""Insert *subelement* at position *index*.""" |
| 248 |
self._assert_is_element(subelement) |
| 249 |
self._children.insert(index, subelement) |
| 250 |
|
| 251 |
def _assert_is_element(self, e): |
| 252 |
# Need to refer to the actual Python implementation, not the |
| 253 |
# shadowing C implementation. |
| 254 |
if not isinstance(e, _Element_Py): |
| 255 |
raise TypeError('expected an Element, not %s' % type(e).__name__) |
| 256 |
|
| 257 |
def remove(self, subelement): |
| 258 |
"""Remove matching subelement. |
| 259 |
|
| 260 |
Unlike the find methods, this method compares elements based on |
| 261 |
identity, NOT ON tag value or contents. To remove subelements by |
| 262 |
other means, the easiest way is to use a list comprehension to |
| 263 |
select what elements to keep, and then use slice assignment to update |
| 264 |
the parent element. |
| 265 |
|
| 266 |
ValueError is raised if a matching element could not be found. |
| 267 |
|
| 268 |
""" |
| 269 |
# assert iselement(element) |
| 270 |
try: |
| 271 |
self._children.remove(subelement) |
| 272 |
except ValueError: |
| 273 |
# to align the error message with the C implementation |
| 274 |
raise ValueError("Element.remove(x): element not found") from None |
| 275 |
|
| 276 |
def find(self, path, namespaces=None): |
| 277 |
"""Find first matching element by tag name or path. |
| 278 |
|
| 279 |
*path* is a string having either an element tag or an XPath, |
| 280 |
*namespaces* is an optional mapping from namespace prefix to full name. |
| 281 |
|
| 282 |
Return the first matching element, or None if no element was found. |
| 283 |
|
| 284 |
""" |
| 285 |
return ElementPath.find(self, path, namespaces) |
| 286 |
|
| 287 |
def findtext(self, path, default=None, namespaces=None): |
| 288 |
"""Find text for first matching element by tag name or path. |
| 289 |
|
| 290 |
*path* is a string having either an element tag or an XPath, |
| 291 |
*default* is the value to return if the element was not found, |
| 292 |
*namespaces* is an optional mapping from namespace prefix to full name. |
| 293 |
|
| 294 |
Return text content of first matching element, or default value if |
| 295 |
none was found. Note that if an element is found having no text |
| 296 |
content, the empty string is returned. |
| 297 |
|
| 298 |
""" |
| 299 |
return ElementPath.findtext(self, path, default, namespaces) |
| 300 |
|
| 301 |
def findall(self, path, namespaces=None): |
| 302 |
"""Find all matching subelements by tag name or path. |
| 303 |
|
| 304 |
*path* is a string having either an element tag or an XPath, |
| 305 |
*namespaces* is an optional mapping from namespace prefix to full name. |
| 306 |
|
| 307 |
Returns list containing all matching elements in document order. |
| 308 |
|
| 309 |
""" |
| 310 |
return ElementPath.findall(self, path, namespaces) |
| 311 |
|
| 312 |
def iterfind(self, path, namespaces=None): |
| 313 |
"""Find all matching subelements by tag name or path. |
| 314 |
|
| 315 |
*path* is a string having either an element tag or an XPath, |
| 316 |
*namespaces* is an optional mapping from namespace prefix to full name. |
| 317 |
|
| 318 |
Return an iterable yielding all matching elements in document order. |
| 319 |
|
| 320 |
""" |
| 321 |
return ElementPath.iterfind(self, path, namespaces) |
| 322 |
|
| 323 |
def clear(self): |
| 324 |
"""Reset element. |
| 325 |
|
| 326 |
This function removes all subelements, clears all attributes, and sets |
| 327 |
the text and tail attributes to None. |
| 328 |
|
| 329 |
""" |
| 330 |
self.attrib.clear() |
| 331 |
self._children = [] |
| 332 |
self.text = self.tail = None |
| 333 |
|
| 334 |
def get(self, key, default=None): |
| 335 |
"""Get element attribute. |
| 336 |
|
| 337 |
Equivalent to attrib.get, but some implementations may handle this a |
| 338 |
bit more efficiently. *key* is what attribute to look for, and |
| 339 |
*default* is what to return if the attribute was not found. |
| 340 |
|
| 341 |
Returns a string containing the attribute value, or the default if |
| 342 |
attribute was not found. |
| 343 |
|
| 344 |
""" |
| 345 |
return self.attrib.get(key, default) |
| 346 |
|
| 347 |
def set(self, key, value): |
| 348 |
"""Set element attribute. |
| 349 |
|
| 350 |
Equivalent to attrib[key] = value, but some implementations may handle |
| 351 |
this a bit more efficiently. *key* is what attribute to set, and |
| 352 |
*value* is the attribute value to set it to. |
| 353 |
|
| 354 |
""" |
| 355 |
self.attrib[key] = value |
| 356 |
|
| 357 |
def keys(self): |
| 358 |
"""Get list of attribute names. |
| 359 |
|
| 360 |
Names are returned in an arbitrary order, just like an ordinary |
| 361 |
Python dict. Equivalent to attrib.keys() |
| 362 |
|
| 363 |
""" |
| 364 |
return self.attrib.keys() |
| 365 |
|
| 366 |
def items(self): |
| 367 |
"""Get element attributes as a sequence. |
| 368 |
|
| 369 |
The attributes are returned in arbitrary order. Equivalent to |
| 370 |
attrib.items(). |
| 371 |
|
| 372 |
Return a list of (name, value) tuples. |
| 373 |
|
| 374 |
""" |
| 375 |
return self.attrib.items() |
| 376 |
|
| 377 |
def iter(self, tag=None): |
| 378 |
"""Create tree iterator. |
| 379 |
|
| 380 |
The iterator loops over the element and all subelements in document |
| 381 |
order, returning all elements with a matching tag. |
| 382 |
|
| 383 |
If the tree structure is modified during iteration, new or removed |
| 384 |
elements may or may not be included. To get a stable set, use the |
| 385 |
list() function on the iterator, and loop over the resulting list. |
| 386 |
|
| 387 |
*tag* is what tags to look for (default is to return all elements) |
| 388 |
|
| 389 |
Return an iterator containing all the matching elements. |
| 390 |
|
| 391 |
""" |
| 392 |
if tag == "*": |
| 393 |
tag = None |
| 394 |
if tag is None or self.tag == tag: |
| 395 |
yield self |
| 396 |
for e in self._children: |
| 397 |
yield from e.iter(tag) |
| 398 |
|
| 399 |
def itertext(self): |
| 400 |
"""Create text iterator. |
| 401 |
|
| 402 |
The iterator loops over the element and all subelements in document |
| 403 |
order, returning all inner text. |
| 404 |
|
| 405 |
""" |
| 406 |
tag = self.tag |
| 407 |
if not isinstance(tag, str) and tag is not None: |
| 408 |
return |
| 409 |
t = self.text |
| 410 |
if t: |
| 411 |
yield t |
| 412 |
for e in self: |
| 413 |
yield from e.itertext() |
| 414 |
t = e.tail |
| 415 |
if t: |
| 416 |
yield t |
| 417 |
|
| 418 |
|
| 419 |
def SubElement(parent, tag, attrib={}, **extra): |
| 420 |
"""Subelement factory which creates an element instance, and appends it |
| 421 |
to an existing parent. |
| 422 |
|
| 423 |
The element tag, attribute names, and attribute values can be either |
| 424 |
bytes or Unicode strings. |
| 425 |
|
| 426 |
*parent* is the parent element, *tag* is the subelements name, *attrib* is |
| 427 |
an optional directory containing element attributes, *extra* are |
| 428 |
additional attributes given as keyword arguments. |
| 429 |
|
| 430 |
""" |
| 431 |
attrib = {**attrib, **extra} |
| 432 |
element = parent.makeelement(tag, attrib) |
| 433 |
parent.append(element) |
| 434 |
return element |
| 435 |
|
| 436 |
|
| 437 |
def Comment(text=None): |
| 438 |
"""Comment element factory. |
| 439 |
|
| 440 |
This function creates a special element which the standard serializer |
| 441 |
serializes as an XML comment. |
| 442 |
|
| 443 |
*text* is a string containing the comment string. |
| 444 |
|
| 445 |
""" |
| 446 |
element = Element(Comment) |
| 447 |
element.text = text |
| 448 |
return element |
| 449 |
|
| 450 |
|
| 451 |
def ProcessingInstruction(target, text=None): |
| 452 |
"""Processing Instruction element factory. |
| 453 |
|
| 454 |
This function creates a special element which the standard serializer |
| 455 |
serializes as an XML comment. |
| 456 |
|
| 457 |
*target* is a string containing the processing instruction, *text* is a |
| 458 |
string containing the processing instruction contents, if any. |
| 459 |
|
| 460 |
""" |
| 461 |
element = Element(ProcessingInstruction) |
| 462 |
element.text = target |
| 463 |
if text: |
| 464 |
element.text = element.text + " " + text |
| 465 |
return element |
| 466 |
|
| 467 |
PI = ProcessingInstruction |
| 468 |
|
| 469 |
|
| 470 |
class QName: |
| 471 |
"""Qualified name wrapper. |
| 472 |
|
| 473 |
This class can be used to wrap a QName attribute value in order to get |
| 474 |
proper namespace handing on output. |
| 475 |
|
| 476 |
*text_or_uri* is a string containing the QName value either in the form |
| 477 |
{uri}local, or if the tag argument is given, the URI part of a QName. |
| 478 |
|
| 479 |
*tag* is an optional argument which if given, will make the first |
| 480 |
argument (text_or_uri) be interpreted as a URI, and this argument (tag) |
| 481 |
be interpreted as a local name. |
| 482 |
|
| 483 |
""" |
| 484 |
def __init__(self, text_or_uri, tag=None): |
| 485 |
if tag: |
| 486 |
text_or_uri = "{%s}%s" % (text_or_uri, tag) |
| 487 |
self.text = text_or_uri |
| 488 |
def __str__(self): |
| 489 |
return self.text |
| 490 |
def __repr__(self): |
| 491 |
return '<%s %r>' % (self.__class__.__name__, self.text) |
| 492 |
def __hash__(self): |
| 493 |
return hash(self.text) |
| 494 |
def __le__(self, other): |
| 495 |
if isinstance(other, QName): |
| 496 |
return self.text <= other.text |
| 497 |
return self.text <= other |
| 498 |
def __lt__(self, other): |
| 499 |
if isinstance(other, QName): |
| 500 |
return self.text < other.text |
| 501 |
return self.text < other |
| 502 |
def __ge__(self, other): |
| 503 |
if isinstance(other, QName): |
| 504 |
return self.text >= other.text |
| 505 |
return self.text >= other |
| 506 |
def __gt__(self, other): |
| 507 |
if isinstance(other, QName): |
| 508 |
return self.text > other.text |
| 509 |
return self.text > other |
| 510 |
def __eq__(self, other): |
| 511 |
if isinstance(other, QName): |
| 512 |
return self.text == other.text |
| 513 |
return self.text == other |
| 514 |
|
| 515 |
# -------------------------------------------------------------------- |
| 516 |
|
| 517 |
|
| 518 |
class ElementTree: |
| 519 |
"""An XML element hierarchy. |
| 520 |
|
| 521 |
This class also provides support for serialization to and from |
| 522 |
standard XML. |
| 523 |
|
| 524 |
*element* is an optional root element node, |
| 525 |
*file* is an optional file handle or file name of an XML file whose |
| 526 |
contents will be used to initialize the tree with. |
| 527 |
|
| 528 |
""" |
| 529 |
def __init__(self, element=None, file=None): |
| 530 |
if element is not None and not iselement(element): |
| 531 |
raise TypeError('expected an Element, not %s' % |
| 532 |
type(element).__name__) |
| 533 |
self._root = element # first node |
| 534 |
if file: |
| 535 |
self.parse(file) |
| 536 |
|
| 537 |
def getroot(self): |
| 538 |
"""Return root element of this tree.""" |
| 539 |
return self._root |
| 540 |
|
| 541 |
def _setroot(self, element): |
| 542 |
"""Replace root element of this tree. |
| 543 |
|
| 544 |
This will discard the current contents of the tree and replace it |
| 545 |
with the given element. Use with care! |
| 546 |
|
| 547 |
""" |
| 548 |
if not iselement(element): |
| 549 |
raise TypeError('expected an Element, not %s' |
| 550 |
% type(element).__name__) |
| 551 |
self._root = element |
| 552 |
|
| 553 |
def parse(self, source, parser=None): |
| 554 |
"""Load external XML document into element tree. |
| 555 |
|
| 556 |
*source* is a file name or file object, *parser* is an optional parser |
| 557 |
instance that defaults to XMLParser. |
| 558 |
|
| 559 |
ParseError is raised if the parser fails to parse the document. |
| 560 |
|
| 561 |
Returns the root element of the given source document. |
| 562 |
|
| 563 |
""" |
| 564 |
close_source = False |
| 565 |
if not hasattr(source, "read"): |
| 566 |
source = open(source, "rb") |
| 567 |
close_source = True |
| 568 |
try: |
| 569 |
if parser is None: |
| 570 |
# If no parser was specified, create a default XMLParser |
| 571 |
parser = XMLParser() |
| 572 |
if hasattr(parser, '_parse_whole'): |
| 573 |
# The default XMLParser, when it comes from an accelerator, |
| 574 |
# can define an internal _parse_whole API for efficiency. |
| 575 |
# It can be used to parse the whole source without feeding |
| 576 |
# it with chunks. |
| 577 |
self._root = parser._parse_whole(source) |
| 578 |
return self._root |
| 579 |
while data := source.read(65536): |
| 580 |
parser.feed(data) |
| 581 |
self._root = parser.close() |
| 582 |
return self._root |
| 583 |
finally: |
| 584 |
if close_source: |
| 585 |
source.close() |
| 586 |
|
| 587 |
def iter(self, tag=None): |
| 588 |
"""Create and return tree iterator for the root element. |
| 589 |
|
| 590 |
The iterator loops over all elements in this tree, in document order. |
| 591 |
|
| 592 |
*tag* is a string with the tag name to iterate over |
| 593 |
(default is to return all elements). |
| 594 |
|
| 595 |
""" |
| 596 |
# assert self._root is not None |
| 597 |
return self._root.iter(tag) |
| 598 |
|
| 599 |
def find(self, path, namespaces=None): |
| 600 |
"""Find first matching element by tag name or path. |
| 601 |
|
| 602 |
Same as getroot().find(path), which is Element.find() |
| 603 |
|
| 604 |
*path* is a string having either an element tag or an XPath, |
| 605 |
*namespaces* is an optional mapping from namespace prefix to full name. |
| 606 |
|
| 607 |
Return the first matching element, or None if no element was found. |
| 608 |
|
| 609 |
""" |
| 610 |
# assert self._root is not None |
| 611 |
if path[:1] == "/": |
| 612 |
path = "." + path |
| 613 |
warnings.warn( |
| 614 |
"This search is broken in 1.3 and earlier, and will be " |
| 615 |
"fixed in a future version. If you rely on the current " |
| 616 |
"behaviour, change it to %r" % path, |
| 617 |
FutureWarning, stacklevel=2 |
| 618 |
) |
| 619 |
return self._root.find(path, namespaces) |
| 620 |
|
| 621 |
def findtext(self, path, default=None, namespaces=None): |
| 622 |
"""Find first matching element by tag name or path. |
| 623 |
|
| 624 |
Same as getroot().findtext(path), which is Element.findtext() |
| 625 |
|
| 626 |
*path* is a string having either an element tag or an XPath, |
| 627 |
*namespaces* is an optional mapping from namespace prefix to full name. |
| 628 |
|
| 629 |
Return the first matching element, or None if no element was found. |
| 630 |
|
| 631 |
""" |
| 632 |
# assert self._root is not None |
| 633 |
if path[:1] == "/": |
| 634 |
path = "." + path |
| 635 |
warnings.warn( |
| 636 |
"This search is broken in 1.3 and earlier, and will be " |
| 637 |
"fixed in a future version. If you rely on the current " |
| 638 |
"behaviour, change it to %r" % path, |
| 639 |
FutureWarning, stacklevel=2 |
| 640 |
) |
| 641 |
return self._root.findtext(path, default, namespaces) |
| 642 |
|
| 643 |
def findall(self, path, namespaces=None): |
| 644 |
"""Find all matching subelements by tag name or path. |
| 645 |
|
| 646 |
Same as getroot().findall(path), which is Element.findall(). |
| 647 |
|
| 648 |
*path* is a string having either an element tag or an XPath, |
| 649 |
*namespaces* is an optional mapping from namespace prefix to full name. |
| 650 |
|
| 651 |
Return list containing all matching elements in document order. |
| 652 |
|
| 653 |
""" |
| 654 |
# assert self._root is not None |
| 655 |
if path[:1] == "/": |
| 656 |
path = "." + path |
| 657 |
warnings.warn( |
| 658 |
"This search is broken in 1.3 and earlier, and will be " |
| 659 |
"fixed in a future version. If you rely on the current " |
| 660 |
"behaviour, change it to %r" % path, |
| 661 |
FutureWarning, stacklevel=2 |
| 662 |
) |
| 663 |
return self._root.findall(path, namespaces) |
| 664 |
|
| 665 |
def iterfind(self, path, namespaces=None): |
| 666 |
"""Find all matching subelements by tag name or path. |
| 667 |
|
| 668 |
Same as getroot().iterfind(path), which is element.iterfind() |
| 669 |
|
| 670 |
*path* is a string having either an element tag or an XPath, |
| 671 |
*namespaces* is an optional mapping from namespace prefix to full name. |
| 672 |
|
| 673 |
Return an iterable yielding all matching elements in document order. |
| 674 |
|
| 675 |
""" |
| 676 |
# assert self._root is not None |
| 677 |
if path[:1] == "/": |
| 678 |
path = "." + path |
| 679 |
warnings.warn( |
| 680 |
"This search is broken in 1.3 and earlier, and will be " |
| 681 |
"fixed in a future version. If you rely on the current " |
| 682 |
"behaviour, change it to %r" % path, |
| 683 |
FutureWarning, stacklevel=2 |
| 684 |
) |
| 685 |
return self._root.iterfind(path, namespaces) |
| 686 |
|
| 687 |
def write(self, file_or_filename, |
| 688 |
encoding=None, |
| 689 |
xml_declaration=None, |
| 690 |
default_namespace=None, |
| 691 |
method=None, *, |
| 692 |
short_empty_elements=True): |
| 693 |
"""Write element tree to a file as XML. |
| 694 |
|
| 695 |
Arguments: |
| 696 |
*file_or_filename* -- file name or a file object opened for writing |
| 697 |
|
| 698 |
*encoding* -- the output encoding (default: US-ASCII) |
| 699 |
|
| 700 |
*xml_declaration* -- bool indicating if an XML declaration should be |
| 701 |
added to the output. If None, an XML declaration |
| 702 |
is added if encoding IS NOT either of: |
| 703 |
US-ASCII, UTF-8, or Unicode |
| 704 |
|
| 705 |
*default_namespace* -- sets the default XML namespace (for "xmlns") |
| 706 |
|
| 707 |
*method* -- either "xml" (default), "html, "text", or "c14n" |
| 708 |
|
| 709 |
*short_empty_elements* -- controls the formatting of elements |
| 710 |
that contain no content. If True (default) |
| 711 |
they are emitted as a single self-closed |
| 712 |
tag, otherwise they are emitted as a pair |
| 713 |
of start/end tags |
| 714 |
|
| 715 |
""" |
| 716 |
if self._root is None: |
| 717 |
raise TypeError('ElementTree not initialized') |
| 718 |
if not method: |
| 719 |
method = "xml" |
| 720 |
elif method not in _serialize: |
| 721 |
raise ValueError("unknown method %r" % method) |
| 722 |
if not encoding: |
| 723 |
if method == "c14n": |
| 724 |
encoding = "utf-8" |
| 725 |
else: |
| 726 |
encoding = "us-ascii" |
| 727 |
with _get_writer(file_or_filename, encoding) as (write, declared_encoding): |
| 728 |
if method == "xml" and (xml_declaration or |
| 729 |
(xml_declaration is None and |
| 730 |
encoding.lower() != "unicode" and |
| 731 |
declared_encoding.lower() not in ("utf-8", "us-ascii"))): |
| 732 |
write("<?xml version='1.0' encoding='%s'?>\n" % ( |
| 733 |
declared_encoding,)) |
| 734 |
if method == "text": |
| 735 |
_serialize_text(write, self._root) |
| 736 |
else: |
| 737 |
qnames, namespaces = _namespaces(self._root, default_namespace) |
| 738 |
serialize = _serialize[method] |
| 739 |
serialize(write, self._root, qnames, namespaces, |
| 740 |
short_empty_elements=short_empty_elements) |
| 741 |
|
| 742 |
def write_c14n(self, file): |
| 743 |
# lxml.etree compatibility. use output method instead |
| 744 |
return self.write(file, method="c14n") |
| 745 |
|
| 746 |
# -------------------------------------------------------------------- |
| 747 |
# serialization support |
| 748 |
|
| 749 |
@contextlib.contextmanager |
| 750 |
def _get_writer(file_or_filename, encoding): |
| 751 |
# returns text write method and release all resources after using |
| 752 |
try: |
| 753 |
write = file_or_filename.write |
| 754 |
except AttributeError: |
| 755 |
# file_or_filename is a file name |
| 756 |
if encoding.lower() == "unicode": |
| 757 |
encoding="utf-8" |
| 758 |
with open(file_or_filename, "w", encoding=encoding, |
| 759 |
errors="xmlcharrefreplace") as file: |
| 760 |
yield file.write, encoding |
| 761 |
else: |
| 762 |
# file_or_filename is a file-like object |
| 763 |
# encoding determines if it is a text or binary writer |
| 764 |
if encoding.lower() == "unicode": |
| 765 |
# use a text writer as is |
| 766 |
yield write, getattr(file_or_filename, "encoding", None) or "utf-8" |
| 767 |
else: |
| 768 |
# wrap a binary writer with TextIOWrapper |
| 769 |
with contextlib.ExitStack() as stack: |
| 770 |
if isinstance(file_or_filename, io.BufferedIOBase): |
| 771 |
file = file_or_filename |
| 772 |
elif isinstance(file_or_filename, io.RawIOBase): |
| 773 |
file = io.BufferedWriter(file_or_filename) |
| 774 |
# Keep the original file open when the BufferedWriter is |
| 775 |
# destroyed |
| 776 |
stack.callback(file.detach) |
| 777 |
else: |
| 778 |
# This is to handle passed objects that aren't in the |
| 779 |
# IOBase hierarchy, but just have a write method |
| 780 |
file = io.BufferedIOBase() |
| 781 |
file.writable = lambda: True |
| 782 |
file.write = write |
| 783 |
try: |
| 784 |
# TextIOWrapper uses this methods to determine |
| 785 |
# if BOM (for UTF-16, etc) should be added |
| 786 |
file.seekable = file_or_filename.seekable |
| 787 |
file.tell = file_or_filename.tell |
| 788 |
except AttributeError: |
| 789 |
pass |
| 790 |
file = io.TextIOWrapper(file, |
| 791 |
encoding=encoding, |
| 792 |
errors="xmlcharrefreplace", |
| 793 |
newline="\n") |
| 794 |
# Keep the original file open when the TextIOWrapper is |
| 795 |
# destroyed |
| 796 |
stack.callback(file.detach) |
| 797 |
yield file.write, encoding |
| 798 |
|
| 799 |
def _namespaces(elem, default_namespace=None): |
| 800 |
# identify namespaces used in this tree |
| 801 |
|
| 802 |
# maps qnames to *encoded* prefix:local names |
| 803 |
qnames = {None: None} |
| 804 |
|
| 805 |
# maps uri:s to prefixes |
| 806 |
namespaces = {} |
| 807 |
if default_namespace: |
| 808 |
namespaces[default_namespace] = "" |
| 809 |
|
| 810 |
def add_qname(qname): |
| 811 |
# calculate serialized qname representation |
| 812 |
try: |
| 813 |
if qname[:1] == "{": |
| 814 |
uri, tag = qname[1:].rsplit("}", 1) |
| 815 |
prefix = namespaces.get(uri) |
| 816 |
if prefix is None: |
| 817 |
prefix = _namespace_map.get(uri) |
| 818 |
if prefix is None: |
| 819 |
prefix = "ns%d" % len(namespaces) |
| 820 |
if prefix != "xml": |
| 821 |
namespaces[uri] = prefix |
| 822 |
if prefix: |
| 823 |
qnames[qname] = "%s:%s" % (prefix, tag) |
| 824 |
else: |
| 825 |
qnames[qname] = tag # default element |
| 826 |
else: |
| 827 |
if default_namespace: |
| 828 |
# FIXME: can this be handled in XML 1.0? |
| 829 |
raise ValueError( |
| 830 |
"cannot use non-qualified names with " |
| 831 |
"default_namespace option" |
| 832 |
) |
| 833 |
qnames[qname] = qname |
| 834 |
except TypeError: |
| 835 |
_raise_serialization_error(qname) |
| 836 |
|
| 837 |
# populate qname and namespaces table |
| 838 |
for elem in elem.iter(): |
| 839 |
tag = elem.tag |
| 840 |
if isinstance(tag, QName): |
| 841 |
if tag.text not in qnames: |
| 842 |
add_qname(tag.text) |
| 843 |
elif isinstance(tag, str): |
| 844 |
if tag not in qnames: |
| 845 |
add_qname(tag) |
| 846 |
elif tag is not None and tag is not Comment and tag is not PI: |
| 847 |
_raise_serialization_error(tag) |
| 848 |
for key, value in elem.items(): |
| 849 |
if isinstance(key, QName): |
| 850 |
key = key.text |
| 851 |
if key not in qnames: |
| 852 |
add_qname(key) |
| 853 |
if isinstance(value, QName) and value.text not in qnames: |
| 854 |
add_qname(value.text) |
| 855 |
text = elem.text |
| 856 |
if isinstance(text, QName) and text.text not in qnames: |
| 857 |
add_qname(text.text) |
| 858 |
return qnames, namespaces |
| 859 |
|
| 860 |
def _serialize_xml(write, elem, qnames, namespaces, |
| 861 |
short_empty_elements, **kwargs): |
| 862 |
tag = elem.tag |
| 863 |
text = elem.text |
| 864 |
if tag is Comment: |
| 865 |
write("<!--%s-->" % text) |
| 866 |
elif tag is ProcessingInstruction: |
| 867 |
write("<?%s?>" % text) |
| 868 |
else: |
| 869 |
tag = qnames[tag] |
| 870 |
if tag is None: |
| 871 |
if text: |
| 872 |
write(_escape_cdata(text)) |
| 873 |
for e in elem: |
| 874 |
_serialize_xml(write, e, qnames, None, |
| 875 |
short_empty_elements=short_empty_elements) |
| 876 |
else: |
| 877 |
write("<" + tag) |
| 878 |
items = list(elem.items()) |
| 879 |
if items or namespaces: |
| 880 |
if namespaces: |
| 881 |
for v, k in sorted(namespaces.items(), |
| 882 |
key=lambda x: x[1]): # sort on prefix |
| 883 |
if k: |
| 884 |
k = ":" + k |
| 885 |
write(" xmlns%s=\"%s\"" % ( |
| 886 |
k, |
| 887 |
_escape_attrib(v) |
| 888 |
)) |
| 889 |
for k, v in items: |
| 890 |
if isinstance(k, QName): |
| 891 |
k = k.text |
| 892 |
if isinstance(v, QName): |
| 893 |
v = qnames[v.text] |
| 894 |
else: |
| 895 |
v = _escape_attrib(v) |
| 896 |
write(" %s=\"%s\"" % (qnames[k], v)) |
| 897 |
if text or len(elem) or not short_empty_elements: |
| 898 |
write(">") |
| 899 |
if text: |
| 900 |
write(_escape_cdata(text)) |
| 901 |
for e in elem: |
| 902 |
_serialize_xml(write, e, qnames, None, |
| 903 |
short_empty_elements=short_empty_elements) |
| 904 |
write("</" + tag + ">") |
| 905 |
else: |
| 906 |
write(" />") |
| 907 |
if elem.tail: |
| 908 |
write(_escape_cdata(elem.tail)) |
| 909 |
|
| 910 |
HTML_EMPTY = {"area", "base", "basefont", "br", "col", "embed", "frame", "hr", |
| 911 |
"img", "input", "isindex", "link", "meta", "param", "source", |
| 912 |
"track", "wbr"} |
| 913 |
|
| 914 |
def _serialize_html(write, elem, qnames, namespaces, **kwargs): |
| 915 |
tag = elem.tag |
| 916 |
text = elem.text |
| 917 |
if tag is Comment: |
| 918 |
write("<!--%s-->" % _escape_cdata(text)) |
| 919 |
elif tag is ProcessingInstruction: |
| 920 |
write("<?%s?>" % _escape_cdata(text)) |
| 921 |
else: |
| 922 |
tag = qnames[tag] |
| 923 |
if tag is None: |
| 924 |
if text: |
| 925 |
write(_escape_cdata(text)) |
| 926 |
for e in elem: |
| 927 |
_serialize_html(write, e, qnames, None) |
| 928 |
else: |
| 929 |
write("<" + tag) |
| 930 |
items = list(elem.items()) |
| 931 |
if items or namespaces: |
| 932 |
if namespaces: |
| 933 |
for v, k in sorted(namespaces.items(), |
| 934 |
key=lambda x: x[1]): # sort on prefix |
| 935 |
if k: |
| 936 |
k = ":" + k |
| 937 |
write(" xmlns%s=\"%s\"" % ( |
| 938 |
k, |
| 939 |
_escape_attrib(v) |
| 940 |
)) |
| 941 |
for k, v in items: |
| 942 |
if isinstance(k, QName): |
| 943 |
k = k.text |
| 944 |
if isinstance(v, QName): |
| 945 |
v = qnames[v.text] |
| 946 |
else: |
| 947 |
v = _escape_attrib_html(v) |
| 948 |
# FIXME: handle boolean attributes |
| 949 |
write(" %s=\"%s\"" % (qnames[k], v)) |
| 950 |
write(">") |
| 951 |
ltag = tag.lower() |
| 952 |
if text: |
| 953 |
if ltag == "script" or ltag == "style": |
| 954 |
write(text) |
| 955 |
else: |
| 956 |
write(_escape_cdata(text)) |
| 957 |
for e in elem: |
| 958 |
_serialize_html(write, e, qnames, None) |
| 959 |
if ltag not in HTML_EMPTY: |
| 960 |
write("</" + tag + ">") |
| 961 |
if elem.tail: |
| 962 |
write(_escape_cdata(elem.tail)) |
| 963 |
|
| 964 |
def _serialize_text(write, elem): |
| 965 |
for part in elem.itertext(): |
| 966 |
write(part) |
| 967 |
if elem.tail: |
| 968 |
write(elem.tail) |
| 969 |
|
| 970 |
_serialize = { |
| 971 |
"xml": _serialize_xml, |
| 972 |
"html": _serialize_html, |
| 973 |
"text": _serialize_text, |
| 974 |
# this optional method is imported at the end of the module |
| 975 |
# "c14n": _serialize_c14n, |
| 976 |
} |
| 977 |
|
| 978 |
|
| 979 |
def register_namespace(prefix, uri): |
| 980 |
"""Register a namespace prefix. |
| 981 |
|
| 982 |
The registry is global, and any existing mapping for either the |
| 983 |
given prefix or the namespace URI will be removed. |
| 984 |
|
| 985 |
*prefix* is the namespace prefix, *uri* is a namespace uri. Tags and |
| 986 |
attributes in this namespace will be serialized with prefix if possible. |
| 987 |
|
| 988 |
ValueError is raised if prefix is reserved or is invalid. |
| 989 |
|
| 990 |
""" |
| 991 |
if re.match(r"ns\d+$", prefix): |
| 992 |
raise ValueError("Prefix format reserved for internal use") |
| 993 |
for k, v in list(_namespace_map.items()): |
| 994 |
if k == uri or v == prefix: |
| 995 |
del _namespace_map[k] |
| 996 |
_namespace_map[uri] = prefix |
| 997 |
|
| 998 |
_namespace_map = { |
| 999 |
# "well-known" namespace prefixes |
| 1000 |
"http://www.w3.org/XML/1998/namespace": "xml", |
| 1001 |
"http://www.w3.org/1999/xhtml": "html", |
| 1002 |
"http://www.w3.org/1999/02/22-rdf-syntax-ns#": "rdf", |
| 1003 |
"http://schemas.xmlsoap.org/wsdl/": "wsdl", |
| 1004 |
# xml schema |
| 1005 |
"http://www.w3.org/2001/XMLSchema": "xs", |
| 1006 |
"http://www.w3.org/2001/XMLSchema-instance": "xsi", |
| 1007 |
# dublin core |
| 1008 |
"http://purl.org/dc/elements/1.1/": "dc", |
| 1009 |
} |
| 1010 |
# For tests and troubleshooting |
| 1011 |
register_namespace._namespace_map = _namespace_map |
| 1012 |
|
| 1013 |
def _raise_serialization_error(text): |
| 1014 |
raise TypeError( |
| 1015 |
"cannot serialize %r (type %s)" % (text, type(text).__name__) |
| 1016 |
) |
| 1017 |
|
| 1018 |
def _escape_cdata(text): |
| 1019 |
# escape character data |
| 1020 |
try: |
| 1021 |
# it's worth avoiding do-nothing calls for strings that are |
| 1022 |
# shorter than 500 characters, or so. assume that's, by far, |
| 1023 |
# the most common case in most applications. |
| 1024 |
if "&" in text: |
| 1025 |
text = text.replace("&", "&") |
| 1026 |
if "<" in text: |
| 1027 |
text = text.replace("<", "<") |
| 1028 |
if ">" in text: |
| 1029 |
text = text.replace(">", ">") |
| 1030 |
return text |
| 1031 |
except (TypeError, AttributeError): |
| 1032 |
_raise_serialization_error(text) |
| 1033 |
|
| 1034 |
def _escape_attrib(text): |
| 1035 |
# escape attribute value |
| 1036 |
try: |
| 1037 |
if "&" in text: |
| 1038 |
text = text.replace("&", "&") |
| 1039 |
if "<" in text: |
| 1040 |
text = text.replace("<", "<") |
| 1041 |
if ">" in text: |
| 1042 |
text = text.replace(">", ">") |
| 1043 |
if "\"" in text: |
| 1044 |
text = text.replace("\"", """) |
| 1045 |
# Although section 2.11 of the XML specification states that CR or |
| 1046 |
# CR LN should be replaced with just LN, it applies only to EOLNs |
| 1047 |
# which take part of organizing file into lines. Within attributes, |
| 1048 |
# we are replacing these with entity numbers, so they do not count. |
| 1049 |
# http://www.w3.org/TR/REC-xml/#sec-line-ends |
| 1050 |
# The current solution, contained in following six lines, was |
| 1051 |
# discussed in issue 17582 and 39011. |
| 1052 |
if "\r" in text: |
| 1053 |
text = text.replace("\r", " ") |
| 1054 |
if "\n" in text: |
| 1055 |
text = text.replace("\n", " ") |
| 1056 |
if "\t" in text: |
| 1057 |
text = text.replace("\t", "	") |
| 1058 |
return text |
| 1059 |
except (TypeError, AttributeError): |
| 1060 |
_raise_serialization_error(text) |
| 1061 |
|
| 1062 |
def _escape_attrib_html(text): |
| 1063 |
# escape attribute value |
| 1064 |
try: |
| 1065 |
if "&" in text: |
| 1066 |
text = text.replace("&", "&") |
| 1067 |
if ">" in text: |
| 1068 |
text = text.replace(">", ">") |
| 1069 |
if "\"" in text: |
| 1070 |
text = text.replace("\"", """) |
| 1071 |
return text |
| 1072 |
except (TypeError, AttributeError): |
| 1073 |
_raise_serialization_error(text) |
| 1074 |
|
| 1075 |
# -------------------------------------------------------------------- |
| 1076 |
|
| 1077 |
def tostring(element, encoding=None, method=None, *, |
| 1078 |
xml_declaration=None, default_namespace=None, |
| 1079 |
short_empty_elements=True): |
| 1080 |
"""Generate string representation of XML element. |
| 1081 |
|
| 1082 |
All subelements are included. If encoding is "unicode", a string |
| 1083 |
is returned. Otherwise a bytestring is returned. |
| 1084 |
|
| 1085 |
*element* is an Element instance, *encoding* is an optional output |
| 1086 |
encoding defaulting to US-ASCII, *method* is an optional output which can |
| 1087 |
be one of "xml" (default), "html", "text" or "c14n", *default_namespace* |
| 1088 |
sets the default XML namespace (for "xmlns"). |
| 1089 |
|
| 1090 |
Returns an (optionally) encoded string containing the XML data. |
| 1091 |
|
| 1092 |
""" |
| 1093 |
stream = io.StringIO() if encoding == 'unicode' else io.BytesIO() |
| 1094 |
ElementTree(element).write(stream, encoding, |
| 1095 |
xml_declaration=xml_declaration, |
| 1096 |
default_namespace=default_namespace, |
| 1097 |
method=method, |
| 1098 |
short_empty_elements=short_empty_elements) |
| 1099 |
return stream.getvalue() |
| 1100 |
|
| 1101 |
class _ListDataStream(io.BufferedIOBase): |
| 1102 |
"""An auxiliary stream accumulating into a list reference.""" |
| 1103 |
def __init__(self, lst): |
| 1104 |
self.lst = lst |
| 1105 |
|
| 1106 |
def writable(self): |
| 1107 |
return True |
| 1108 |
|
| 1109 |
def seekable(self): |
| 1110 |
return True |
| 1111 |
|
| 1112 |
def write(self, b): |
| 1113 |
self.lst.append(b) |
| 1114 |
|
| 1115 |
def tell(self): |
| 1116 |
return len(self.lst) |
| 1117 |
|
| 1118 |
def tostringlist(element, encoding=None, method=None, *, |
| 1119 |
xml_declaration=None, default_namespace=None, |
| 1120 |
short_empty_elements=True): |
| 1121 |
lst = [] |
| 1122 |
stream = _ListDataStream(lst) |
| 1123 |
ElementTree(element).write(stream, encoding, |
| 1124 |
xml_declaration=xml_declaration, |
| 1125 |
default_namespace=default_namespace, |
| 1126 |
method=method, |
| 1127 |
short_empty_elements=short_empty_elements) |
| 1128 |
return lst |
| 1129 |
|
| 1130 |
|
| 1131 |
def dump(elem): |
| 1132 |
"""Write element tree or element structure to sys.stdout. |
| 1133 |
|
| 1134 |
This function should be used for debugging only. |
| 1135 |
|
| 1136 |
*elem* is either an ElementTree, or a single Element. The exact output |
| 1137 |
format is implementation dependent. In this version, it's written as an |
| 1138 |
ordinary XML file. |
| 1139 |
|
| 1140 |
""" |
| 1141 |
# debugging |
| 1142 |
if not isinstance(elem, ElementTree): |
| 1143 |
elem = ElementTree(elem) |
| 1144 |
elem.write(sys.stdout, encoding="unicode") |
| 1145 |
tail = elem.getroot().tail |
| 1146 |
if not tail or tail[-1] != "\n": |
| 1147 |
sys.stdout.write("\n") |
| 1148 |
|
| 1149 |
|
| 1150 |
def indent(tree, space=" ", level=0): |
| 1151 |
"""Indent an XML document by inserting newlines and indentation space |
| 1152 |
after elements. |
| 1153 |
|
| 1154 |
*tree* is the ElementTree or Element to modify. The (root) element |
| 1155 |
itself will not be changed, but the tail text of all elements in its |
| 1156 |
subtree will be adapted. |
| 1157 |
|
| 1158 |
*space* is the whitespace to insert for each indentation level, two |
| 1159 |
space characters by default. |
| 1160 |
|
| 1161 |
*level* is the initial indentation level. Setting this to a higher |
| 1162 |
value than 0 can be used for indenting subtrees that are more deeply |
| 1163 |
nested inside of a document. |
| 1164 |
""" |
| 1165 |
if isinstance(tree, ElementTree): |
| 1166 |
tree = tree.getroot() |
| 1167 |
if level < 0: |
| 1168 |
raise ValueError(f"Initial indentation level must be >= 0, got {level}") |
| 1169 |
if not len(tree): |
| 1170 |
return |
| 1171 |
|
| 1172 |
# Reduce the memory consumption by reusing indentation strings. |
| 1173 |
indentations = ["\n" + level * space] |
| 1174 |
|
| 1175 |
def _indent_children(elem, level): |
| 1176 |
# Start a new indentation level for the first child. |
| 1177 |
child_level = level + 1 |
| 1178 |
try: |
| 1179 |
child_indentation = indentations[child_level] |
| 1180 |
except IndexError: |
| 1181 |
child_indentation = indentations[level] + space |
| 1182 |
indentations.append(child_indentation) |
| 1183 |
|
| 1184 |
if not elem.text or not elem.text.strip(): |
| 1185 |
elem.text = child_indentation |
| 1186 |
|
| 1187 |
for child in elem: |
| 1188 |
if len(child): |
| 1189 |
_indent_children(child, child_level) |
| 1190 |
if not child.tail or not child.tail.strip(): |
| 1191 |
child.tail = child_indentation |
| 1192 |
|
| 1193 |
# Dedent after the last child by overwriting the previous indentation. |
| 1194 |
if not child.tail.strip(): |
| 1195 |
child.tail = indentations[level] |
| 1196 |
|
| 1197 |
_indent_children(tree, 0) |
| 1198 |
|
| 1199 |
|
| 1200 |
# -------------------------------------------------------------------- |
| 1201 |
# parsing |
| 1202 |
|
| 1203 |
|
| 1204 |
def parse(source, parser=None): |
| 1205 |
"""Parse XML document into element tree. |
| 1206 |
|
| 1207 |
*source* is a filename or file object containing XML data, |
| 1208 |
*parser* is an optional parser instance defaulting to XMLParser. |
| 1209 |
|
| 1210 |
Return an ElementTree instance. |
| 1211 |
|
| 1212 |
""" |
| 1213 |
tree = ElementTree() |
| 1214 |
tree.parse(source, parser) |
| 1215 |
return tree |
| 1216 |
|
| 1217 |
|
| 1218 |
def iterparse(source, events=None, parser=None): |
| 1219 |
"""Incrementally parse XML document into ElementTree. |
| 1220 |
|
| 1221 |
This class also reports what's going on to the user based on the |
| 1222 |
*events* it is initialized with. The supported events are the strings |
| 1223 |
"start", "end", "start-ns" and "end-ns" (the "ns" events are used to get |
| 1224 |
detailed namespace information). If *events* is omitted, only |
| 1225 |
"end" events are reported. |
| 1226 |
|
| 1227 |
*source* is a filename or file object containing XML data, *events* is |
| 1228 |
a list of events to report back, *parser* is an optional parser instance. |
| 1229 |
|
| 1230 |
Returns an iterator providing (event, elem) pairs. |
| 1231 |
|
| 1232 |
""" |
| 1233 |
# Use the internal, undocumented _parser argument for now; When the |
| 1234 |
# parser argument of iterparse is removed, this can be killed. |
| 1235 |
pullparser = XMLPullParser(events=events, _parser=parser) |
| 1236 |
|
| 1237 |
if not hasattr(source, "read"): |
| 1238 |
source = open(source, "rb") |
| 1239 |
close_source = True |
| 1240 |
else: |
| 1241 |
close_source = False |
| 1242 |
|
| 1243 |
def iterator(source): |
| 1244 |
try: |
| 1245 |
while True: |
| 1246 |
yield from pullparser.read_events() |
| 1247 |
# load event buffer |
| 1248 |
data = source.read(16 * 1024) |
| 1249 |
if not data: |
| 1250 |
break |
| 1251 |
pullparser.feed(data) |
| 1252 |
root = pullparser._close_and_return_root() |
| 1253 |
yield from pullparser.read_events() |
| 1254 |
it = wr() |
| 1255 |
if it is not None: |
| 1256 |
it.root = root |
| 1257 |
finally: |
| 1258 |
if close_source: |
| 1259 |
source.close() |
| 1260 |
|
| 1261 |
gen = iterator(source) |
| 1262 |
class IterParseIterator(collections.abc.Iterator): |
| 1263 |
__next__ = gen.__next__ |
| 1264 |
def close(self): |
| 1265 |
if close_source: |
| 1266 |
source.close() |
| 1267 |
gen.close() |
| 1268 |
|
| 1269 |
def __del__(self): |
| 1270 |
# TODO: Emit a ResourceWarning if it was not explicitly closed. |
| 1271 |
# (When the close() method will be supported in all maintained Python versions.) |
| 1272 |
if close_source: |
| 1273 |
source.close() |
| 1274 |
|
| 1275 |
it = IterParseIterator() |
| 1276 |
it.root = None |
| 1277 |
wr = weakref.ref(it) |
| 1278 |
return it |
| 1279 |
|
| 1280 |
|
| 1281 |
class XMLPullParser: |
| 1282 |
|
| 1283 |
def __init__(self, events=None, *, _parser=None): |
| 1284 |
# The _parser argument is for internal use only and must not be relied |
| 1285 |
# upon in user code. It will be removed in a future release. |
| 1286 |
# See https://bugs.python.org/issue17741 for more details. |
| 1287 |
|
| 1288 |
self._events_queue = collections.deque() |
| 1289 |
self._parser = _parser or XMLParser(target=TreeBuilder()) |
| 1290 |
# wire up the parser for event reporting |
| 1291 |
if events is None: |
| 1292 |
events = ("end",) |
| 1293 |
self._parser._setevents(self._events_queue, events) |
| 1294 |
|
| 1295 |
def feed(self, data): |
| 1296 |
"""Feed encoded data to parser.""" |
| 1297 |
if self._parser is None: |
| 1298 |
raise ValueError("feed() called after end of stream") |
| 1299 |
if data: |
| 1300 |
try: |
| 1301 |
self._parser.feed(data) |
| 1302 |
except SyntaxError as exc: |
| 1303 |
self._events_queue.append(exc) |
| 1304 |
|
| 1305 |
def _close_and_return_root(self): |
| 1306 |
# iterparse needs this to set its root attribute properly :( |
| 1307 |
root = self._parser.close() |
| 1308 |
self._parser = None |
| 1309 |
return root |
| 1310 |
|
| 1311 |
def close(self): |
| 1312 |
"""Finish feeding data to parser. |
| 1313 |
|
| 1314 |
Unlike XMLParser, does not return the root element. Use |
| 1315 |
read_events() to consume elements from XMLPullParser. |
| 1316 |
""" |
| 1317 |
self._close_and_return_root() |
| 1318 |
|
| 1319 |
def read_events(self): |
| 1320 |
"""Return an iterator over currently available (event, elem) pairs. |
| 1321 |
|
| 1322 |
Events are consumed from the internal event queue as they are |
| 1323 |
retrieved from the iterator. |
| 1324 |
""" |
| 1325 |
events = self._events_queue |
| 1326 |
while events: |
| 1327 |
event = events.popleft() |
| 1328 |
if isinstance(event, Exception): |
| 1329 |
raise event |
| 1330 |
else: |
| 1331 |
yield event |
| 1332 |
|
| 1333 |
def flush(self): |
| 1334 |
if self._parser is None: |
| 1335 |
raise ValueError("flush() called after end of stream") |
| 1336 |
self._parser.flush() |
| 1337 |
|
| 1338 |
|
| 1339 |
def XML(text, parser=None): |
| 1340 |
"""Parse XML document from string constant. |
| 1341 |
|
| 1342 |
This function can be used to embed "XML Literals" in Python code. |
| 1343 |
|
| 1344 |
*text* is a string containing XML data, *parser* is an |
| 1345 |
optional parser instance, defaulting to the standard XMLParser. |
| 1346 |
|
| 1347 |
Returns an Element instance. |
| 1348 |
|
| 1349 |
""" |
| 1350 |
if not parser: |
| 1351 |
parser = XMLParser(target=TreeBuilder()) |
| 1352 |
parser.feed(text) |
| 1353 |
return parser.close() |
| 1354 |
|
| 1355 |
|
| 1356 |
def XMLID(text, parser=None): |
| 1357 |
"""Parse XML document from string constant for its IDs. |
| 1358 |
|
| 1359 |
*text* is a string containing XML data, *parser* is an |
| 1360 |
optional parser instance, defaulting to the standard XMLParser. |
| 1361 |
|
| 1362 |
Returns an (Element, dict) tuple, in which the |
| 1363 |
dict maps element id:s to elements. |
| 1364 |
|
| 1365 |
""" |
| 1366 |
if not parser: |
| 1367 |
parser = XMLParser(target=TreeBuilder()) |
| 1368 |
parser.feed(text) |
| 1369 |
tree = parser.close() |
| 1370 |
ids = {} |
| 1371 |
for elem in tree.iter(): |
| 1372 |
id = elem.get("id") |
| 1373 |
if id: |
| 1374 |
ids[id] = elem |
| 1375 |
return tree, ids |
| 1376 |
|
| 1377 |
# Parse XML document from string constant. Alias for XML(). |
| 1378 |
fromstring = XML |
| 1379 |
|
| 1380 |
def fromstringlist(sequence, parser=None): |
| 1381 |
"""Parse XML document from sequence of string fragments. |
| 1382 |
|
| 1383 |
*sequence* is a list of other sequence, *parser* is an optional parser |
| 1384 |
instance, defaulting to the standard XMLParser. |
| 1385 |
|
| 1386 |
Returns an Element instance. |
| 1387 |
|
| 1388 |
""" |
| 1389 |
if not parser: |
| 1390 |
parser = XMLParser(target=TreeBuilder()) |
| 1391 |
for text in sequence: |
| 1392 |
parser.feed(text) |
| 1393 |
return parser.close() |
| 1394 |
|
| 1395 |
# -------------------------------------------------------------------- |
| 1396 |
|
| 1397 |
|
| 1398 |
class TreeBuilder: |
| 1399 |
"""Generic element structure builder. |
| 1400 |
|
| 1401 |
This builder converts a sequence of start, data, and end method |
| 1402 |
calls to a well-formed element structure. |
| 1403 |
|
| 1404 |
You can use this class to build an element structure using a custom XML |
| 1405 |
parser, or a parser for some other XML-like format. |
| 1406 |
|
| 1407 |
*element_factory* is an optional element factory which is called |
| 1408 |
to create new Element instances, as necessary. |
| 1409 |
|
| 1410 |
*comment_factory* is a factory to create comments to be used instead of |
| 1411 |
the standard factory. If *insert_comments* is false (the default), |
| 1412 |
comments will not be inserted into the tree. |
| 1413 |
|
| 1414 |
*pi_factory* is a factory to create processing instructions to be used |
| 1415 |
instead of the standard factory. If *insert_pis* is false (the default), |
| 1416 |
processing instructions will not be inserted into the tree. |
| 1417 |
""" |
| 1418 |
def __init__(self, element_factory=None, *, |
| 1419 |
comment_factory=None, pi_factory=None, |
| 1420 |
insert_comments=False, insert_pis=False): |
| 1421 |
self._data = [] # data collector |
| 1422 |
self._elem = [] # element stack |
| 1423 |
self._last = None # last element |
| 1424 |
self._root = None # root element |
| 1425 |
self._tail = None # true if we're after an end tag |
| 1426 |
if comment_factory is None: |
| 1427 |
comment_factory = Comment |
| 1428 |
self._comment_factory = comment_factory |
| 1429 |
self.insert_comments = insert_comments |
| 1430 |
if pi_factory is None: |
| 1431 |
pi_factory = ProcessingInstruction |
| 1432 |
self._pi_factory = pi_factory |
| 1433 |
self.insert_pis = insert_pis |
| 1434 |
if element_factory is None: |
| 1435 |
element_factory = Element |
| 1436 |
self._factory = element_factory |
| 1437 |
|
| 1438 |
def close(self): |
| 1439 |
"""Flush builder buffers and return toplevel document Element.""" |
| 1440 |
assert len(self._elem) == 0, "missing end tags" |
| 1441 |
assert self._root is not None, "missing toplevel element" |
| 1442 |
return self._root |
| 1443 |
|
| 1444 |
def _flush(self): |
| 1445 |
if self._data: |
| 1446 |
if self._last is not None: |
| 1447 |
text = "".join(self._data) |
| 1448 |
if self._tail: |
| 1449 |
assert self._last.tail is None, "internal error (tail)" |
| 1450 |
self._last.tail = text |
| 1451 |
else: |
| 1452 |
assert self._last.text is None, "internal error (text)" |
| 1453 |
self._last.text = text |
| 1454 |
self._data = [] |
| 1455 |
|
| 1456 |
def data(self, data): |
| 1457 |
"""Add text to current element.""" |
| 1458 |
self._data.append(data) |
| 1459 |
|
| 1460 |
def start(self, tag, attrs): |
| 1461 |
"""Open new element and return it. |
| 1462 |
|
| 1463 |
*tag* is the element name, *attrs* is a dict containing element |
| 1464 |
attributes. |
| 1465 |
|
| 1466 |
""" |
| 1467 |
self._flush() |
| 1468 |
self._last = elem = self._factory(tag, attrs) |
| 1469 |
if self._elem: |
| 1470 |
self._elem[-1].append(elem) |
| 1471 |
elif self._root is None: |
| 1472 |
self._root = elem |
| 1473 |
self._elem.append(elem) |
| 1474 |
self._tail = 0 |
| 1475 |
return elem |
| 1476 |
|
| 1477 |
def end(self, tag): |
| 1478 |
"""Close and return current Element. |
| 1479 |
|
| 1480 |
*tag* is the element name. |
| 1481 |
|
| 1482 |
""" |
| 1483 |
self._flush() |
| 1484 |
self._last = self._elem.pop() |
| 1485 |
assert self._last.tag == tag,\ |
| 1486 |
"end tag mismatch (expected %s, got %s)" % ( |
| 1487 |
self._last.tag, tag) |
| 1488 |
self._tail = 1 |
| 1489 |
return self._last |
| 1490 |
|
| 1491 |
def comment(self, text): |
| 1492 |
"""Create a comment using the comment_factory. |
| 1493 |
|
| 1494 |
*text* is the text of the comment. |
| 1495 |
""" |
| 1496 |
return self._handle_single( |
| 1497 |
self._comment_factory, self.insert_comments, text) |
| 1498 |
|
| 1499 |
def pi(self, target, text=None): |
| 1500 |
"""Create a processing instruction using the pi_factory. |
| 1501 |
|
| 1502 |
*target* is the target name of the processing instruction. |
| 1503 |
*text* is the data of the processing instruction, or ''. |
| 1504 |
""" |
| 1505 |
return self._handle_single( |
| 1506 |
self._pi_factory, self.insert_pis, target, text) |
| 1507 |
|
| 1508 |
def _handle_single(self, factory, insert, *args): |
| 1509 |
elem = factory(*args) |
| 1510 |
if insert: |
| 1511 |
self._flush() |
| 1512 |
self._last = elem |
| 1513 |
if self._elem: |
| 1514 |
self._elem[-1].append(elem) |
| 1515 |
self._tail = 1 |
| 1516 |
return elem |
| 1517 |
|
| 1518 |
|
| 1519 |
# also see ElementTree and TreeBuilder |
| 1520 |
class XMLParser: |
| 1521 |
"""Element structure builder for XML source data based on the expat parser. |
| 1522 |
|
| 1523 |
*target* is an optional target object which defaults to an instance of the |
| 1524 |
standard TreeBuilder class, *encoding* is an optional encoding string |
| 1525 |
which if given, overrides the encoding specified in the XML file: |
| 1526 |
http://www.iana.org/assignments/character-sets |
| 1527 |
|
| 1528 |
""" |
| 1529 |
|
| 1530 |
def __init__(self, *, target=None, encoding=None): |
| 1531 |
try: |
| 1532 |
from xml.parsers import expat |
| 1533 |
except ImportError: |
| 1534 |
try: |
| 1535 |
import pyexpat as expat |
| 1536 |
except ImportError: |
| 1537 |
raise ImportError( |
| 1538 |
"No module named expat; use SimpleXMLTreeBuilder instead" |
| 1539 |
) |
| 1540 |
parser = expat.ParserCreate(encoding, "}") |
| 1541 |
if target is None: |
| 1542 |
target = TreeBuilder() |
| 1543 |
# underscored names are provided for compatibility only |
| 1544 |
self.parser = self._parser = parser |
| 1545 |
self.target = self._target = target |
| 1546 |
self._error = expat.error |
| 1547 |
self._names = {} # name memo cache |
| 1548 |
# main callbacks |
| 1549 |
parser.DefaultHandlerExpand = self._default |
| 1550 |
if hasattr(target, 'start'): |
| 1551 |
parser.StartElementHandler = self._start |
| 1552 |
if hasattr(target, 'end'): |
| 1553 |
parser.EndElementHandler = self._end |
| 1554 |
if hasattr(target, 'start_ns'): |
| 1555 |
parser.StartNamespaceDeclHandler = self._start_ns |
| 1556 |
if hasattr(target, 'end_ns'): |
| 1557 |
parser.EndNamespaceDeclHandler = self._end_ns |
| 1558 |
if hasattr(target, 'data'): |
| 1559 |
parser.CharacterDataHandler = target.data |
| 1560 |
# miscellaneous callbacks |
| 1561 |
if hasattr(target, 'comment'): |
| 1562 |
parser.CommentHandler = target.comment |
| 1563 |
if hasattr(target, 'pi'): |
| 1564 |
parser.ProcessingInstructionHandler = target.pi |
| 1565 |
# Configure pyexpat: buffering, new-style attribute handling. |
| 1566 |
parser.buffer_text = 1 |
| 1567 |
parser.ordered_attributes = 1 |
| 1568 |
self._doctype = None |
| 1569 |
self.entity = {} |
| 1570 |
try: |
| 1571 |
self.version = "Expat %d.%d.%d" % expat.version_info |
| 1572 |
except AttributeError: |
| 1573 |
pass # unknown |
| 1574 |
|
| 1575 |
def _setevents(self, events_queue, events_to_report): |
| 1576 |
# Internal API for XMLPullParser |
| 1577 |
# events_to_report: a list of events to report during parsing (same as |
| 1578 |
# the *events* of XMLPullParser's constructor. |
| 1579 |
# events_queue: a list of actual parsing events that will be populated |
| 1580 |
# by the underlying parser. |
| 1581 |
# |
| 1582 |
parser = self._parser |
| 1583 |
append = events_queue.append |
| 1584 |
for event_name in events_to_report: |
| 1585 |
if event_name == "start": |
| 1586 |
parser.ordered_attributes = 1 |
| 1587 |
def handler(tag, attrib_in, event=event_name, append=append, |
| 1588 |
start=self._start): |
| 1589 |
append((event, start(tag, attrib_in))) |
| 1590 |
parser.StartElementHandler = handler |
| 1591 |
elif event_name == "end": |
| 1592 |
def handler(tag, event=event_name, append=append, |
| 1593 |
end=self._end): |
| 1594 |
append((event, end(tag))) |
| 1595 |
parser.EndElementHandler = handler |
| 1596 |
elif event_name == "start-ns": |
| 1597 |
# TreeBuilder does not implement .start_ns() |
| 1598 |
if hasattr(self.target, "start_ns"): |
| 1599 |
def handler(prefix, uri, event=event_name, append=append, |
| 1600 |
start_ns=self._start_ns): |
| 1601 |
append((event, start_ns(prefix, uri))) |
| 1602 |
else: |
| 1603 |
def handler(prefix, uri, event=event_name, append=append): |
| 1604 |
append((event, (prefix or '', uri or ''))) |
| 1605 |
parser.StartNamespaceDeclHandler = handler |
| 1606 |
elif event_name == "end-ns": |
| 1607 |
# TreeBuilder does not implement .end_ns() |
| 1608 |
if hasattr(self.target, "end_ns"): |
| 1609 |
def handler(prefix, event=event_name, append=append, |
| 1610 |
end_ns=self._end_ns): |
| 1611 |
append((event, end_ns(prefix))) |
| 1612 |
else: |
| 1613 |
def handler(prefix, event=event_name, append=append): |
| 1614 |
append((event, None)) |
| 1615 |
parser.EndNamespaceDeclHandler = handler |
| 1616 |
elif event_name == 'comment': |
| 1617 |
def handler(text, event=event_name, append=append, self=self): |
| 1618 |
append((event, self.target.comment(text))) |
| 1619 |
parser.CommentHandler = handler |
| 1620 |
elif event_name == 'pi': |
| 1621 |
def handler(pi_target, data, event=event_name, append=append, |
| 1622 |
self=self): |
| 1623 |
append((event, self.target.pi(pi_target, data))) |
| 1624 |
parser.ProcessingInstructionHandler = handler |
| 1625 |
else: |
| 1626 |
raise ValueError("unknown event %r" % event_name) |
| 1627 |
|
| 1628 |
def _raiseerror(self, value): |
| 1629 |
err = ParseError(value) |
| 1630 |
err.code = value.code |
| 1631 |
err.position = value.lineno, value.offset |
| 1632 |
raise err |
| 1633 |
|
| 1634 |
def _fixname(self, key): |
| 1635 |
# expand qname, and convert name string to ascii, if possible |
| 1636 |
try: |
| 1637 |
name = self._names[key] |
| 1638 |
except KeyError: |
| 1639 |
name = key |
| 1640 |
if "}" in name: |
| 1641 |
name = "{" + name |
| 1642 |
self._names[key] = name |
| 1643 |
return name |
| 1644 |
|
| 1645 |
def _start_ns(self, prefix, uri): |
| 1646 |
return self.target.start_ns(prefix or '', uri or '') |
| 1647 |
|
| 1648 |
def _end_ns(self, prefix): |
| 1649 |
return self.target.end_ns(prefix or '') |
| 1650 |
|
| 1651 |
def _start(self, tag, attr_list): |
| 1652 |
# Handler for expat's StartElementHandler. Since ordered_attributes |
| 1653 |
# is set, the attributes are reported as a list of alternating |
| 1654 |
# attribute name,value. |
| 1655 |
fixname = self._fixname |
| 1656 |
tag = fixname(tag) |
| 1657 |
attrib = {} |
| 1658 |
if attr_list: |
| 1659 |
for i in range(0, len(attr_list), 2): |
| 1660 |
attrib[fixname(attr_list[i])] = attr_list[i+1] |
| 1661 |
return self.target.start(tag, attrib) |
| 1662 |
|
| 1663 |
def _end(self, tag): |
| 1664 |
return self.target.end(self._fixname(tag)) |
| 1665 |
|
| 1666 |
def _default(self, text): |
| 1667 |
prefix = text[:1] |
| 1668 |
if prefix == "&": |
| 1669 |
# deal with undefined entities |
| 1670 |
try: |
| 1671 |
data_handler = self.target.data |
| 1672 |
except AttributeError: |
| 1673 |
return |
| 1674 |
try: |
| 1675 |
data_handler(self.entity[text[1:-1]]) |
| 1676 |
except KeyError: |
| 1677 |
from xml.parsers import expat |
| 1678 |
err = expat.error( |
| 1679 |
"undefined entity %s: line %d, column %d" % |
| 1680 |
(text, self.parser.ErrorLineNumber, |
| 1681 |
self.parser.ErrorColumnNumber) |
| 1682 |
) |
| 1683 |
err.code = 11 # XML_ERROR_UNDEFINED_ENTITY |
| 1684 |
err.lineno = self.parser.ErrorLineNumber |
| 1685 |
err.offset = self.parser.ErrorColumnNumber |
| 1686 |
raise err |
| 1687 |
elif prefix == "<" and text[:9] == "<!DOCTYPE": |
| 1688 |
self._doctype = [] # inside a doctype declaration |
| 1689 |
elif self._doctype is not None: |
| 1690 |
# parse doctype contents |
| 1691 |
if prefix == ">": |
| 1692 |
self._doctype = None |
| 1693 |
return |
| 1694 |
text = text.strip() |
| 1695 |
if not text: |
| 1696 |
return |
| 1697 |
self._doctype.append(text) |
| 1698 |
n = len(self._doctype) |
| 1699 |
if n > 2: |
| 1700 |
type = self._doctype[1] |
| 1701 |
if type == "PUBLIC" and n == 4: |
| 1702 |
name, type, pubid, system = self._doctype |
| 1703 |
if pubid: |
| 1704 |
pubid = pubid[1:-1] |
| 1705 |
elif type == "SYSTEM" and n == 3: |
| 1706 |
name, type, system = self._doctype |
| 1707 |
pubid = None |
| 1708 |
else: |
| 1709 |
return |
| 1710 |
if hasattr(self.target, "doctype"): |
| 1711 |
self.target.doctype(name, pubid, system[1:-1]) |
| 1712 |
elif hasattr(self, "doctype"): |
| 1713 |
warnings.warn( |
| 1714 |
"The doctype() method of XMLParser is ignored. " |
| 1715 |
"Define doctype() method on the TreeBuilder target.", |
| 1716 |
RuntimeWarning) |
| 1717 |
|
| 1718 |
self._doctype = None |
| 1719 |
|
| 1720 |
def feed(self, data): |
| 1721 |
"""Feed encoded data to parser.""" |
| 1722 |
try: |
| 1723 |
self.parser.Parse(data, False) |
| 1724 |
except self._error as v: |
| 1725 |
self._raiseerror(v) |
| 1726 |
|
| 1727 |
def close(self): |
| 1728 |
"""Finish feeding data to parser and return element structure.""" |
| 1729 |
try: |
| 1730 |
self.parser.Parse(b"", True) # end of data |
| 1731 |
except self._error as v: |
| 1732 |
self._raiseerror(v) |
| 1733 |
try: |
| 1734 |
close_handler = self.target.close |
| 1735 |
except AttributeError: |
| 1736 |
pass |
| 1737 |
else: |
| 1738 |
return close_handler() |
| 1739 |
finally: |
| 1740 |
# get rid of circular references |
| 1741 |
del self.parser, self._parser |
| 1742 |
del self.target, self._target |
| 1743 |
|
| 1744 |
def flush(self): |
| 1745 |
was_enabled = self.parser.GetReparseDeferralEnabled() |
| 1746 |
try: |
| 1747 |
self.parser.SetReparseDeferralEnabled(False) |
| 1748 |
self.parser.Parse(b"", False) |
| 1749 |
except self._error as v: |
| 1750 |
self._raiseerror(v) |
| 1751 |
finally: |
| 1752 |
self.parser.SetReparseDeferralEnabled(was_enabled) |
| 1753 |
|
| 1754 |
# -------------------------------------------------------------------- |
| 1755 |
# C14N 2.0 |
| 1756 |
|
| 1757 |
def canonicalize(xml_data=None, *, out=None, from_file=None, **options): |
| 1758 |
"""Convert XML to its C14N 2.0 serialised form. |
| 1759 |
|
| 1760 |
If *out* is provided, it must be a file or file-like object that receives |
| 1761 |
the serialised canonical XML output (text, not bytes) through its ``.write()`` |
| 1762 |
method. To write to a file, open it in text mode with encoding "utf-8". |
| 1763 |
If *out* is not provided, this function returns the output as text string. |
| 1764 |
|
| 1765 |
Either *xml_data* (an XML string) or *from_file* (a file path or |
| 1766 |
file-like object) must be provided as input. |
| 1767 |
|
| 1768 |
The configuration options are the same as for the ``C14NWriterTarget``. |
| 1769 |
""" |
| 1770 |
if xml_data is None and from_file is None: |
| 1771 |
raise ValueError("Either 'xml_data' or 'from_file' must be provided as input") |
| 1772 |
sio = None |
| 1773 |
if out is None: |
| 1774 |
sio = out = io.StringIO() |
| 1775 |
|
| 1776 |
parser = XMLParser(target=C14NWriterTarget(out.write, **options)) |
| 1777 |
|
| 1778 |
if xml_data is not None: |
| 1779 |
parser.feed(xml_data) |
| 1780 |
parser.close() |
| 1781 |
elif from_file is not None: |
| 1782 |
parse(from_file, parser=parser) |
| 1783 |
|
| 1784 |
return sio.getvalue() if sio is not None else None |
| 1785 |
|
| 1786 |
|
| 1787 |
_looks_like_prefix_name = re.compile(r'^\w+:\w+$', re.UNICODE).match |
| 1788 |
|
| 1789 |
|
| 1790 |
class C14NWriterTarget: |
| 1791 |
""" |
| 1792 |
Canonicalization writer target for the XMLParser. |
| 1793 |
|
| 1794 |
Serialises parse events to XML C14N 2.0. |
| 1795 |
|
| 1796 |
The *write* function is used for writing out the resulting data stream |
| 1797 |
as text (not bytes). To write to a file, open it in text mode with encoding |
| 1798 |
"utf-8" and pass its ``.write`` method. |
| 1799 |
|
| 1800 |
Configuration options: |
| 1801 |
|
| 1802 |
- *with_comments*: set to true to include comments |
| 1803 |
- *strip_text*: set to true to strip whitespace before and after text content |
| 1804 |
- *rewrite_prefixes*: set to true to replace namespace prefixes by "n{number}" |
| 1805 |
- *qname_aware_tags*: a set of qname aware tag names in which prefixes |
| 1806 |
should be replaced in text content |
| 1807 |
- *qname_aware_attrs*: a set of qname aware attribute names in which prefixes |
| 1808 |
should be replaced in text content |
| 1809 |
- *exclude_attrs*: a set of attribute names that should not be serialised |
| 1810 |
- *exclude_tags*: a set of tag names that should not be serialised |
| 1811 |
""" |
| 1812 |
def __init__(self, write, *, |
| 1813 |
with_comments=False, strip_text=False, rewrite_prefixes=False, |
| 1814 |
qname_aware_tags=None, qname_aware_attrs=None, |
| 1815 |
exclude_attrs=None, exclude_tags=None): |
| 1816 |
self._write = write |
| 1817 |
self._data = [] |
| 1818 |
self._with_comments = with_comments |
| 1819 |
self._strip_text = strip_text |
| 1820 |
self._exclude_attrs = set(exclude_attrs) if exclude_attrs else None |
| 1821 |
self._exclude_tags = set(exclude_tags) if exclude_tags else None |
| 1822 |
|
| 1823 |
self._rewrite_prefixes = rewrite_prefixes |
| 1824 |
if qname_aware_tags: |
| 1825 |
self._qname_aware_tags = set(qname_aware_tags) |
| 1826 |
else: |
| 1827 |
self._qname_aware_tags = None |
| 1828 |
if qname_aware_attrs: |
| 1829 |
self._find_qname_aware_attrs = set(qname_aware_attrs).intersection |
| 1830 |
else: |
| 1831 |
self._find_qname_aware_attrs = None |
| 1832 |
|
| 1833 |
# Stack with globally and newly declared namespaces as (uri, prefix) pairs. |
| 1834 |
self._declared_ns_stack = [[ |
| 1835 |
("http://www.w3.org/XML/1998/namespace", "xml"), |
| 1836 |
]] |
| 1837 |
# Stack with user declared namespace prefixes as (uri, prefix) pairs. |
| 1838 |
self._ns_stack = [] |
| 1839 |
if not rewrite_prefixes: |
| 1840 |
self._ns_stack.append(list(_namespace_map.items())) |
| 1841 |
self._ns_stack.append([]) |
| 1842 |
self._prefix_map = {} |
| 1843 |
self._preserve_space = [False] |
| 1844 |
self._pending_start = None |
| 1845 |
self._root_seen = False |
| 1846 |
self._root_done = False |
| 1847 |
self._ignored_depth = 0 |
| 1848 |
|
| 1849 |
def _iter_namespaces(self, ns_stack, _reversed=reversed): |
| 1850 |
for namespaces in _reversed(ns_stack): |
| 1851 |
if namespaces: # almost no element declares new namespaces |
| 1852 |
yield from namespaces |
| 1853 |
|
| 1854 |
def _resolve_prefix_name(self, prefixed_name): |
| 1855 |
prefix, name = prefixed_name.split(':', 1) |
| 1856 |
for uri, p in self._iter_namespaces(self._ns_stack): |
| 1857 |
if p == prefix: |
| 1858 |
return f'{{{uri}}}{name}' |
| 1859 |
raise ValueError(f'Prefix {prefix} of QName "{prefixed_name}" is not declared in scope') |
| 1860 |
|
| 1861 |
def _qname(self, qname, uri=None): |
| 1862 |
if uri is None: |
| 1863 |
uri, tag = qname[1:].rsplit('}', 1) if qname[:1] == '{' else ('', qname) |
| 1864 |
else: |
| 1865 |
tag = qname |
| 1866 |
|
| 1867 |
prefixes_seen = set() |
| 1868 |
for u, prefix in self._iter_namespaces(self._declared_ns_stack): |
| 1869 |
if u == uri and prefix not in prefixes_seen: |
| 1870 |
return f'{prefix}:{tag}' if prefix else tag, tag, uri |
| 1871 |
prefixes_seen.add(prefix) |
| 1872 |
|
| 1873 |
# Not declared yet => add new declaration. |
| 1874 |
if self._rewrite_prefixes: |
| 1875 |
if uri in self._prefix_map: |
| 1876 |
prefix = self._prefix_map[uri] |
| 1877 |
else: |
| 1878 |
prefix = self._prefix_map[uri] = f'n{len(self._prefix_map)}' |
| 1879 |
self._declared_ns_stack[-1].append((uri, prefix)) |
| 1880 |
return f'{prefix}:{tag}', tag, uri |
| 1881 |
|
| 1882 |
if not uri and '' not in prefixes_seen: |
| 1883 |
# No default namespace declared => no prefix needed. |
| 1884 |
return tag, tag, uri |
| 1885 |
|
| 1886 |
for u, prefix in self._iter_namespaces(self._ns_stack): |
| 1887 |
if u == uri: |
| 1888 |
self._declared_ns_stack[-1].append((uri, prefix)) |
| 1889 |
return f'{prefix}:{tag}' if prefix else tag, tag, uri |
| 1890 |
|
| 1891 |
if not uri: |
| 1892 |
# As soon as a default namespace is defined, |
| 1893 |
# anything that has no namespace (and thus, no prefix) goes there. |
| 1894 |
return tag, tag, uri |
| 1895 |
|
| 1896 |
raise ValueError(f'Namespace "{uri}" is not declared in scope') |
| 1897 |
|
| 1898 |
def data(self, data): |
| 1899 |
if not self._ignored_depth: |
| 1900 |
self._data.append(data) |
| 1901 |
|
| 1902 |
def _flush(self, _join_text=''.join): |
| 1903 |
data = _join_text(self._data) |
| 1904 |
del self._data[:] |
| 1905 |
if self._strip_text and not self._preserve_space[-1]: |
| 1906 |
data = data.strip() |
| 1907 |
if self._pending_start is not None: |
| 1908 |
args, self._pending_start = self._pending_start, None |
| 1909 |
qname_text = data if data and _looks_like_prefix_name(data) else None |
| 1910 |
self._start(*args, qname_text) |
| 1911 |
if qname_text is not None: |
| 1912 |
return |
| 1913 |
if data and self._root_seen: |
| 1914 |
self._write(_escape_cdata_c14n(data)) |
| 1915 |
|
| 1916 |
def start_ns(self, prefix, uri): |
| 1917 |
if self._ignored_depth: |
| 1918 |
return |
| 1919 |
# we may have to resolve qnames in text content |
| 1920 |
if self._data: |
| 1921 |
self._flush() |
| 1922 |
self._ns_stack[-1].append((uri, prefix)) |
| 1923 |
|
| 1924 |
def start(self, tag, attrs): |
| 1925 |
if self._exclude_tags is not None and ( |
| 1926 |
self._ignored_depth or tag in self._exclude_tags): |
| 1927 |
self._ignored_depth += 1 |
| 1928 |
return |
| 1929 |
if self._data: |
| 1930 |
self._flush() |
| 1931 |
|
| 1932 |
new_namespaces = [] |
| 1933 |
self._declared_ns_stack.append(new_namespaces) |
| 1934 |
|
| 1935 |
if self._qname_aware_tags is not None and tag in self._qname_aware_tags: |
| 1936 |
# Need to parse text first to see if it requires a prefix declaration. |
| 1937 |
self._pending_start = (tag, attrs, new_namespaces) |
| 1938 |
return |
| 1939 |
self._start(tag, attrs, new_namespaces) |
| 1940 |
|
| 1941 |
def _start(self, tag, attrs, new_namespaces, qname_text=None): |
| 1942 |
if self._exclude_attrs is not None and attrs: |
| 1943 |
attrs = {k: v for k, v in attrs.items() if k not in self._exclude_attrs} |
| 1944 |
|
| 1945 |
qnames = {tag, *attrs} |
| 1946 |
resolved_names = {} |
| 1947 |
|
| 1948 |
# Resolve prefixes in attribute and tag text. |
| 1949 |
if qname_text is not None: |
| 1950 |
qname = resolved_names[qname_text] = self._resolve_prefix_name(qname_text) |
| 1951 |
qnames.add(qname) |
| 1952 |
if self._find_qname_aware_attrs is not None and attrs: |
| 1953 |
qattrs = self._find_qname_aware_attrs(attrs) |
| 1954 |
if qattrs: |
| 1955 |
for attr_name in qattrs: |
| 1956 |
value = attrs[attr_name] |
| 1957 |
if _looks_like_prefix_name(value): |
| 1958 |
qname = resolved_names[value] = self._resolve_prefix_name(value) |
| 1959 |
qnames.add(qname) |
| 1960 |
else: |
| 1961 |
qattrs = None |
| 1962 |
else: |
| 1963 |
qattrs = None |
| 1964 |
|
| 1965 |
# Assign prefixes in lexicographical order of used URIs. |
| 1966 |
parse_qname = self._qname |
| 1967 |
parsed_qnames = {n: parse_qname(n) for n in sorted( |
| 1968 |
qnames, key=lambda n: n.split('}', 1))} |
| 1969 |
|
| 1970 |
# Write namespace declarations in prefix order ... |
| 1971 |
if new_namespaces: |
| 1972 |
attr_list = [ |
| 1973 |
('xmlns:' + prefix if prefix else 'xmlns', uri) |
| 1974 |
for uri, prefix in new_namespaces |
| 1975 |
] |
| 1976 |
attr_list.sort() |
| 1977 |
else: |
| 1978 |
# almost always empty |
| 1979 |
attr_list = [] |
| 1980 |
|
| 1981 |
# ... followed by attributes in URI+name order |
| 1982 |
if attrs: |
| 1983 |
for k, v in sorted(attrs.items()): |
| 1984 |
if qattrs is not None and k in qattrs and v in resolved_names: |
| 1985 |
v = parsed_qnames[resolved_names[v]][0] |
| 1986 |
attr_qname, attr_name, uri = parsed_qnames[k] |
| 1987 |
# No prefix for attributes in default ('') namespace. |
| 1988 |
attr_list.append((attr_qname if uri else attr_name, v)) |
| 1989 |
|
| 1990 |
# Honour xml:space attributes. |
| 1991 |
space_behaviour = attrs.get('{http://www.w3.org/XML/1998/namespace}space') |
| 1992 |
self._preserve_space.append( |
| 1993 |
space_behaviour == 'preserve' if space_behaviour |
| 1994 |
else self._preserve_space[-1]) |
| 1995 |
|
| 1996 |
# Write the tag. |
| 1997 |
write = self._write |
| 1998 |
write('<' + parsed_qnames[tag][0]) |
| 1999 |
if attr_list: |
| 2000 |
write(''.join([f' {k}="{_escape_attrib_c14n(v)}"' for k, v in attr_list])) |
| 2001 |
write('>') |
| 2002 |
|
| 2003 |
# Write the resolved qname text content. |
| 2004 |
if qname_text is not None: |
| 2005 |
write(_escape_cdata_c14n(parsed_qnames[resolved_names[qname_text]][0])) |
| 2006 |
|
| 2007 |
self._root_seen = True |
| 2008 |
self._ns_stack.append([]) |
| 2009 |
|
| 2010 |
def end(self, tag): |
| 2011 |
if self._ignored_depth: |
| 2012 |
self._ignored_depth -= 1 |
| 2013 |
return |
| 2014 |
if self._data: |
| 2015 |
self._flush() |
| 2016 |
self._write(f'</{self._qname(tag)[0]}>') |
| 2017 |
self._preserve_space.pop() |
| 2018 |
self._root_done = len(self._preserve_space) == 1 |
| 2019 |
self._declared_ns_stack.pop() |
| 2020 |
self._ns_stack.pop() |
| 2021 |
|
| 2022 |
def comment(self, text): |
| 2023 |
if not self._with_comments: |
| 2024 |
return |
| 2025 |
if self._ignored_depth: |
| 2026 |
return |
| 2027 |
if self._root_done: |
| 2028 |
self._write('\n') |
| 2029 |
elif self._root_seen and self._data: |
| 2030 |
self._flush() |
| 2031 |
self._write(f'<!--{_escape_cdata_c14n(text)}-->') |
| 2032 |
if not self._root_seen: |
| 2033 |
self._write('\n') |
| 2034 |
|
| 2035 |
def pi(self, target, data): |
| 2036 |
if self._ignored_depth: |
| 2037 |
return |
| 2038 |
if self._root_done: |
| 2039 |
self._write('\n') |
| 2040 |
elif self._root_seen and self._data: |
| 2041 |
self._flush() |
| 2042 |
self._write( |
| 2043 |
f'<?{target} {_escape_cdata_c14n(data)}?>' if data else f'<?{target}?>') |
| 2044 |
if not self._root_seen: |
| 2045 |
self._write('\n') |
| 2046 |
|
| 2047 |
|
| 2048 |
def _escape_cdata_c14n(text): |
| 2049 |
# escape character data |
| 2050 |
try: |
| 2051 |
# it's worth avoiding do-nothing calls for strings that are |
| 2052 |
# shorter than 500 character, or so. assume that's, by far, |
| 2053 |
# the most common case in most applications. |
| 2054 |
if '&' in text: |
| 2055 |
text = text.replace('&', '&') |
| 2056 |
if '<' in text: |
| 2057 |
text = text.replace('<', '<') |
| 2058 |
if '>' in text: |
| 2059 |
text = text.replace('>', '>') |
| 2060 |
if '\r' in text: |
| 2061 |
text = text.replace('\r', '
') |
| 2062 |
return text |
| 2063 |
except (TypeError, AttributeError): |
| 2064 |
_raise_serialization_error(text) |
| 2065 |
|
| 2066 |
|
| 2067 |
def _escape_attrib_c14n(text): |
| 2068 |
# escape attribute value |
| 2069 |
try: |
| 2070 |
if '&' in text: |
| 2071 |
text = text.replace('&', '&') |
| 2072 |
if '<' in text: |
| 2073 |
text = text.replace('<', '<') |
| 2074 |
if '"' in text: |
| 2075 |
text = text.replace('"', '"') |
| 2076 |
if '\t' in text: |
| 2077 |
text = text.replace('\t', '	') |
| 2078 |
if '\n' in text: |
| 2079 |
text = text.replace('\n', '
') |
| 2080 |
if '\r' in text: |
| 2081 |
text = text.replace('\r', '
') |
| 2082 |
return text |
| 2083 |
except (TypeError, AttributeError): |
| 2084 |
_raise_serialization_error(text) |
| 2085 |
|
| 2086 |
|
| 2087 |
# -------------------------------------------------------------------- |
| 2088 |
|
| 2089 |
# Import the C accelerators |
| 2090 |
try: |
| 2091 |
# Element is going to be shadowed by the C implementation. We need to keep |
| 2092 |
# the Python version of it accessible for some "creative" by external code |
| 2093 |
# (see tests) |
| 2094 |
_Element_Py = Element |
| 2095 |
|
| 2096 |
# Element, SubElement, ParseError, TreeBuilder, XMLParser, _set_factories |
| 2097 |
from _elementtree import * |
| 2098 |
from _elementtree import _set_factories |
| 2099 |
except ImportError: |
| 2100 |
pass |
| 2101 |
else: |
| 2102 |
_set_factories(Comment, ProcessingInstruction) |