nbxmpp.simplexml

1 ## simplexml.py based on Mattew Allum's xmlstream.py 2 ## 3 ## Copyright (C) 2003-2005 Alexey "Snake" Nezhdanov 4 ## 5 ## This program is free software; you can redistribute it and/or modify 6 ## it under the terms of the GNU General Public License as published by 7 ## the Free Software Foundation; either version 2, or (at your option) 8 ## any later version. 9 ## 10 ## This program is distributed in the hope that it will be useful, 11 ## but WITHOUT ANY WARRANTY; without even the implied warranty of 12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 ## GNU General Public License for more details. 14 15 # $Id: simplexml.py,v 1.27 2005/04/30 07:20:27 snakeru Exp $ 16 17 """ 18 Simplexml module provides xmpppy library with all needed tools to handle XML 19 nodes and XML streams. I'm personally using it in many other separate 20 projects. It is designed to be as standalone as possible 21 """ 22 23 import xml.parsers.expat 24 import logging 25 log = logging.getLogger('nbxmpp.simplexml') 26

27 -def XMLescape(txt):

28 """ 29 Return provided string with symbols & < > " replaced by their respective XML 30 entities 31 """ 32 # replace also FORM FEED and ESC, because they are not valid XML chars 33 return txt.replace("&", "&").replace("<", "<").replace(">", ">").replace('"', """).replace(u'\x0C', "").replace(u'\x1B', "")

34 35 ENCODING='utf-8' 36

37 -def ustr(what):

38 """ 39 Converts object "what" to unicode string using it's own __str__ method if 40 accessible or unicode method otherwise 41 """ 42 if isinstance(what, unicode): 43 return what 44 try: 45 r = what.__str__() 46 except AttributeError: 47 r = str(what) 48 if not isinstance(r, unicode): 49 return unicode(r, ENCODING) 50 return r

51

52 -class Node(object):

53 """ 54 Node class describes syntax of separate XML Node. It have a constructor that 55 permits node creation from set of "namespace name", attributes and payload 56 of text strings and other nodes. It does not natively support building node 57 from text string and uses NodeBuilder class for that purpose. After 58 creation node can be mangled in many ways so it can be completely changed. 59 Also node can be serialised into string in one of two modes: default (where 60 the textual representation of node describes it exactly) and "fancy" - with 61 whitespace added to make indentation and thus make result more readable by 62 human. 63 64 Node class have attribute FORCE_NODE_RECREATION that is defaults to False 65 thus enabling fast node replication from the some other node. The drawback 66 of the fast way is that new node shares some info with the "original" node 67 that is changing the one node may influence the other. Though it is rarely 68 needed (in xmpppy it is never needed at all since I'm usually never using 69 original node after replication (and using replication only to move upwards 70 on the classes tree). 71 """ 72 73 FORCE_NODE_RECREATION = 0 74

75 - def __init__(self, tag=None, attrs={}, payload=[], parent=None, nsp=None, 76 node_built=False, node=None):

77 """ 78 Takes "tag" argument as the name of node (prepended by namespace, if 79 needed and separated from it by a space), attrs dictionary as the set of 80 arguments, payload list as the set of textual strings and child nodes 81 that this node carries within itself and "parent" argument that is 82 another node that this one will be the child of. Also the __init__ can be 83 provided with "node" argument that is either a text string containing 84 exactly one node or another Node instance to begin with. If both "node" 85 and other arguments is provided then the node initially created as 86 replica of "node" provided and then modified to be compliant with other 87 arguments. 88 """ 89 if node: 90 if self.FORCE_NODE_RECREATION and isinstance(node, Node): 91 node = str(node) 92 if not isinstance(node, Node): 93 node = NodeBuilder(node, self) 94 node_built = True 95 else: 96 self.name, self.namespace, self.attrs, self.data, self.kids, self.parent, self.nsd = node.name, node.namespace, {}, [], [], node.parent, {} 97 for key in node.attrs.keys(): 98 self.attrs[key] = node.attrs[key] 99 for data in node.data: 100 self.data.append(data) 101 for kid in node.kids: 102 self.kids.append(kid) 103 for k, v in node.nsd.items(): 104 self.nsd[k] = v 105 else: 106 self.name, self.namespace, self.attrs, self.data, self.kids, self.parent, self.nsd = 'tag', '', {}, [], [], None, {} 107 if parent: 108 self.parent = parent 109 self.nsp_cache = {} 110 if nsp: 111 for k, v in nsp.items(): self.nsp_cache[k] = v 112 for attr, val in attrs.items(): 113 if attr == 'xmlns': 114 self.nsd[u''] = val 115 elif attr.startswith('xmlns:'): 116 self.nsd[attr[6:]] = val 117 self.attrs[attr]=attrs[attr] 118 if tag: 119 if node_built: 120 pfx, self.name = (['']+tag.split(':'))[-2:] 121 self.namespace = self.lookup_nsp(pfx) 122 else: 123 if ' ' in tag: 124 self.namespace, self.name = tag.split() 125 else: 126 self.name = tag 127 if isinstance(payload, basestring): payload=[payload] 128 for i in payload: 129 if isinstance(i, Node): 130 self.addChild(node=i) 131 else: 132 self.data.append(ustr(i))

