Statistics
| Branch: | Tag: | Revision:

root / ncclient / xml_.py @ dd225c7a

History | View | Annotate | Download (7.3 kB)

1
# Copyright 2009 Shikhar Bhushan
2
#
3
# Licensed under the Apache License, Version 2.0 (the "License");
4
# you may not use this file except in compliance with the License.
5
# You may obtain a copy of the License at
6
#
7
#    http://www.apache.org/licenses/LICENSE-2.0
8
#
9
# Unless required by applicable law or agreed to in writing, software
10
# distributed under the License is distributed on an "AS IS" BASIS,
11
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
# See the License for the specific language governing permissions and
13
# limitations under the License.
14

    
15

    
16
"""The :mod:`xml` module provides methods for creating XML documents, parsing
17
XML, and converting between different XML representations. It uses
18
:mod:`~xml.etree.ElementTree` internally.
19
"""
20

    
21
from cStringIO import StringIO
22
from xml.etree import cElementTree as ET
23

    
24
from ncclient import NCClientError
25

    
26
class ContentError(NCClientError):
27
    "Raised by methods of the :mod:`content` module in case of an error."
28
    pass
29

    
30
### Namespace-related
31

    
32
#: Base NETCONF namespace
33
BASE_NS_1_0 = 'urn:ietf:params:xml:ns:netconf:base:1.0'
34
#: ... and this is BASE_NS according to Cisco devices tested
35
CISCO_BS_1_0 = 'urn:ietf:params:netconf:base:1.0'
36
#: namespace for Tail-f data model
37
TAILF_AAA_1_1 = 'http://tail-f.com/ns/aaa/1.1'
38
#: namespace for Tail-f data model
39
TAILF_EXECD_1_1 = 'http://tail-f.com/ns/execd/1.1'
40
#: namespace for Cisco data model
41
CISCO_CPI_1_0 = 'http://www.cisco.com/cpi_10/schema'
42
#: namespace for Flowmon data model
43
FLOWMON_1_0 = 'http://www.liberouter.org/ns/netopeer/flowmon/1.0'
44

    
45
try:
46
    register_namespace = ET.register_namespace
47
except AttributeError:
48
    def register_namespace(prefix, uri):
49
        from xml.etree import ElementTree
50
        # cElementTree uses ElementTree's _namespace_map, so that's ok
51
        ElementTree._namespace_map[uri] = prefix
52

    
53
prefix_map = {
54
    BASE_NS_1_0: 'nc',
55
    TAILF_AAA_1_1: 'aaa',
56
    TAILF_EXECD_1_1: 'execd',
57
    CISCO_CPI_1_0: 'cpi',
58
    FLOWMON_1_0: 'fm',
59
}
60

    
61
for (ns, pre) in prefix_map.items():
62
    register_namespace(pre, ns)
63

    
64
qualify = lambda tag, ns=BASE_NS_1_0: tag if ns is None else '{%s}%s' % (ns, tag)
65

    
66
multiqualify = lambda tag, nslist=(BASE_NS_1_0, CISCO_BS_1_0): [qualify(tag, ns) for ns in nslist]
67

    
68
unqualify = lambda tag: tag[tag.rfind('}')+1:]
69

    
70
### XML representations
71

    
72
class DictTree:
73

    
74
    @staticmethod
75
    def Element(spec):
76
        """DictTree -> Element
77

78
        :type spec: :obj:`dict` or :obj:`string` or :class:`~xml.etree.ElementTree.Element`
79

80
        :rtype: :class:`~xml.etree.ElementTree.Element`
81
        """
82
        if iselement(spec):
83
            return spec
84
        elif isinstance(spec, basestring):
85
            return XML.Element(spec)
86
        if not isinstance(spec, dict):
87
            raise ContentError("Invalid tree spec")
88
        if 'tag' in spec:
89
            ele = ET.Element(spec.get('tag'), spec.get('attrib', {}))
90
            ele.text = spec.get('text', '')
91
            ele.tail = spec.get('tail', '')
92
            subtree = spec.get('subtree', [])
93
            # might not be properly specified as list but may be dict
94
            if not isinstance(subtree, list):
95
                subtree = [subtree]
96
            for subele in subtree:
97
                ele.append(DictTree.Element(subele))
98
            return ele
99
        elif 'comment' in spec:
100
            return ET.Comment(spec.get('comment'))
101
        else:
102
            raise ContentError('Invalid tree spec')
103

    
104
    @staticmethod
105
    def XML(spec, encoding='UTF-8'):
