Statistics
| Branch: | Tag: | Revision:

root / docs / source / userdoc / content.rst @ 216bb34c

History | View | Annotate | Download (2.6 kB)

1
**********************
2
:mod:`content` module
3
**********************
4

    
5
.. automodule:: ncclient.content
6
    :synopsis: Content layer
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