5 .. automodule:: ncclient.content
6 :synopsis: Content layer
11 The following namespace is defined in this module.
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:
17 .. function:: qualify(tag[, ns=BASE_NS])
19 :returns: qualified name
21 .. function:: unqualify(tag)
23 :returns: unqualified name
25 .. note:: It is strongly recommended to compare qualified names.
29 DictTree XML representation
30 ===========================
33 Where this representation is stipulated, an XML literal or :class:`~xml.etree.ElementTree.Element` is just fine as well.
35 :mod:`ncclient` can make use of a special syntax for XML based on Python dictionaries. It is best illustrated through an example::
38 'tag': qualify('a', 'some_namespace'),
39 'attrib': {'attr': 'val'},
40 'subtree': [ { 'tag': 'child1' }, { 'tag': 'child2', 'text': 'some text' } ]
43 Calling :func:`dtree2xml` on *dtree* would return
47 <?xml version="1.0" encoding="UTF-8"?>
48 <ns0:a attr="val" xmlns:ns0="some_namespace">
50 <child2>some text</child2>
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::
57 'attrib': {'attr': 'val'},
58 'subtree': [ ET.Element('child1'), '<child2>some text</child2>' ]
61 Converting between different representations
62 ============================================
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.
66 .. autofunction:: dtree2ele(spec)
68 .. autofunction:: dtree2xml(spec[, encoding="UTF-8"])
70 .. autofunction:: ele2dtree(ele)
72 .. autofunction:: ele2xml(ele)
74 .. autofunction:: xml2dtree(xml)
76 .. autofunction:: xml2ele(xml)
78 Other utility functions
79 ========================
81 .. autofunction:: iselement(obj)
83 :see: :meth:`xml.etree.ElementTree.iselement`
85 .. autofunction:: find(ele, tag[, nslist=[]])
87 .. autofunction:: parse_root(raw)
89 .. autofunction:: validated_element(rep, tag=None, attrs=None, text=None)
95 .. autoexception:: ContentError