133

134 - def lookup_nsp(self, pfx=''):

135 ns = self.nsd.get(pfx, None) 136 if ns is None: 137 ns = self.nsp_cache.get(pfx, None) 138 if ns is None: 139 if self.parent: 140 ns = self.parent.lookup_nsp(pfx) 141 self.nsp_cache[pfx] = ns 142 else: 143 return 'http://www.gajim.org/xmlns/undeclared' 144 return ns

145

146 - def __str__(self, fancy=0):

147 """ 148 Method used to dump node into textual representation. If "fancy" argument 149 is set to True produces indented output for readability 150 """ 151 s = (fancy-1) * 2 * ' ' + "<" + self.name 152 if self.namespace: 153 if not self.parent or self.parent.namespace!=self.namespace: 154 if 'xmlns' not in self.attrs: 155 s = s + ' xmlns="%s"'%self.namespace 156 for key in self.attrs.keys(): 157 val = ustr(self.attrs[key]) 158 s = s + ' %s="%s"' % ( key, XMLescape(val) ) 159 s = s + ">" 160 cnt = 0 161 if self.kids: 162 if fancy: s = s + "\n" 163 for a in self.kids: 164 if not fancy and (len(self.data)-1)>=cnt: s=s+XMLescape(self.data[cnt]) 165 elif (len(self.data)-1)>=cnt: s=s+XMLescape(self.data[cnt].strip()) 166 if isinstance(a, str) or isinstance(a, unicode): 167 s = s + a.__str__() 168 else: 169 s = s + a.__str__(fancy and fancy+1) 170 cnt=cnt+1 171 if not fancy and (len(self.data)-1) >= cnt: s = s + XMLescape(self.data[cnt]) 172 elif (len(self.data)-1) >= cnt: s = s + XMLescape(self.data[cnt].strip()) 173 if not self.kids and s.endswith('>'): 174 s=s[:-1]+' />' 175 if fancy: s = s + "\n" 176 else: 177 if fancy and not self.data: s = s + (fancy-1) * 2 * ' ' 178 s = s + "</" + self.name + ">" 179 if fancy: s = s + "\n" 180 return s

181

182 - def addChild(self, name=None, attrs={}, payload=[], namespace=None, node=None):

183 """ 184 If "node" argument is provided, adds it as child node. Else creates new 185 node from the other arguments' values and adds it as well 186 """ 187 if 'xmlns' in attrs: 188 raise AttributeError("Use namespace=x instead of attrs={'xmlns':x}") 189 if node: 190 newnode=node 191 node.parent = self 192 else: newnode=Node(tag=name, parent=self, attrs=attrs, payload=payload) 193 if namespace: 194 newnode.setNamespace(namespace) 195 self.kids.append(newnode) 196 return newnode

197

198 - def addData(self, data):

199 """ 200 Add some CDATA to node 201 """ 202 self.data.append(ustr(data))

203

204 - def clearData(self):

205 """ 206 Remove all CDATA from the node 207 """ 208 self.data = []

209

210 - def delAttr(self, key):

211 """ 212 Delete an attribute "key" 213 """ 214 del self.attrs[key]

215

216 - def delChild(self, node, attrs={}):

217 """ 218 Delete the "node" from the node's childs list, if "node" is an instance. 219 Else delete the first node that have specified name and (optionally) 220 attributes 221 """ 222 if not isinstance(node, Node): 223 node = self.getTag(node, attrs) 224 self.kids.remove(node) 225 return node

226

227 - def getAttrs(self):

228 """ 229 Return all node's attributes as dictionary 230 """ 231 return self.attrs

232

233 - def getAttr(self, key):

234 """ 235 Return value of specified attribute 236 """ 237 return self.attrs.get(key)

238

239 - def getChildren(self):

240 """ 241 Return all node's child nodes as list 242 """ 243 return self.kids

244

245 - def getData(self):

246 """ 247 Return all node CDATA as string (concatenated) 248 """ 249 return ''.join(self.data)

