Package pyxmpp :: Module objects

[hide private]

# Source Code for Module pyxmpp.objects

      1  #
      2  # (C) Copyright 2003-2010 Jacek Konieczny <jajcus@jajcus.net>
      3  #
      4  # This program is free software; you can redistribute it and/or modify
      5  # it under the terms of the GNU Lesser General Public License Version
      6  # 2.1 as published by the Free Software Foundation.
      7  #
      8  # This program is distributed in the hope that it will be useful,
      9  # but WITHOUT ANY WARRANTY; without even the implied warranty of
     10  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     11  # GNU Lesser General Public License for more details.
     12  #
     13  # You should have received a copy of the GNU Lesser General Public
     14  # License along with this program; if not, write to the Free Software
     15  # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
     16  #
     17  # pylint: disable-msg=W0232, E0201
     18
     19  """General base classes for PyXMPP objects."""
     20
     21  __docformat__="restructuredtext en"
     22
     23  import libxml2
     24  from pyxmpp.xmlextra import common_doc
     25
     26 -class StanzaPayloadObject(object):
     27      """Base class for objects that may be used as XMPP stanza payload and don't keep
     28      internal XML representation, only parsed values.
     29
     30      Provides `as_xml` method. Derived classes must override `xml_element_name` and
     31      `xml_element_namespace` class attributes and the `complete_xml_element` method.
     32
     33      Please note that not all classes derived from `StanzaPayloadObject` should be
     34      used directly as stanza payload. Some of them are parts of higher level objects.
     35
     36      :Cvariables:
     37          - `xml_element_name`: name for the XML element provided by the class.
     38          - `xml_element_namespace`: namespace URI for the XML element provided
     39            by the class.
     40      :Types:
     41          - `xml_element_name`: `unicode`
     42          - `xml_element_namespace`: `unicode`
     43      """
     44      xml_element_name = None
     45      xml_element_namespace = None
     46
     47 -    def as_xml(self, parent = None, doc = None):
     48          """Get the XML representation of `self`.
     49
     50          New document will be created if no `parent` and no `doc` is given.
     51
     52          :Parameters:
     53              - `parent`: the parent for the XML element.
     54              - `doc`: the document where the element should be created. If not
     55                given and `parent` is provided then autodetection is attempted.
     56                If that fails, then `common_doc` is used.
     57          :Types:
     58              - `parent`: `libxml2.xmlNode`
     59              - `doc`: `libxml2.xmlDoc`
     60          :return: the new XML element or document created.
     61          :returntype: `libxml2.xmlNode` or `libxml2.xmlDoc`"""
     62          if parent:
     63              if not doc:
     64                  n = parent
     65                  while n:
     66                      if n.type == "xml_document":
     67                          doc = n
     68                          break
     69                      n = n.parent
     70                  if not doc:
     71                      doc = common_doc
     72              try:
     73                  ns = parent.searchNsByHref(doc, self.xml_element_namespace)
     74              except libxml2.treeError:
     75                  ns = None
     76              xmlnode = parent.newChild(ns,self.xml_element_name,None)
     77              if not ns:
     78                  ns = xmlnode.newNs(self.xml_element_namespace,None)
     79                  xmlnode.setNs(ns)
     80              doc1 = doc
     81          else:
     82              if doc:
     83                  doc1 = doc
     84              else:
     85                  doc1 = libxml2.newDoc("1.0")
     86              xmlnode = doc1.newChild(None,self.xml_element_name, None)
     87              ns = xmlnode.newNs(self.xml_element_namespace, None)
     88              xmlnode.setNs(ns)
     89
     90          self.complete_xml_element(xmlnode, doc1)
     91
     92          if doc or parent:
     93              return xmlnode
     94          doc1.setRootElement(xmlnode)
     95          return doc1
     96
     97 -    def complete_xml_element(self, xmlnode, doc):
     98          """Complete the XML node with `self` content.
     99
    100          Should be overriden in classes derived from `StanzaPayloadObject`.
    101
    102          :Parameters:
    103              - `xmlnode`: XML node with the element being built. It has already
    104                right name and namespace, but no attributes or content.
    105              - `doc`: document to which the element belongs.
    106          :Types:
    107              - `xmlnode`: `libxml2.xmlNode`
    108              - `doc`: `libxml2.xmlDoc`"""
    109          pass
    110
    111 -class StanzaPayloadWrapperObject(object):
    112      """Base class for objects that may be used as XMPP stanza payload and maintain
    113      an internal XML representation of self.
    114
    115      Provides `as_xml` method. Objects of derived classes must have the `xmlnode` attribute.
    116
    117      Please note that not all classes derived from `StanzaPayloadWrapperObject` should be
    118      used directly as stanza payload. Some of them are parts of higher level objects.
    119
    120      :Ivariables:
    121          - `xmlnode`: XML node of the object.
    122      :Types:
    123          - `xmlnode`: `libxml2.xmlNode`
    124      """
    125
    126 -    def as_xml(self, parent = None, doc = None):
    127          """Get the XML representation of `self`.
    128
    129          New document will be created if no `parent` and no `doc` is given.
    130
    131          :Parameters:
    132              - `parent`: the parent for the XML element.
    133              - `doc`: the document where the element should be created. If not
    134                given and `parent` is provided then autodetection is attempted.
    135                If that fails, then `common_doc` is used.
    136          :Types:
    137              - `parent`: `libxml2.xmlNode`
    138              - `doc`: `libxml2.xmlDoc`
    139
    140          :return: the new XML element (copy of `self.xmlnode`) or document
    141              created (containg the copy as the root element).
    142          :returntype: `libxml2.xmlNode` or `libxml2.xmlDoc`"""
    143          if parent:
    144              if not doc:
    145                  n = parent
    146                  while n:
    147                      if n.type == "xml_document":
    148                          doc = n
    149                          break
    150                      n = n.parent
    151                  if not doc:
    152                      doc = common_doc
    153              copy=self.xmlnode.docCopyNode(doc,True)
    154              parent.addChild(copy)
    155              return copy
    156          else:
    157              if not doc:
    158                  doc1=libxml2.newDoc("1.0")
    159              else:
    160                  doc1=doc
    161              xmlnode=doc1.addChild(self.xmlnode.docCopyNode(doc,True))
    162              doc1.setRootElement(xmlnode)
    163              if doc:
    164                  return xmlnode
    165              return doc1
    166
    167  # vi: sts=4 et sw=4
    168