Debian Codegraph @

Lib/xml/etree/ElementTree.py

raw
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("&", "&amp;")
1026 if "<" in text:
1027 text = text.replace("<", "&lt;")
1028 if ">" in text:
1029 text = text.replace(">", "&gt;")
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("&", "&amp;")
1039 if "<" in text:
1040 text = text.replace("<", "&lt;")
1041 if ">" in text:
1042 text = text.replace(">", "&gt;")
1043 if "\"" in text:
1044 text = text.replace("\"", "&quot;")
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", "&#13;")
1054 if "\n" in text:
1055 text = text.replace("\n", "&#10;")
1056 if "\t" in text:
1057 text = text.replace("\t", "&#09;")
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("&", "&amp;")
1067 if ">" in text:
1068 text = text.replace(">", "&gt;")
1069 if "\"" in text:
1070 text = text.replace("\"", "&quot;")
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('&', '&amp;')
2056 if '<' in text:
2057 text = text.replace('<', '&lt;')
2058 if '>' in text:
2059 text = text.replace('>', '&gt;')
2060 if '\r' in text:
2061 text = text.replace('\r', '&#xD;')
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('&', '&amp;')
2072 if '<' in text:
2073 text = text.replace('<', '&lt;')
2074 if '"' in text:
2075 text = text.replace('"', '&quot;')
2076 if '\t' in text:
2077 text = text.replace('\t', '&#x9;')
2078 if '\n' in text:
2079 text = text.replace('\n', '&#xA;')
2080 if '\r' in text:
2081 text = text.replace('\r', '&#xD;')
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)