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