code.grnet.gr Git - ncclient/blob - docs/source/userdoc/xml.rst

   1 **********************
   2 :mod:`content` module
   3 **********************
   4
   5 .. automodule:: ncclient.xml_
   6     :synopsis: XML facilities
   7
   8 Namespaces
   9 ==========
  10
  11 The following namespace is defined in this module.
  12
  13 .. autodata:: BASE_NS
  14
  15 Namespaces are handled just the same way as :mod:`~xml.etree.ElementTree`. So a qualified name takes the form *{namespace}tag*. There are some utility functions for qualified names:
  16
  17 .. function:: qualify(tag[, ns=BASE_NS])
  18
  19     :returns: qualified name
  20
  21 .. function:: unqualify(tag)
  22
  23     :returns: unqualified name
  24
  25     .. note:: It is strongly recommended to compare qualified names.
  26
  27 .. _dtree:
  28
  29 DictTree XML representation
  30 ===========================
  31
  32 .. note::
  33     Where this representation is stipulated, an XML literal or :class:`~xml.etree.ElementTree.Element` is just fine as well.
  34
  35 :mod:`ncclient` can make use of a special syntax for XML based on Python dictionaries. It is best illustrated through an example::
  36
  37     dtree = {
  38         'tag': qualify('a', 'some_namespace'),
  39         'attrib': {'attr': 'val'},
  40         'subtree': [ { 'tag': 'child1' }, { 'tag': 'child2', 'text': 'some text' } ]
  41     }
  42
  43 Calling :func:`dtree2xml` on *dtree* would return
  44
  45 .. code-block:: xml
  46
  47     <?xml version="1.0" encoding="UTF-8"?>
  48     <ns0:a attr="val" xmlns:ns0="some_namespace">
  49         <child1 />
  50         <child2>some text</child2>
  51     </ns0:a>
  52
  53 In addition to a 'pure' dictionary representation a DictTree node (including the root) may be an XML literal or an :class:`~xml.etree.ElementTree.Element` instance. The above example could thus be equivalently written as::
  54
  55     dtree2 = {
  56         'tag': '{ns}a',
  57         'attrib': {'attr': 'val'},
  58         'subtree': [ ET.Element('child1'), '<child2>some text</child2>' ]
  59     }
  60
  61 Converting between different representations
  62 ============================================
  63
  64 Conversions *to* DictTree representation are guaranteed to be entirely dictionaries. In converting *from* DictTree representation, the argument may be any valid representation as specified.
  65
  66 .. autofunction:: dtree2ele(spec)
  67
  68 .. autofunction:: dtree2xml(spec[, encoding="UTF-8"])
  69
  70 .. autofunction:: ele2dtree(ele)
  71
  72 .. autofunction:: ele2xml(ele)
  73
  74 .. autofunction:: xml2dtree(xml)
  75
  76 .. autofunction:: xml2ele(xml)
  77
  78 Other utility functions
  79 ========================
  80
  81 .. autofunction:: iselement(obj)
  82
  83     :see: :meth:`xml.etree.ElementTree.iselement`
  84
  85 .. autofunction:: find(ele, tag[, nslist=[]])
  86
  87 .. autofunction:: parse_root(raw)
  88
  89 .. autofunction:: validated_element(rep, tag=None, attrs=None, text=None)
  90
  91
  92 Errors
  93 ======
  94
  95 .. autoexception:: ContentError
  96     :show-inheritance:
  97     :members:
  98