250

251 - def getName(self):

252 """ 253 Return the name of node 254 """ 255 return self.name

256

257 - def getNamespace(self):

258 """ 259 Return the namespace of node 260 """ 261 return self.namespace

262

263 - def getParent(self):

264 """ 265 Returns the parent of node (if present) 266 """ 267 return self.parent

268

269 - def getPayload(self):

270 """ 271 Return the payload of node i.e. list of child nodes and CDATA entries. 272 F.e. for "<node>text1<nodea/><nodeb/> text2</node>" will be returned 273 list: ['text1', <nodea instance>, <nodeb instance>, ' text2'] 274 """ 275 ret = [] 276 for i in range(len(self.kids)+len(self.data)+1): 277 try: 278 if self.data[i]: 279 ret.append(self.data[i]) 280 except IndexError: 281 pass 282 try: 283 ret.append(self.kids[i]) 284 except IndexError: 285 pass 286 return ret

287

288 - def getTag(self, name, attrs={}, namespace=None):

289 """ 290 Filter all child nodes using specified arguments as filter. Return the 291 first found or None if not found 292 """ 293 return self.getTags(name, attrs, namespace, one=1)

294

295 - def getTagAttr(self, tag, attr):

296 """ 297 Return attribute value of the child with specified name (or None if no 298 such attribute) 299 """ 300 try: 301 return self.getTag(tag).attrs[attr] 302 except: 303 return None

304

305 - def getTagData(self, tag):

306 """ 307 Return cocatenated CDATA of the child with specified name 308 """ 309 try: 310 return self.getTag(tag).getData() 311 except Exception: 312 return None

313

314 - def getTags(self, name, attrs={}, namespace=None, one=0):

315 """ 316 Filter all child nodes using specified arguments as filter. Returns the 317 list of nodes found 318 """ 319 nodes = [] 320 for node in self.kids: 321 if namespace and namespace != node.getNamespace(): 322 continue 323 if node.getName() == name: 324 for key in attrs.keys(): 325 if key not in node.attrs or node.attrs[key]!=attrs[key]: 326 break 327 else: 328 nodes.append(node) 329 if one and nodes: 330 return nodes[0] 331 if not one: 332 return nodes

333

334 - def iterTags(self, name, attrs={}, namespace=None):

335 """ 336 Iterate over all children using specified arguments as filter 337 """ 338 for node in self.kids: 339 if namespace is not None and namespace != node.getNamespace(): 340 continue 341 if node.getName() == name: 342 for key in attrs.keys(): 343 if key not in node.attrs or \ 344 node.attrs[key]!=attrs[key]: 345 break 346 else: 347 yield node

348

349 - def setAttr(self, key, val):

350 """ 351 Set attribute "key" with the value "val" 352 """ 353 self.attrs[key] = val

354

355 - def setData(self, data):

356 """ 357 Set node's CDATA to provided string. Resets all previous CDATA! 358 """ 359 self.data = [ustr(data)]

360

361 - def setName(self, val):

362 """ 363 Change the node name 364 """ 365 self.name = val

366

367 - def setNamespace(self, namespace):

368 """ 369 Changes the node namespace 370 """ 371 self.namespace = namespace

372

373 - def setParent(self, node):

374 """ 375 Set node's parent to "node". WARNING: do not checks if the parent already 376 present and not removes the node from the list of childs of previous 377 parent 378 """ 379 self.parent = node

380

381 - def setPayload(self, payload, add=0):

382 """ 383 Set node payload according to the list specified. WARNING: completely 384 replaces all node's previous content. If you wish just to add child or 385 CDATA - use addData or addChild methods 386 """ 387 if isinstance(payload, basestring): 388 payload = [payload] 389 if add: 390 self.kids += payload 391 else: 392 self.kids = payload

393

394 - def setTag(self, name, attrs={}, namespace=None):

395 """ 396 Same as getTag but if the node with specified namespace/attributes not 397 found, creates such node and returns it 398 """ 399 node = self.getTags(name, attrs, namespace=namespace, one=1) 400 if node: 401 return node 402 else: 403 return self.addChild(name, attrs, namespace=namespace)

404

405 - def setTagAttr(self, tag, attr, val):

406 """ 407 Create new node (if not already present) with name "tag" and set it's 408 attribute "attr" to value "val" 409 """ 410 try: 411 self.getTag(tag).attrs[attr] = val 412 except Exception: 413 self.addChild(tag, attrs={attr: val})

414

415 - def setTagData(self, tag, val, attrs={}):