106
        """DictTree -> XML
107

108
        :type spec: :obj:`dict` or :obj:`string` or :class:`~xml.etree.ElementTree.Element`
109

110
        :arg encoding: chraracter encoding
111

112
        :rtype: string
113
        """
114
        return Element.XML(DictTree.Element(spec), encoding)
115

    
116
class Element:
117

    
118
    @staticmethod
119
    def DictTree(ele):
120
        """DictTree -> Element
121

122
        :type spec: :class:`~xml.etree.ElementTree.Element`
123
        :rtype: :obj:`dict`
124
        """
125
        return {
126
            'tag': ele.tag,
127
            'attributes': ele.attrib,
128
            'text': ele.text,
129
            'tail': ele.tail,
130
            'subtree': [ Element.DictTree(child) for child in ele.getchildren() ]
131
        }
132

    
133
    @staticmethod
134
    def XML(ele, encoding='UTF-8'):
135
        """Element -> XML
136

137
        :type spec: :class:`~xml.etree.ElementTree.Element`
138
        :arg encoding: character encoding
139
        :rtype: :obj:`string`
140
        """
141
        xml = ET.tostring(ele, encoding)
142
        if xml.startswith('<?xml'):
143
            return xml
144
        else:
145
            return '<?xml version="1.0" encoding="%s"?>%s' % (encoding, xml)
146

    
147
class XML:
148

    
149
    @staticmethod
150
    def DictTree(xml):
151
        """XML -> DictTree
152

153
        :type spec: :obj:`string`
154
        :rtype: :obj:`dict`
155
        """
156
        return Element.DictTree(XML.Element(xml))
157

    
158
    @staticmethod
159
    def Element(xml):
160
        """XML -> Element
161

162
        :type xml: :obj:`string`
163
        :rtype: :class:`~xml.etree.ElementTree.Element`
164
        """
165
        return ET.fromstring(xml)
166

    
167
dtree2ele = DictTree.Element
168
dtree2xml = DictTree.XML
169
ele2dtree = Element.DictTree
170
ele2xml = Element.XML
171
xml2dtree = XML.DictTree
172
xml2ele = XML.Element
173

    
174
### Other utility functions
175

    
176
iselement = ET.iselement
177

    
178

    
179
NSLIST = [BASE_NS_1_0, CISCO_BS_1_0]
180

    
181
def find(ele, tag, nslist=[]):
182
    """If *nslist* is empty, same as :meth:`xml.etree.ElementTree.Element.find`.
183
    If it is not, *tag* is interpreted as an unqualified name and qualified
184
    using each item in *nslist* (with a :const:`None` item in *nslit* meaning no
185
    qualification is done). The first match is returned.
186

187
    :arg nslist: optional list of namespaces
188
    :type nslit: `string` `list`
189
    """
190
    if nslist:
191
        for qname in multiqualify(tag):
192
            found = ele.find(qname)
193
            if found is not None:
194
                return found
195
    else:
196
        return ele.find(tag)
197

    
198
def parse_root(raw):
199
    """Efficiently parses the root element of an XML document.
200

201
    :arg raw: XML document
202
    :type raw: string
203
    :returns: a tuple of `(tag, attributes)`, where `tag` is the (qualified) name of the element and `attributes` is a dictionary of its attributes.
204
    :rtype: `tuple`
205
    """
206
    fp = StringIO(raw[:1024]) # this is a guess but start element beyond 1024 bytes would be a bit absurd
207
    for event, element in ET.iterparse(fp, events=('start',)):
208
        return (element.tag, element.attrib)
209

    
210
def validated_element(rep, tags=None, attrs=None, text=None):
211
    """Checks if the root element meets the supplied criteria. Returns a
212
    :class:`~xml.etree.ElementTree.Element` instance if so, otherwise raises
213
    :exc:`ContentError`.
214

215
    :arg tags: tag name or a list of allowable tag names
216
    :arg attrs: list of required attribute names, each item may be a list of allowable alternatives
217
    :arg text: textual content to match
218
    :type rep: :obj:`dict` or :obj:`string` or :class:`~xml.etree.ElementTree.Element`
219
    """
220
    ele = dtree2ele(rep)
221
    err = False
222
    if tags:
223
        if isinstance(tags, basestring):
224
            tags = [tags]
225
        if ele.tag not in tags:
226
            err = True
227
    if attrs:
228
        for req in attrs:
229
            if isinstance(req, basestring): req = [req]
230
            for alt in req:
231
                if alt in ele.attrib:
232
                    break
233
            else:
234
                err = True
235
    if text and ele.text != text:
236
        err = True
237
    if err:
238
        raise ContentError("Element [%s] does not meet requirements" % ele.tag)
239
    return ele