ElementTree.py 40 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254
  1. #
  2. # ElementTree
  3. # $Id: ElementTree.py 2326 2005-03-17 07:45:21Z fredrik $
  4. #
  5. # light-weight XML support for Python 1.5.2 and later.
  6. #
  7. # history:
  8. # 2001-10-20 fl created (from various sources)
  9. # 2001-11-01 fl return root from parse method
  10. # 2002-02-16 fl sort attributes in lexical order
  11. # 2002-04-06 fl TreeBuilder refactoring, added PythonDoc markup
  12. # 2002-05-01 fl finished TreeBuilder refactoring
  13. # 2002-07-14 fl added basic namespace support to ElementTree.write
  14. # 2002-07-25 fl added QName attribute support
  15. # 2002-10-20 fl fixed encoding in write
  16. # 2002-11-24 fl changed default encoding to ascii; fixed attribute encoding
  17. # 2002-11-27 fl accept file objects or file names for parse/write
  18. # 2002-12-04 fl moved XMLTreeBuilder back to this module
  19. # 2003-01-11 fl fixed entity encoding glitch for us-ascii
  20. # 2003-02-13 fl added XML literal factory
  21. # 2003-02-21 fl added ProcessingInstruction/PI factory
  22. # 2003-05-11 fl added tostring/fromstring helpers
  23. # 2003-05-26 fl added ElementPath support
  24. # 2003-07-05 fl added makeelement factory method
  25. # 2003-07-28 fl added more well-known namespace prefixes
  26. # 2003-08-15 fl fixed typo in ElementTree.findtext (Thomas Dartsch)
  27. # 2003-09-04 fl fall back on emulator if ElementPath is not installed
  28. # 2003-10-31 fl markup updates
  29. # 2003-11-15 fl fixed nested namespace bug
  30. # 2004-03-28 fl added XMLID helper
  31. # 2004-06-02 fl added default support to findtext
  32. # 2004-06-08 fl fixed encoding of non-ascii element/attribute names
  33. # 2004-08-23 fl take advantage of post-2.1 expat features
  34. # 2005-02-01 fl added iterparse implementation
  35. # 2005-03-02 fl fixed iterparse support for pre-2.2 versions
  36. #
  37. # Copyright (c) 1999-2005 by Fredrik Lundh. All rights reserved.
  38. #
  39. # fredrik@pythonware.com
  40. # http://www.pythonware.com
  41. #
  42. # --------------------------------------------------------------------
  43. # The ElementTree toolkit is
  44. #
  45. # Copyright (c) 1999-2005 by Fredrik Lundh
  46. #
  47. # By obtaining, using, and/or copying this software and/or its
  48. # associated documentation, you agree that you have read, understood,
  49. # and will comply with the following terms and conditions:
  50. #
  51. # Permission to use, copy, modify, and distribute this software and
  52. # its associated documentation for any purpose and without fee is
  53. # hereby granted, provided that the above copyright notice appears in
  54. # all copies, and that both that copyright notice and this permission
  55. # notice appear in supporting documentation, and that the name of
  56. # Secret Labs AB or the author not be used in advertising or publicity
  57. # pertaining to distribution of the software without specific, written
  58. # prior permission.
  59. #
  60. # SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
  61. # TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT-
  62. # ABILITY AND FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR
  63. # BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
  64. # DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  65. # WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  66. # ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  67. # OF THIS SOFTWARE.
  68. # --------------------------------------------------------------------
  69. __all__ = [
  70. # public symbols
  71. "Comment",
  72. "dump",
  73. "Element", "ElementTree",
  74. "fromstring",
  75. "iselement", "iterparse",
  76. "parse",
  77. "PI", "ProcessingInstruction",
  78. "QName",
  79. "SubElement",
  80. "tostring",
  81. "TreeBuilder",
  82. "VERSION", "XML",
  83. "XMLTreeBuilder",
  84. ]
  85. ##
  86. # The <b>Element</b> type is a flexible container object, designed to
  87. # store hierarchical data structures in memory. The type can be
  88. # described as a cross between a list and a dictionary.
  89. # <p>
  90. # Each element has a number of properties associated with it:
  91. # <ul>
  92. # <li>a <i>tag</i>. This is a string identifying what kind of data
  93. # this element represents (the element type, in other words).</li>
  94. # <li>a number of <i>attributes</i>, stored in a Python dictionary.</li>
  95. # <li>a <i>text</i> string.</li>
  96. # <li>an optional <i>tail</i> string.</li>
  97. # <li>a number of <i>child elements</i>, stored in a Python sequence</li>
  98. # </ul>
  99. #
  100. # To create an element instance, use the {@link #Element} or {@link
  101. # #SubElement} factory functions.
  102. # <p>
  103. # The {@link #ElementTree} class can be used to wrap an element
  104. # structure, and convert it from and to XML.
  105. ##
  106. import string, sys, re
  107. class _SimpleElementPath:
  108. # emulate pre-1.2 find/findtext/findall behaviour
  109. def find(self, element, tag):
  110. for elem in element:
  111. if elem.tag == tag:
  112. return elem
  113. return None
  114. def findtext(self, element, tag, default=None):
  115. for elem in element:
  116. if elem.tag == tag:
  117. return elem.text or ""
  118. return default
  119. def findall(self, element, tag):
  120. if tag[:3] == ".//":
  121. return element.getiterator(tag[3:])
  122. result = []
  123. for elem in element:
  124. if elem.tag == tag:
  125. result.append(elem)
  126. return result
  127. try:
  128. import ElementPath
  129. except ImportError:
  130. # FIXME: issue warning in this case?
  131. ElementPath = _SimpleElementPath()
  132. # TODO: add support for custom namespace resolvers/default namespaces
  133. # TODO: add improved support for incremental parsing
  134. VERSION = "1.2.6"
  135. ##
  136. # Internal element class. This class defines the Element interface,
  137. # and provides a reference implementation of this interface.
  138. # <p>
  139. # You should not create instances of this class directly. Use the
  140. # appropriate factory functions instead, such as {@link #Element}
  141. # and {@link #SubElement}.
  142. #
  143. # @see Element
  144. # @see SubElement
  145. # @see Comment
  146. # @see ProcessingInstruction
  147. class _ElementInterface:
  148. # <tag attrib>text<child/>...</tag>tail
  149. ##
  150. # (Attribute) Element tag.
  151. tag = None
  152. ##
  153. # (Attribute) Element attribute dictionary. Where possible, use
  154. # {@link #_ElementInterface.get},
  155. # {@link #_ElementInterface.set},
  156. # {@link #_ElementInterface.keys}, and
  157. # {@link #_ElementInterface.items} to access
  158. # element attributes.
  159. attrib = None
  160. ##
  161. # (Attribute) Text before first subelement. This is either a
  162. # string or the value None, if there was no text.
  163. text = None
  164. ##
  165. # (Attribute) Text after this element's end tag, but before the
  166. # next sibling element's start tag. This is either a string or
  167. # the value None, if there was no text.
  168. tail = None # text after end tag, if any
  169. def __init__(self, tag, attrib):
  170. self.tag = tag
  171. self.attrib = attrib
  172. self._children = []
  173. def __repr__(self):
  174. return "<Element %s at %x>" % (self.tag, id(self))
  175. ##
  176. # Creates a new element object of the same type as this element.
  177. #
  178. # @param tag Element tag.
  179. # @param attrib Element attributes, given as a dictionary.
  180. # @return A new element instance.
  181. def makeelement(self, tag, attrib):
  182. return Element(tag, attrib)
  183. ##
  184. # Returns the number of subelements.
  185. #
  186. # @return The number of subelements.
  187. def __len__(self):
  188. return len(self._children)
  189. ##
  190. # Returns the given subelement.
  191. #
  192. # @param index What subelement to return.
  193. # @return The given subelement.
  194. # @exception IndexError If the given element does not exist.
  195. def __getitem__(self, index):
  196. return self._children[index]
  197. ##
  198. # Replaces the given subelement.
  199. #
  200. # @param index What subelement to replace.
  201. # @param element The new element value.
  202. # @exception IndexError If the given element does not exist.
  203. # @exception AssertionError If element is not a valid object.
  204. def __setitem__(self, index, element):
  205. assert iselement(element)
  206. self._children[index] = element
  207. ##
  208. # Deletes the given subelement.
  209. #
  210. # @param index What subelement to delete.
  211. # @exception IndexError If the given element does not exist.
  212. def __delitem__(self, index):
  213. del self._children[index]
  214. ##
  215. # Returns a list containing subelements in the given range.
  216. #
  217. # @param start The first subelement to return.
  218. # @param stop The first subelement that shouldn't be returned.
  219. # @return A sequence object containing subelements.
  220. def __getslice__(self, start, stop):
  221. return self._children[start:stop]
  222. ##
  223. # Replaces a number of subelements with elements from a sequence.
  224. #
  225. # @param start The first subelement to replace.
  226. # @param stop The first subelement that shouldn't be replaced.
  227. # @param elements A sequence object with zero or more elements.
  228. # @exception AssertionError If a sequence member is not a valid object.
  229. def __setslice__(self, start, stop, elements):
  230. for element in elements:
  231. assert iselement(element)
  232. self._children[start:stop] = list(elements)
  233. ##
  234. # Deletes a number of subelements.
  235. #
  236. # @param start The first subelement to delete.
  237. # @param stop The first subelement to leave in there.
  238. def __delslice__(self, start, stop):
  239. del self._children[start:stop]
  240. ##
  241. # Adds a subelement to the end of this element.
  242. #
  243. # @param element The element to add.
  244. # @exception AssertionError If a sequence member is not a valid object.
  245. def append(self, element):
  246. assert iselement(element)
  247. self._children.append(element)
  248. ##
  249. # Inserts a subelement at the given position in this element.
  250. #
  251. # @param index Where to insert the new subelement.
  252. # @exception AssertionError If the element is not a valid object.
  253. def insert(self, index, element):
  254. assert iselement(element)
  255. self._children.insert(index, element)
  256. ##
  257. # Removes a matching subelement. Unlike the <b>find</b> methods,
  258. # this method compares elements based on identity, not on tag
  259. # value or contents.
  260. #
  261. # @param element What element to remove.
  262. # @exception ValueError If a matching element could not be found.
  263. # @exception AssertionError If the element is not a valid object.
  264. def remove(self, element):
  265. assert iselement(element)
  266. self._children.remove(element)
  267. ##
  268. # Returns all subelements. The elements are returned in document
  269. # order.
  270. #
  271. # @return A list of subelements.
  272. # @defreturn list of Element instances
  273. def getchildren(self):
  274. return self._children
  275. ##
  276. # Finds the first matching subelement, by tag name or path.
  277. #
  278. # @param path What element to look for.
  279. # @return The first matching element, or None if no element was found.
  280. # @defreturn Element or None
  281. def find(self, path):
  282. return ElementPath.find(self, path)
  283. ##
  284. # Finds text for the first matching subelement, by tag name or path.
  285. #
  286. # @param path What element to look for.
  287. # @param default What to return if the element was not found.
  288. # @return The text content of the first matching element, or the
  289. # default value no element was found. Note that if the element
  290. # has is found, but has no text content, this method returns an
  291. # empty string.
  292. # @defreturn string
  293. def findtext(self, path, default=None):
  294. return ElementPath.findtext(self, path, default)
  295. ##
  296. # Finds all matching subelements, by tag name or path.
  297. #
  298. # @param path What element to look for.
  299. # @return A list or iterator containing all matching elements,
  300. # in document order.
  301. # @defreturn list of Element instances
  302. def findall(self, path):
  303. return ElementPath.findall(self, path)
  304. ##
  305. # Resets an element. This function removes all subelements, clears
  306. # all attributes, and sets the text and tail attributes to None.
  307. def clear(self):
  308. self.attrib.clear()
  309. self._children = []
  310. self.text = self.tail = None
  311. ##
  312. # Gets an element attribute.
  313. #
  314. # @param key What attribute to look for.
  315. # @param default What to return if the attribute was not found.
  316. # @return The attribute value, or the default value, if the
  317. # attribute was not found.
  318. # @defreturn string or None
  319. def get(self, key, default=None):
  320. return self.attrib.get(key, default)
  321. ##
  322. # Sets an element attribute.
  323. #
  324. # @param key What attribute to set.
  325. # @param value The attribute value.
  326. def set(self, key, value):
  327. self.attrib[key] = value
  328. ##
  329. # Gets a list of attribute names. The names are returned in an
  330. # arbitrary order (just like for an ordinary Python dictionary).
  331. #
  332. # @return A list of element attribute names.
  333. # @defreturn list of strings
  334. def keys(self):
  335. return self.attrib.keys()
  336. ##
  337. # Gets element attributes, as a sequence. The attributes are
  338. # returned in an arbitrary order.
  339. #
  340. # @return A list of (name, value) tuples for all attributes.
  341. # @defreturn list of (string, string) tuples
  342. def items(self):
  343. return self.attrib.items()
  344. ##
  345. # Creates a tree iterator. The iterator loops over this element
  346. # and all subelements, in document order, and returns all elements
  347. # with a matching tag.
  348. # <p>
  349. # If the tree structure is modified during iteration, the result
  350. # is undefined.
  351. #
  352. # @param tag What tags to look for (default is to return all elements).
  353. # @return A list or iterator containing all the matching elements.
  354. # @defreturn list or iterator
  355. def getiterator(self, tag=None):
  356. nodes = []
  357. if tag == "*":
  358. tag = None
  359. if tag is None or self.tag == tag:
  360. nodes.append(self)
  361. for node in self._children:
  362. nodes.extend(node.getiterator(tag))
  363. return nodes
  364. # compatibility
  365. _Element = _ElementInterface
  366. ##
  367. # Element factory. This function returns an object implementing the
  368. # standard Element interface. The exact class or type of that object
  369. # is implementation dependent, but it will always be compatible with
  370. # the {@link #_ElementInterface} class in this module.
  371. # <p>
  372. # The element name, attribute names, and attribute values can be
  373. # either 8-bit ASCII strings or Unicode strings.
  374. #
  375. # @param tag The element name.
  376. # @param attrib An optional dictionary, containing element attributes.
  377. # @param **extra Additional attributes, given as keyword arguments.
  378. # @return An element instance.
  379. # @defreturn Element
  380. def Element(tag, attrib={}, **extra):
  381. attrib = attrib.copy()
  382. attrib.update(extra)
  383. return _ElementInterface(tag, attrib)
  384. ##
  385. # Subelement factory. This function creates an element instance, and
  386. # appends it to an existing element.
  387. # <p>
  388. # The element name, attribute names, and attribute values can be
  389. # either 8-bit ASCII strings or Unicode strings.
  390. #
  391. # @param parent The parent element.
  392. # @param tag The subelement name.
  393. # @param attrib An optional dictionary, containing element attributes.
  394. # @param **extra Additional attributes, given as keyword arguments.
  395. # @return An element instance.
  396. # @defreturn Element
  397. def SubElement(parent, tag, attrib={}, **extra):
  398. attrib = attrib.copy()
  399. attrib.update(extra)
  400. element = parent.makeelement(tag, attrib)
  401. parent.append(element)
  402. return element
  403. ##
  404. # Comment element factory. This factory function creates a special
  405. # element that will be serialized as an XML comment.
  406. # <p>
  407. # The comment string can be either an 8-bit ASCII string or a Unicode
  408. # string.
  409. #
  410. # @param text A string containing the comment string.
  411. # @return An element instance, representing a comment.
  412. # @defreturn Element
  413. def Comment(text=None):
  414. element = Element(Comment)
  415. element.text = text
  416. return element
  417. ##
  418. # PI element factory. This factory function creates a special element
  419. # that will be serialized as an XML processing instruction.
  420. #
  421. # @param target A string containing the PI target.
  422. # @param text A string containing the PI contents, if any.
  423. # @return An element instance, representing a PI.
  424. # @defreturn Element
  425. def ProcessingInstruction(target, text=None):
  426. element = Element(ProcessingInstruction)
  427. element.text = target
  428. if text:
  429. element.text = element.text + " " + text
  430. return element
  431. PI = ProcessingInstruction
  432. ##
  433. # QName wrapper. This can be used to wrap a QName attribute value, in
  434. # order to get proper namespace handling on output.
  435. #
  436. # @param text A string containing the QName value, in the form {uri}local,
  437. # or, if the tag argument is given, the URI part of a QName.
  438. # @param tag Optional tag. If given, the first argument is interpreted as
  439. # an URI, and this argument is interpreted as a local name.
  440. # @return An opaque object, representing the QName.
  441. class QName:
  442. def __init__(self, text_or_uri, tag=None):
  443. if tag:
  444. text_or_uri = "{%s}%s" % (text_or_uri, tag)
  445. self.text = text_or_uri
  446. def __str__(self):
  447. return self.text
  448. def __hash__(self):
  449. return hash(self.text)
  450. def __cmp__(self, other):
  451. if isinstance(other, QName):
  452. return cmp(self.text, other.text)
  453. return cmp(self.text, other)
  454. ##
  455. # ElementTree wrapper class. This class represents an entire element
  456. # hierarchy, and adds some extra support for serialization to and from
  457. # standard XML.
  458. #
  459. # @param element Optional root element.
  460. # @keyparam file Optional file handle or name. If given, the
  461. # tree is initialized with the contents of this XML file.
  462. class ElementTree:
  463. def __init__(self, element=None, file=None):
  464. assert element is None or iselement(element)
  465. self._root = element # first node
  466. if file:
  467. self.parse(file)
  468. ##
  469. # Gets the root element for this tree.
  470. #
  471. # @return An element instance.
  472. # @defreturn Element
  473. def getroot(self):
  474. return self._root
  475. ##
  476. # Replaces the root element for this tree. This discards the
  477. # current contents of the tree, and replaces it with the given
  478. # element. Use with care.
  479. #
  480. # @param element An element instance.
  481. def _setroot(self, element):
  482. assert iselement(element)
  483. self._root = element
  484. ##
  485. # Loads an external XML document into this element tree.
  486. #
  487. # @param source A file name or file object.
  488. # @param parser An optional parser instance. If not given, the
  489. # standard {@link XMLTreeBuilder} parser is used.
  490. # @return The document root element.
  491. # @defreturn Element
  492. def parse(self, source, parser=None):
  493. if not hasattr(source, "read"):
  494. source = open(source, "rb")
  495. if not parser:
  496. parser = XMLTreeBuilder()
  497. while 1:
  498. data = source.read(32768)
  499. if not data:
  500. break
  501. parser.feed(data)
  502. self._root = parser.close()
  503. return self._root
  504. ##
  505. # Creates a tree iterator for the root element. The iterator loops
  506. # over all elements in this tree, in document order.
  507. #
  508. # @param tag What tags to look for (default is to return all elements)
  509. # @return An iterator.
  510. # @defreturn iterator
  511. def getiterator(self, tag=None):
  512. assert self._root is not None
  513. return self._root.getiterator(tag)
  514. ##
  515. # Finds the first toplevel element with given tag.
  516. # Same as getroot().find(path).
  517. #
  518. # @param path What element to look for.
  519. # @return The first matching element, or None if no element was found.
  520. # @defreturn Element or None
  521. def find(self, path):
  522. assert self._root is not None
  523. if path[:1] == "/":
  524. path = "." + path
  525. return self._root.find(path)
  526. ##
  527. # Finds the element text for the first toplevel element with given
  528. # tag. Same as getroot().findtext(path).
  529. #
  530. # @param path What toplevel element to look for.
  531. # @param default What to return if the element was not found.
  532. # @return The text content of the first matching element, or the
  533. # default value no element was found. Note that if the element
  534. # has is found, but has no text content, this method returns an
  535. # empty string.
  536. # @defreturn string
  537. def findtext(self, path, default=None):
  538. assert self._root is not None
  539. if path[:1] == "/":
  540. path = "." + path
  541. return self._root.findtext(path, default)
  542. ##
  543. # Finds all toplevel elements with the given tag.
  544. # Same as getroot().findall(path).
  545. #
  546. # @param path What element to look for.
  547. # @return A list or iterator containing all matching elements,
  548. # in document order.
  549. # @defreturn list of Element instances
  550. def findall(self, path):
  551. assert self._root is not None
  552. if path[:1] == "/":
  553. path = "." + path
  554. return self._root.findall(path)
  555. ##
  556. # Writes the element tree to a file, as XML.
  557. #
  558. # @param file A file name, or a file object opened for writing.
  559. # @param encoding Optional output encoding (default is US-ASCII).
  560. def write(self, file, encoding="us-ascii"):
  561. assert self._root is not None
  562. if not hasattr(file, "write"):
  563. file = open(file, "wb")
  564. if not encoding:
  565. encoding = "us-ascii"
  566. elif encoding != "utf-8" and encoding != "us-ascii":
  567. file.write("<?xml version='1.0' encoding='%s'?>\n" % encoding)
  568. self._write(file, self._root, encoding, {})
  569. def _write(self, file, node, encoding, namespaces):
  570. # write XML to file
  571. tag = node.tag
  572. if tag is Comment:
  573. file.write("<!-- %s -->" % _escape_cdata(node.text, encoding))
  574. elif tag is ProcessingInstruction:
  575. file.write("<?%s?>" % _escape_cdata(node.text, encoding))
  576. else:
  577. items = node.items()
  578. xmlns_items = [] # new namespaces in this scope
  579. try:
  580. if isinstance(tag, QName) or tag[:1] == "{":
  581. tag, xmlns = fixtag(tag, namespaces)
  582. if xmlns: xmlns_items.append(xmlns)
  583. except TypeError:
  584. _raise_serialization_error(tag)
  585. file.write("<" + _encode(tag, encoding))
  586. if items or xmlns_items:
  587. items.sort() # lexical order
  588. for k, v in items:
  589. try:
  590. if isinstance(k, QName) or k[:1] == "{":
  591. k, xmlns = fixtag(k, namespaces)
  592. if xmlns: xmlns_items.append(xmlns)
  593. except TypeError:
  594. _raise_serialization_error(k)
  595. try:
  596. if isinstance(v, QName):
  597. v, xmlns = fixtag(v, namespaces)
  598. if xmlns: xmlns_items.append(xmlns)
  599. except TypeError:
  600. _raise_serialization_error(v)
  601. file.write(" %s=\"%s\"" % (_encode(k, encoding),
  602. _escape_attrib(v, encoding)))
  603. for k, v in xmlns_items:
  604. file.write(" %s=\"%s\"" % (_encode(k, encoding),
  605. _escape_attrib(v, encoding)))
  606. if node.text or len(node):
  607. file.write(">")
  608. if node.text:
  609. file.write(_escape_cdata(node.text, encoding))
  610. for n in node:
  611. self._write(file, n, encoding, namespaces)
  612. file.write("</" + _encode(tag, encoding) + ">")
  613. else:
  614. file.write(" />")
  615. for k, v in xmlns_items:
  616. del namespaces[v]
  617. if node.tail:
  618. file.write(_escape_cdata(node.tail, encoding))
  619. # --------------------------------------------------------------------
  620. # helpers
  621. ##
  622. # Checks if an object appears to be a valid element object.
  623. #
  624. # @param An element instance.
  625. # @return A true value if this is an element object.
  626. # @defreturn flag
  627. def iselement(element):
  628. # FIXME: not sure about this; might be a better idea to look
  629. # for tag/attrib/text attributes
  630. return isinstance(element, _ElementInterface) or hasattr(element, "tag")
  631. ##
  632. # Writes an element tree or element structure to sys.stdout. This
  633. # function should be used for debugging only.
  634. # <p>
  635. # The exact output format is implementation dependent. In this
  636. # version, it's written as an ordinary XML file.
  637. #
  638. # @param elem An element tree or an individual element.
  639. def dump(elem):
  640. # debugging
  641. if not isinstance(elem, ElementTree):
  642. elem = ElementTree(elem)
  643. elem.write(sys.stdout)
  644. tail = elem.getroot().tail
  645. if not tail or tail[-1] != "\n":
  646. sys.stdout.write("\n")
  647. def _encode(s, encoding):
  648. try:
  649. return s.encode(encoding)
  650. except AttributeError:
  651. return s # 1.5.2: assume the string uses the right encoding
  652. if sys.version[:3] == "1.5":
  653. _escape = re.compile(r"[&<>\"\x80-\xff]+") # 1.5.2
  654. else:
  655. _escape = re.compile(eval(r'u"[&<>\"\u0080-\uffff]+"'))
  656. _escape_map = {
  657. "&": "&amp;",
  658. "<": "&lt;",
  659. ">": "&gt;",
  660. '"': "&quot;",
  661. }
  662. _namespace_map = {
  663. # "well-known" namespace prefixes
  664. "http://www.w3.org/XML/1998/namespace": "xml",
  665. "http://www.w3.org/1999/xhtml": "html",
  666. "http://www.w3.org/1999/02/22-rdf-syntax-ns#": "rdf",
  667. "http://schemas.xmlsoap.org/wsdl/": "wsdl",
  668. }
  669. def _raise_serialization_error(text):
  670. raise TypeError(
  671. "cannot serialize %r (type %s)" % (text, type(text).__name__)
  672. )
  673. def _encode_entity(text, pattern=_escape):
  674. # map reserved and non-ascii characters to numerical entities
  675. def escape_entities(m, map=_escape_map):
  676. out = []
  677. append = out.append
  678. for char in m.group():
  679. text = map.get(char)
  680. if text is None:
  681. text = "&#%d;" % ord(char)
  682. append(text)
  683. return string.join(out, "")
  684. try:
  685. return _encode(pattern.sub(escape_entities, text), "ascii")
  686. except TypeError:
  687. _raise_serialization_error(text)
  688. #
  689. # the following functions assume an ascii-compatible encoding
  690. # (or "utf-16")
  691. def _escape_cdata(text, encoding=None, replace=string.replace):
  692. # escape character data
  693. try:
  694. if encoding:
  695. try:
  696. text = _encode(text, encoding)
  697. except UnicodeError:
  698. return _encode_entity(text)
  699. text = replace(text, "&", "&amp;")
  700. text = replace(text, "<", "&lt;")
  701. text = replace(text, ">", "&gt;")
  702. return text
  703. except (TypeError, AttributeError):
  704. _raise_serialization_error(text)
  705. def _escape_attrib(text, encoding=None, replace=string.replace):
  706. # escape attribute value
  707. try:
  708. if encoding:
  709. try:
  710. text = _encode(text, encoding)
  711. except UnicodeError:
  712. return _encode_entity(text)
  713. text = replace(text, "&", "&amp;")
  714. text = replace(text, "'", "&apos;") # FIXME: overkill
  715. text = replace(text, "\"", "&quot;")
  716. text = replace(text, "<", "&lt;")
  717. text = replace(text, ">", "&gt;")
  718. return text
  719. except (TypeError, AttributeError):
  720. _raise_serialization_error(text)
  721. def fixtag(tag, namespaces):
  722. # given a decorated tag (of the form {uri}tag), return prefixed
  723. # tag and namespace declaration, if any
  724. if isinstance(tag, QName):
  725. tag = tag.text
  726. namespace_uri, tag = string.split(tag[1:], "}", 1)
  727. prefix = namespaces.get(namespace_uri)
  728. if prefix is None:
  729. prefix = _namespace_map.get(namespace_uri)
  730. if prefix is None:
  731. prefix = "ns%d" % len(namespaces)
  732. namespaces[namespace_uri] = prefix
  733. if prefix == "xml":
  734. xmlns = None
  735. else:
  736. xmlns = ("xmlns:%s" % prefix, namespace_uri)
  737. else:
  738. xmlns = None
  739. return "%s:%s" % (prefix, tag), xmlns
  740. ##
  741. # Parses an XML document into an element tree.
  742. #
  743. # @param source A filename or file object containing XML data.
  744. # @param parser An optional parser instance. If not given, the
  745. # standard {@link XMLTreeBuilder} parser is used.
  746. # @return An ElementTree instance
  747. def parse(source, parser=None):
  748. tree = ElementTree()
  749. tree.parse(source, parser)
  750. return tree
  751. ##
  752. # Parses an XML document into an element tree incrementally, and reports
  753. # what's going on to the user.
  754. #
  755. # @param source A filename or file object containing XML data.
  756. # @param events A list of events to report back. If omitted, only "end"
  757. # events are reported.
  758. # @return A (event, elem) iterator.
  759. class iterparse:
  760. def __init__(self, source, events=None):
  761. if not hasattr(source, "read"):
  762. source = open(source, "rb")
  763. self._file = source
  764. self._events = []
  765. self._index = 0
  766. self.root = self._root = None
  767. self._parser = XMLTreeBuilder()
  768. # wire up the parser for event reporting
  769. parser = self._parser._parser
  770. append = self._events.append
  771. if events is None:
  772. events = ["end"]
  773. for event in events:
  774. if event == "start":
  775. try:
  776. parser.ordered_attributes = 1
  777. parser.specified_attributes = 1
  778. def handler(tag, attrib_in, event=event, append=append,
  779. start=self._parser._start_list):
  780. append((event, start(tag, attrib_in)))
  781. parser.StartElementHandler = handler
  782. except AttributeError:
  783. def handler(tag, attrib_in, event=event, append=append,
  784. start=self._parser._start):
  785. append((event, start(tag, attrib_in)))
  786. parser.StartElementHandler = handler
  787. elif event == "end":
  788. def handler(tag, event=event, append=append,
  789. end=self._parser._end):
  790. append((event, end(tag)))
  791. parser.EndElementHandler = handler
  792. elif event == "start-ns":
  793. def handler(prefix, uri, event=event, append=append):
  794. try:
  795. uri = _encode(uri, "ascii")
  796. except UnicodeError:
  797. pass
  798. append((event, (prefix or "", uri)))
  799. parser.StartNamespaceDeclHandler = handler
  800. elif event == "end-ns":
  801. def handler(prefix, event=event, append=append):
  802. append((event, None))
  803. parser.EndNamespaceDeclHandler = handler
  804. def next(self):
  805. while 1:
  806. try:
  807. item = self._events[self._index]
  808. except IndexError:
  809. if self._parser is None:
  810. self.root = self._root
  811. try:
  812. raise StopIteration
  813. except NameError:
  814. raise IndexError
  815. # load event buffer
  816. del self._events[:]
  817. self._index = 0
  818. data = self._file.read(16384)
  819. if data:
  820. self._parser.feed(data)
  821. else:
  822. self._root = self._parser.close()
  823. self._parser = None
  824. else:
  825. self._index = self._index + 1
  826. return item
  827. try:
  828. iter
  829. def __iter__(self):
  830. return self
  831. except NameError:
  832. def __getitem__(self, index):
  833. return self.next()
  834. ##
  835. # Parses an XML document from a string constant. This function can
  836. # be used to embed "XML literals" in Python code.
  837. #
  838. # @param source A string containing XML data.
  839. # @return An Element instance.
  840. # @defreturn Element
  841. def XML(text):
  842. parser = XMLTreeBuilder()
  843. parser.feed(text)
  844. return parser.close()
  845. ##
  846. # Parses an XML document from a string constant, and also returns
  847. # a dictionary which maps from element id:s to elements.
  848. #
  849. # @param source A string containing XML data.
  850. # @return A tuple containing an Element instance and a dictionary.
  851. # @defreturn (Element, dictionary)
  852. def XMLID(text):
  853. parser = XMLTreeBuilder()
  854. parser.feed(text)
  855. tree = parser.close()
  856. ids = {}
  857. for elem in tree.getiterator():
  858. id = elem.get("id")
  859. if id:
  860. ids[id] = elem
  861. return tree, ids
  862. ##
  863. # Parses an XML document from a string constant. Same as {@link #XML}.
  864. #
  865. # @def fromstring(text)
  866. # @param source A string containing XML data.
  867. # @return An Element instance.
  868. # @defreturn Element
  869. fromstring = XML
  870. ##
  871. # Generates a string representation of an XML element, including all
  872. # subelements.
  873. #
  874. # @param element An Element instance.
  875. # @return An encoded string containing the XML data.
  876. # @defreturn string
  877. def tostring(element, encoding=None):
  878. class dummy:
  879. pass
  880. data = []
  881. file = dummy()
  882. file.write = data.append
  883. ElementTree(element).write(file, encoding)
  884. return string.join(data, "")
  885. ##
  886. # Generic element structure builder. This builder converts a sequence
  887. # of {@link #TreeBuilder.start}, {@link #TreeBuilder.data}, and {@link
  888. # #TreeBuilder.end} method calls to a well-formed element structure.
  889. # <p>
  890. # You can use this class to build an element structure using a custom XML
  891. # parser, or a parser for some other XML-like format.
  892. #
  893. # @param element_factory Optional element factory. This factory
  894. # is called to create new Element instances, as necessary.
  895. class TreeBuilder:
  896. def __init__(self, element_factory=None):
  897. self._data = [] # data collector
  898. self._elem = [] # element stack
  899. self._last = None # last element
  900. self._tail = None # true if we're after an end tag
  901. if element_factory is None:
  902. element_factory = _ElementInterface
  903. self._factory = element_factory
  904. ##
  905. # Flushes the parser buffers, and returns the toplevel documen
  906. # element.
  907. #
  908. # @return An Element instance.
  909. # @defreturn Element
  910. def close(self):
  911. assert len(self._elem) == 0, "missing end tags"
  912. assert self._last != None, "missing toplevel element"
  913. return self._last
  914. def _flush(self):
  915. if self._data:
  916. if self._last is not None:
  917. text = string.join(self._data, "")
  918. if self._tail:
  919. assert self._last.tail is None, "internal error (tail)"
  920. self._last.tail = text
  921. else:
  922. assert self._last.text is None, "internal error (text)"
  923. self._last.text = text
  924. self._data = []
  925. ##
  926. # Adds text to the current element.
  927. #
  928. # @param data A string. This should be either an 8-bit string
  929. # containing ASCII text, or a Unicode string.
  930. def data(self, data):
  931. self._data.append(data)
  932. ##
  933. # Opens a new element.
  934. #
  935. # @param tag The element name.
  936. # @param attrib A dictionary containing element attributes.
  937. # @return The opened element.
  938. # @defreturn Element
  939. def start(self, tag, attrs):
  940. self._flush()
  941. self._last = elem = self._factory(tag, attrs)
  942. if self._elem:
  943. self._elem[-1].append(elem)
  944. self._elem.append(elem)
  945. self._tail = 0
  946. return elem
  947. ##
  948. # Closes the current element.
  949. #
  950. # @param tag The element name.
  951. # @return The closed element.
  952. # @defreturn Element
  953. def end(self, tag):
  954. self._flush()
  955. self._last = self._elem.pop()
  956. assert self._last.tag == tag,\
  957. "end tag mismatch (expected %s, got %s)" % (
  958. self._last.tag, tag)
  959. self._tail = 1
  960. return self._last
  961. ##
  962. # Element structure builder for XML source data, based on the
  963. # <b>expat</b> parser.
  964. #
  965. # @keyparam target Target object. If omitted, the builder uses an
  966. # instance of the standard {@link #TreeBuilder} class.
  967. # @keyparam html Predefine HTML entities. This flag is not supported
  968. # by the current implementation.
  969. # @see #ElementTree
  970. # @see #TreeBuilder
  971. class XMLTreeBuilder:
  972. def __init__(self, html=0, target=None):
  973. try:
  974. from xml.parsers import expat
  975. except ImportError:
  976. raise ImportError(
  977. "No module named expat; use SimpleXMLTreeBuilder instead"
  978. )
  979. self._parser = parser = expat.ParserCreate(None, "}")
  980. if target is None:
  981. target = TreeBuilder()
  982. self._target = target
  983. self._names = {} # name memo cache
  984. # callbacks
  985. parser.DefaultHandlerExpand = self._default
  986. parser.StartElementHandler = self._start
  987. parser.EndElementHandler = self._end
  988. parser.CharacterDataHandler = self._data
  989. # let expat do the buffering, if supported
  990. try:
  991. self._parser.buffer_text = 1
  992. except AttributeError:
  993. pass
  994. # use new-style attribute handling, if supported
  995. try:
  996. self._parser.ordered_attributes = 1
  997. self._parser.specified_attributes = 1
  998. parser.StartElementHandler = self._start_list
  999. except AttributeError:
  1000. pass
  1001. encoding = None
  1002. if not parser.returns_unicode:
  1003. encoding = "utf-8"
  1004. # target.xml(encoding, None)
  1005. self._doctype = None
  1006. self.entity = {}
  1007. def _fixtext(self, text):
  1008. # convert text string to ascii, if possible
  1009. try:
  1010. return _encode(text, "ascii")
  1011. except UnicodeError:
  1012. return text
  1013. def _fixname(self, key):
  1014. # expand qname, and convert name string to ascii, if possible
  1015. try:
  1016. name = self._names[key]
  1017. except KeyError:
  1018. name = key
  1019. if "}" in name:
  1020. name = "{" + name
  1021. self._names[key] = name = self._fixtext(name)
  1022. return name
  1023. def _start(self, tag, attrib_in):
  1024. fixname = self._fixname
  1025. tag = fixname(tag)
  1026. attrib = {}
  1027. for key, value in attrib_in.items():
  1028. attrib[fixname(key)] = self._fixtext(value)
  1029. return self._target.start(tag, attrib)
  1030. def _start_list(self, tag, attrib_in):
  1031. fixname = self._fixname
  1032. tag = fixname(tag)
  1033. attrib = {}
  1034. if attrib_in:
  1035. for i in range(0, len(attrib_in), 2):
  1036. attrib[fixname(attrib_in[i])] = self._fixtext(attrib_in[i+1])
  1037. return self._target.start(tag, attrib)
  1038. def _data(self, text):
  1039. return self._target.data(self._fixtext(text))
  1040. def _end(self, tag):
  1041. return self._target.end(self._fixname(tag))
  1042. def _default(self, text):
  1043. prefix = text[:1]
  1044. if prefix == "&":
  1045. # deal with undefined entities
  1046. try:
  1047. self._target.data(self.entity[text[1:-1]])
  1048. except KeyError:
  1049. from xml.parsers import expat
  1050. raise expat.error(
  1051. "undefined entity %s: line %d, column %d" %
  1052. (text, self._parser.ErrorLineNumber,
  1053. self._parser.ErrorColumnNumber)
  1054. )
  1055. elif prefix == "<" and text[:9] == "<!DOCTYPE":
  1056. self._doctype = [] # inside a doctype declaration
  1057. elif self._doctype is not None:
  1058. # parse doctype contents
  1059. if prefix == ">":
  1060. self._doctype = None
  1061. return
  1062. text = string.strip(text)
  1063. if not text:
  1064. return
  1065. self._doctype.append(text)
  1066. n = len(self._doctype)
  1067. if n > 2:
  1068. type = self._doctype[1]
  1069. if type == "PUBLIC" and n == 4:
  1070. name, type, pubid, system = self._doctype
  1071. elif type == "SYSTEM" and n == 3:
  1072. name, type, system = self._doctype
  1073. pubid = None
  1074. else:
  1075. return
  1076. if pubid:
  1077. pubid = pubid[1:-1]
  1078. self.doctype(name, pubid, system[1:-1])
  1079. self._doctype = None
  1080. ##
  1081. # Handles a doctype declaration.
  1082. #
  1083. # @param name Doctype name.
  1084. # @param pubid Public identifier.
  1085. # @param system System identifier.
  1086. def doctype(self, name, pubid, system):
  1087. pass
  1088. ##
  1089. # Feeds data to the parser.
  1090. #
  1091. # @param data Encoded data.
  1092. def feed(self, data):
  1093. self._parser.Parse(data, 0)
  1094. ##
  1095. # Finishes feeding data to the parser.
  1096. #
  1097. # @return An element structure.
  1098. # @defreturn Element
  1099. def close(self):
  1100. self._parser.Parse("", 1) # end of data
  1101. tree = self._target.close()
  1102. del self._target, self._parser # get rid of circular references
  1103. return tree