416 """ 417 Creates new node (if not already present) with name "tag" and 418 (optionally) attributes "attrs" and sets it's CDATA to string "val" 419 """ 420 try: 421 self.getTag(tag, attrs).setData(ustr(val)) 422 except Exception: 423 self.addChild(tag, attrs, payload = [ustr(val)])

424

425 - def has_attr(self, key):

426 """ 427 Check if node have attribute "key" 428 """ 429 return key in self.attrs

430

431 - def __getitem__(self, item):

432 """ 433 Return node's attribute "item" value 434 """ 435 return self.getAttr(item)

436

437 - def __setitem__(self, item, val):

438 """ 439 Set node's attribute "item" value 440 """ 441 return self.setAttr(item, val)

442

443 - def __delitem__(self, item):

444 """ 445 Delete node's attribute "item" 446 """ 447 return self.delAttr(item)

448

449 - def __contains__(self, item):

450 """ 451 Check if node has attribute "item" 452 """ 453 return self.has_attr(item)

454

455 - def __getattr__(self, attr):

456 """ 457 Reduce memory usage caused by T/NT classes - use memory only when needed 458 """ 459 if attr == 'T': 460 self.T = T(self) 461 return self.T 462 if attr == 'NT': 463 self.NT = NT(self) 464 return self.NT 465 raise AttributeError

466

467 -class T:

468 """ 469 Auxiliary class used to quick access to node's child nodes 470 """ 471

472 - def __init__(self, node):

473 self.__dict__['node'] = node

474

475 - def __getattr__(self, attr):

476 return self.node.setTag(attr)

477

478 - def __setattr__(self, attr, val):

479 if isinstance(val, Node): 480 Node.__init__(self.node.setTag(attr), node=val) 481 else: 482 return self.node.setTagData(attr, val)

483

484 - def __delattr__(self, attr):

485 return self.node.delChild(attr)

486

487 -class NT(T):

488 """ 489 Auxiliary class used to quick create node's child nodes 490 """ 491

492 - def __getattr__(self, attr):

493 return self.node.addChild(attr)

494

495 - def __setattr__(self, attr, val):

496 if isinstance(val, Node): 497 self.node.addChild(attr, node=val) 498 else: 499 return self.node.addChild(attr, payload=[val])

500

501 -class NodeBuilder:

502 """ 503 Builds a Node class minidom from data parsed to it. This class used for two 504 purposes: 505 506 1. Creation an XML Node from a textual representation. F.e. reading a 507 config file. See an XML2Node method. 508 2. Handling an incoming XML stream. This is done by mangling the 509 __dispatch_depth parameter and redefining the dispatch method. 510 511 You do not need to use this class directly if you do not designing your own 512 XML handler 513 """ 514

515 - def __init__(self, data=None, initial_node=None):

516 """ 517 Take two optional parameters: "data" and "initial_node" 518 519 By default class initialised with empty Node class instance. Though, if 520 "initial_node" is provided it used as "starting point". You can think 521 about it as of "node upgrade". "data" (if provided) feeded to parser 522 immidiatedly after instance init. 523 """ 524 log.debug("Preparing to handle incoming XML stream.") 525 self._parser = xml.parsers.expat.ParserCreate() 526 self._parser.StartElementHandler = self.starttag 527 self._parser.EndElementHandler = self.endtag 528 self._parser.StartNamespaceDeclHandler = self.handle_namespace_start 529 self._parser.CharacterDataHandler = self.handle_cdata 530 self._parser.buffer_text = True 531 self.Parse = self._parser.Parse 532 533 self.__depth = 0 534 self.__last_depth = 0 535 self.__max_depth = 0 536 self._dispatch_depth = 1 537 self._document_attrs = None 538 self._document_nsp = None 539 self._mini_dom=initial_node 540 self.last_is_data = 1 541 self._ptr=None 542 self.data_buffer = None 543 self.streamError = '' 544 if data: 545 self._parser.Parse(data, 1)

546

547 - def check_data_buffer(self):

548 if self.data_buffer: 549 self._ptr.data.append(''.join(self.data_buffer)) 550 del self.data_buffer[:] 551 self.data_buffer = None

552

553 - def destroy(self):

554 """ 555 Method used to allow class instance to be garbage-collected 556 """ 557 self.check_data_buffer() 558 self._parser.StartElementHandler = None 559 self._parser.EndElementHandler = None 560 self._parser.CharacterDataHandler = None 561 self._parser.StartNamespaceDeclHandler = None

562

563 - def starttag(self, tag, attrs):

