root / docs / source / userdoc / xml.rst @ bbd4ce54
History | View | Annotate | Download (2.6 kB)
1 |
********************** |
---|---|
2 |
:mod:`xml_` 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 |
|