564 """ 565 XML Parser callback. Used internally 566 """ 567 self.check_data_buffer() 568 self._inc_depth() 569 log.info("STARTTAG.. DEPTH -> %i , tag -> %s, attrs -> %s" % (self.__depth, tag, `attrs`)) 570 if self.__depth == self._dispatch_depth: 571 if not self._mini_dom : 572 self._mini_dom = Node(tag=tag, attrs=attrs, nsp = self._document_nsp, node_built=True) 573 else: 574 Node.__init__(self._mini_dom, tag=tag, attrs=attrs, nsp = self._document_nsp, node_built=True) 575 self._ptr = self._mini_dom 576 elif self.__depth > self._dispatch_depth: 577 self._ptr.kids.append(Node(tag=tag, parent=self._ptr, attrs=attrs, node_built=True)) 578 self._ptr = self._ptr.kids[-1] 579 if self.__depth == 1: 580 self._document_attrs = {} 581 self._document_nsp = {} 582 nsp, name = (['']+tag.split(':'))[-2:] 583 for attr, val in attrs.items(): 584 if attr == 'xmlns': 585 self._document_nsp[u''] = val 586 elif attr.startswith('xmlns:'): 587 self._document_nsp[attr[6:]] = val 588 else: 589 self._document_attrs[attr] = val 590 ns = self._document_nsp.get(nsp, 'http://www.gajim.org/xmlns/undeclared-root') 591 try: 592 self.stream_header_received(ns, name, attrs) 593 except ValueError, e: 594 self._document_attrs = None 595 raise ValueError(str(e)) 596 if not self.last_is_data and self._ptr.parent: 597 self._ptr.parent.data.append('') 598 self.last_is_data = 0

599

600 - def endtag(self, tag ):

601 """ 602 XML Parser callback. Used internally 603 """ 604 log.info("DEPTH -> %i , tag -> %s" % (self.__depth, tag)) 605 self.check_data_buffer() 606 if self.__depth == self._dispatch_depth: 607 if self._mini_dom.getName() == 'error': 608 children = self._mini_dom.getChildren() 609 if children: 610 self.streamError = children[0].getName() 611 else: 612 self.streamError = self._mini_dom.getData() 613 self.dispatch(self._mini_dom) 614 elif self.__depth > self._dispatch_depth: 615 self._ptr = self._ptr.parent 616 else: 617 log.info("Got higher than dispatch level. Stream terminated?") 618 self._dec_depth() 619 self.last_is_data = 0 620 if self.__depth == 0: self.stream_footer_received()

621

622 - def handle_cdata(self, data):

623 if self.last_is_data: 624 if self.data_buffer: 625 self.data_buffer.append(data) 626 elif self._ptr: 627 self.data_buffer = [data] 628 self.last_is_data = 1

629

630 - def handle_namespace_start(self, prefix, uri):

631 """ 632 XML Parser callback. Used internally 633 """ 634 self.check_data_buffer()

635

636 - def getDom(self):

637 """ 638 Return just built Node 639 """ 640 self.check_data_buffer() 641 return self._mini_dom

642

643 - def dispatch(self, stanza):

644 """ 645 Get called when the NodeBuilder reaches some level of depth on it's way 646 up with the built node as argument. Can be redefined to convert incoming 647 XML stanzas to program events 648 """ 649 pass

650

651 - def stream_header_received(self, ns, tag, attrs):

652 """ 653 Method called when stream just opened 654 """ 655 self.check_data_buffer()

656

657 - def stream_footer_received(self):

658 """ 659 Method called when stream just closed 660 """ 661 self.check_data_buffer()

662

663 - def has_received_endtag(self, level=0):

664 """ 665 Return True if at least one end tag was seen (at level) 666 """ 667 return self.__depth <= level and self.__max_depth > level

668

669 - def _inc_depth(self):

670 self.__last_depth = self.__depth 671 self.__depth += 1 672 self.__max_depth = max(self.__depth, self.__max_depth)

673

674 - def _dec_depth(self):

675 self.__last_depth = self.__depth 676 self.__depth -= 1

677

678 -def XML2Node(xml):

679 """ 680 Convert supplied textual string into XML node. Handy f.e. for reading 681 configuration file. Raises xml.parser.expat.parsererror if provided string 682 is not well-formed XML 683 """ 684 return NodeBuilder(xml).getDom()

685

686 -def BadXML2Node(xml):

687 """ 688 Convert supplied textual string into XML node. Survives if xml data is 689 cutted half way round. I.e. "<html>some text <br>some more text". Will raise 690 xml.parser.expat.parsererror on misplaced tags though. F.e. "<b>some text 691 <br>some more text</b>" will not work 692 """ 693 return NodeBuilder(xml).getDom()

694

Source Code for Module nbxmpp.simplexml