Statistics
| Branch: | Tag: | Revision:

root / ncclient / operations / rpc.py @ dd8b8dd7

History | View | Annotate | Download (12.1 kB)

1 a14c36f9 Shikhar Bhushan
# Copyright 2009 Shikhar Bhushan
2 a14c36f9 Shikhar Bhushan
#
3 a14c36f9 Shikhar Bhushan
# Licensed under the Apache License, Version 2.0 (the "License");
4 a14c36f9 Shikhar Bhushan
# you may not use this file except in compliance with the License.
5 a14c36f9 Shikhar Bhushan
# You may obtain a copy of the License at
6 a14c36f9 Shikhar Bhushan
#
7 a14c36f9 Shikhar Bhushan
#    http://www.apache.org/licenses/LICENSE-2.0
8 a14c36f9 Shikhar Bhushan
#
9 a14c36f9 Shikhar Bhushan
# Unless required by applicable law or agreed to in writing, software
10 a14c36f9 Shikhar Bhushan
# distributed under the License is distributed on an "AS IS" BASIS,
11 a14c36f9 Shikhar Bhushan
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 a14c36f9 Shikhar Bhushan
# See the License for the specific language governing permissions and
13 a14c36f9 Shikhar Bhushan
# limitations under the License.
14 a14c36f9 Shikhar Bhushan
15 a14c36f9 Shikhar Bhushan
from threading import Event, Lock
16 a14c36f9 Shikhar Bhushan
from uuid import uuid1
17 a14c36f9 Shikhar Bhushan
18 9667bcb2 Shikhar Bhushan
from ncclient.xml_ import *
19 0cdb8b3c Shikhar Bhushan
from ncclient.transport import SessionListener
20 a14c36f9 Shikhar Bhushan
21 216bb34c Shikhar Bhushan
from errors import OperationError, TimeoutExpiredError, MissingCapabilityError
22 a14c36f9 Shikhar Bhushan
23 a14c36f9 Shikhar Bhushan
import logging
24 9667bcb2 Shikhar Bhushan
logger = logging.getLogger("ncclient.operations.rpc")
25 a14c36f9 Shikhar Bhushan
26 a14c36f9 Shikhar Bhushan
27 a14c36f9 Shikhar Bhushan
class RPCReply:
28 4f650d54 Shikhar Bhushan
29 a7cb58ce Shikhar Bhushan
    """Represents an *<rpc-reply>*. Only concerns itself with whether the
30 216bb34c Shikhar Bhushan
    operation was successful.
31 216bb34c Shikhar Bhushan

32 216bb34c Shikhar Bhushan
    .. note::
33 216bb34c Shikhar Bhushan
        If the reply has not yet been parsed there is an implicit, one-time
34 216bb34c Shikhar Bhushan
        parsing overhead to accessing the attributes defined by this class and
35 216bb34c Shikhar Bhushan
        any subclasses.
36 216bb34c Shikhar Bhushan
    """
37 a7cb58ce Shikhar Bhushan
38 a14c36f9 Shikhar Bhushan
    def __init__(self, raw):
39 a14c36f9 Shikhar Bhushan
        self._raw = raw
40 a14c36f9 Shikhar Bhushan
        self._parsed = False
41 a14c36f9 Shikhar Bhushan
        self._root = None
42 a14c36f9 Shikhar Bhushan
        self._errors = []
43 4f650d54 Shikhar Bhushan
44 a14c36f9 Shikhar Bhushan
    def __repr__(self):
45 a14c36f9 Shikhar Bhushan
        return self._raw
46 4f650d54 Shikhar Bhushan
47 a7cb58ce Shikhar Bhushan
    def _parsing_hook(self, root):
48 a7cb58ce Shikhar Bhushan
        """Subclass can implement.
49 a7cb58ce Shikhar Bhushan

50 a7cb58ce Shikhar Bhushan
        :type root: :class:`~xml.etree.ElementTree.Element`
51 a7cb58ce Shikhar Bhushan
        """
52 a7cb58ce Shikhar Bhushan
        pass
53 4f650d54 Shikhar Bhushan
54 a14c36f9 Shikhar Bhushan
    def parse(self):
55 a7cb58ce Shikhar Bhushan
        """Parse the *<rpc-reply>*"""
56 65c6a607 Shikhar Bhushan
        if self._parsed:
57 65c6a607 Shikhar Bhushan
            return
58 9667bcb2 Shikhar Bhushan
        root = self._root = to_ele(self._raw) # The <rpc-reply> element
59 9667bcb2 Shikhar Bhushan
        # Per RFC 4741 an <ok/> tag is sent when there are no errors or warnings
60 9667bcb2 Shikhar Bhushan
        ok = root.find(qualify("ok"))
61 9667bcb2 Shikhar Bhushan
        if ok is None:
62 9667bcb2 Shikhar Bhushan
            # Create RPCError objects from <rpc-error> elements
63 9667bcb2 Shikhar Bhushan
            error = root.find(qualify("rpc-error"))
64 a14c36f9 Shikhar Bhushan
            if error is not None:
65 a14c36f9 Shikhar Bhushan
                for err in root.getiterator(error.tag):
66 9667bcb2 Shikhar Bhushan
                    # Process a particular <rpc-error>
67 9667bcb2 Shikhar Bhushan
                    self._errors.append(RPCError(err))
68 a14c36f9 Shikhar Bhushan
        self._parsing_hook(root)
69 a14c36f9 Shikhar Bhushan
        self._parsed = True
70 4f650d54 Shikhar Bhushan
71 a14c36f9 Shikhar Bhushan
    @property
72 a14c36f9 Shikhar Bhushan
    def xml(self):
73 a7cb58ce Shikhar Bhushan
        "*<rpc-reply>* as returned"
74 a14c36f9 Shikhar Bhushan
        return self._raw
75 4f650d54 Shikhar Bhushan
76 a14c36f9 Shikhar Bhushan
    @property
77 a14c36f9 Shikhar Bhushan
    def ok(self):
78 a7cb58ce Shikhar Bhushan
        "Boolean value indicating if there were no errors."
79 a14c36f9 Shikhar Bhushan
        if not self._parsed:
80 a14c36f9 Shikhar Bhushan
            self.parse()
81 a14c36f9 Shikhar Bhushan
        return not self._errors # empty list => false
82 4f650d54 Shikhar Bhushan
83 a14c36f9 Shikhar Bhushan
    @property
84 a14c36f9 Shikhar Bhushan
    def error(self):
85 216bb34c Shikhar Bhushan
        """Short for :attr:`errors` [0]; :const:`None` if there were no errors.
86 216bb34c Shikhar Bhushan
        """
87 a14c36f9 Shikhar Bhushan
        if not self._parsed:
88 a14c36f9 Shikhar Bhushan
            self.parse()
89 a14c36f9 Shikhar Bhushan
        if self._errors:
90 a14c36f9 Shikhar Bhushan
            return self._errors[0]
91 a14c36f9 Shikhar Bhushan
        else:
92 a14c36f9 Shikhar Bhushan
            return None
93 4f650d54 Shikhar Bhushan
94 a14c36f9 Shikhar Bhushan
    @property
95 a14c36f9 Shikhar Bhushan
    def errors(self):
96 216bb34c Shikhar Bhushan
        """`list` of :class:`RPCError` objects. Will be empty if there were no
97 216bb34c Shikhar Bhushan
        *<rpc-error>* elements in reply.
98 216bb34c Shikhar Bhushan
        """
99 a14c36f9 Shikhar Bhushan
        if not self._parsed:
100 a14c36f9 Shikhar Bhushan
            self.parse()
101 a14c36f9 Shikhar Bhushan
        return self._errors
102 a14c36f9 Shikhar Bhushan
103 a14c36f9 Shikhar Bhushan
104 9667bcb2 Shikhar Bhushan
class RPCError(OperationError):
105 4f650d54 Shikhar Bhushan
106 9667bcb2 Shikhar Bhushan
    """Represents an *<rpc-error>*. It is a type of :exc:`OperationError`
107 2abf9522 Shikhar Bhushan
    and can be raised like any other exception."""
108 a7cb58ce Shikhar Bhushan
109 9667bcb2 Shikhar Bhushan
    def __init__(self, err):
110 9667bcb2 Shikhar Bhushan
        self._type = None
111 9667bcb2 Shikhar Bhushan
        self._severity = None
112 9667bcb2 Shikhar Bhushan
        self._info = None
113 9667bcb2 Shikhar Bhushan
        self._tag = None
114 9667bcb2 Shikhar Bhushan
        self._path = None
115 9667bcb2 Shikhar Bhushan
        self._message = None
116 9667bcb2 Shikhar Bhushan
        for subele in err:
117 9667bcb2 Shikhar Bhushan
            if subele.tag == qualify("error-tag"):
118 9667bcb2 Shikhar Bhushan
                self._tag = subele.text
119 9667bcb2 Shikhar Bhushan
            elif subele.tag == qualify("error-severity"):
120 9667bcb2 Shikhar Bhushan
                self._severity = subele.text
121 9667bcb2 Shikhar Bhushan
            elif subele.tag == qualify("error-info"):
122 9667bcb2 Shikhar Bhushan
                self._info = subele.text
123 9667bcb2 Shikhar Bhushan
            elif subele.tag == qualify("error-path"):
124 9667bcb2 Shikhar Bhushan
                self._path = subele.text
125 9667bcb2 Shikhar Bhushan
            elif subele.tag == qualify("error-message"):
126 9667bcb2 Shikhar Bhushan
                self._message = subele.text
127 a14c36f9 Shikhar Bhushan
        if self.message is not None:
128 d771dffc Shikhar Bhushan
            OperationError.__init__(self, self.message)
129 a14c36f9 Shikhar Bhushan
        else:
130 d771dffc Shikhar Bhushan
            OperationError.__init__(self)
131 4f650d54 Shikhar Bhushan
132 a14c36f9 Shikhar Bhushan
    @property
133 a14c36f9 Shikhar Bhushan
    def type(self):
134 2abf9522 Shikhar Bhushan
        "`string` representing text of *error-type* element"
135 9667bcb2 Shikhar Bhushan
        return self._type
136 4f650d54 Shikhar Bhushan
137 a14c36f9 Shikhar Bhushan
    @property
138 a14c36f9 Shikhar Bhushan
    def severity(self):
139 2abf9522 Shikhar Bhushan
        "`string` representing text of *error-severity* element"
140 9667bcb2 Shikhar Bhushan
        return self._severity
141 4f650d54 Shikhar Bhushan
142 a14c36f9 Shikhar Bhushan
    @property
143 a14c36f9 Shikhar Bhushan
    def tag(self):
144 2abf9522 Shikhar Bhushan
        "`string` representing text of *error-tag* element"
145 9667bcb2 Shikhar Bhushan
        return self._tag
146 4f650d54 Shikhar Bhushan
147 a14c36f9 Shikhar Bhushan
    @property
148 a14c36f9 Shikhar Bhushan
    def path(self):
149 2abf9522 Shikhar Bhushan
        "`string` or :const:`None`; representing text of *error-path* element"
150 9667bcb2 Shikhar Bhushan
        return self._path
151 4f650d54 Shikhar Bhushan
152 a14c36f9 Shikhar Bhushan
    @property
153 a14c36f9 Shikhar Bhushan
    def message(self):
154 2abf9522 Shikhar Bhushan
        "`string` or :const:`None`; representing text of *error-message* element"
155 9667bcb2 Shikhar Bhushan
        return self._message
156 4f650d54 Shikhar Bhushan
157 a14c36f9 Shikhar Bhushan
    @property
158 a14c36f9 Shikhar Bhushan
    def info(self):
159 2abf9522 Shikhar Bhushan
        "`string` (XML) or :const:`None`, representing *error-info* element"
160 9667bcb2 Shikhar Bhushan
        return self._info
161 a14c36f9 Shikhar Bhushan
162 a14c36f9 Shikhar Bhushan
163 0cdb8b3c Shikhar Bhushan
class RPCReplyListener(SessionListener):
164 4f650d54 Shikhar Bhushan
165 a7cb58ce Shikhar Bhushan
    # internal use
166 a7cb58ce Shikhar Bhushan
167 7b02d55b Shikhar Bhushan
    # one instance per session -- maybe there is a better way??
168 a14c36f9 Shikhar Bhushan
    def __new__(cls, session):
169 a14c36f9 Shikhar Bhushan
        instance = session.get_listener_instance(cls)
170 a14c36f9 Shikhar Bhushan
        if instance is None:
171 a14c36f9 Shikhar Bhushan
            instance = object.__new__(cls)
172 a14c36f9 Shikhar Bhushan
            instance._lock = Lock()
173 6a2dfeb4 Shikhar Bhushan
            instance._id2rpc = {}
174 0304f041 Shikhar Bhushan
            #instance._pipelined = session.can_pipeline
175 a14c36f9 Shikhar Bhushan
            session.add_listener(instance)
176 a14c36f9 Shikhar Bhushan
        return instance
177 4f650d54 Shikhar Bhushan
178 a14c36f9 Shikhar Bhushan
    def register(self, id, rpc):
179 a14c36f9 Shikhar Bhushan
        with self._lock:
180 a14c36f9 Shikhar Bhushan
            self._id2rpc[id] = rpc
181 4f650d54 Shikhar Bhushan
182 a14c36f9 Shikhar Bhushan
    def callback(self, root, raw):
183 a14c36f9 Shikhar Bhushan
        tag, attrs = root
184 9667bcb2 Shikhar Bhushan
        if tag != qualify("rpc-reply"):
185 a14c36f9 Shikhar Bhushan
            return
186 0304f041 Shikhar Bhushan
        for key in attrs: # in the <rpc-reply> attributes
187 9667bcb2 Shikhar Bhushan
            if key == "message-id": # if we found msgid attr
188 0304f041 Shikhar Bhushan
                id = attrs[key] # get the msgid
189 9667bcb2 Shikhar Bhushan
                with self._lock:
190 9667bcb2 Shikhar Bhushan
                    try:                    
191 9667bcb2 Shikhar Bhushan
                        rpc = self._id2rpc[id] # the corresponding rpc
192 9667bcb2 Shikhar Bhushan
                        logger.debug("Delivering to %r" % rpc)
193 0304f041 Shikhar Bhushan
                        rpc.deliver_reply(raw)
194 9667bcb2 Shikhar Bhushan
                    except KeyError:
195 9667bcb2 Shikhar Bhushan
                        raise OperationError("Unknown message-id: %s", id)
196 9667bcb2 Shikhar Bhushan
                    # no catching other exceptions, fail loudly if must
197 9667bcb2 Shikhar Bhushan
                    else:
198 9667bcb2 Shikhar Bhushan
                        # if no error delivering, can del the reference to the RPC
199 9667bcb2 Shikhar Bhushan
                        del self._id2rpc[id]
200 9667bcb2 Shikhar Bhushan
                        break
201 a14c36f9 Shikhar Bhushan
        else:
202 9667bcb2 Shikhar Bhushan
            raise OperationError("Could not find 'message-id' attribute in <rpc-reply>")
203 0304f041 Shikhar Bhushan
    
204 a14c36f9 Shikhar Bhushan
    def errback(self, err):
205 6a2dfeb4 Shikhar Bhushan
        try:
206 6a2dfeb4 Shikhar Bhushan
            for rpc in self._id2rpc.values():
207 6a2dfeb4 Shikhar Bhushan
                rpc.deliver_error(err)
208 6a2dfeb4 Shikhar Bhushan
        finally:
209 6a2dfeb4 Shikhar Bhushan
            self._id2rpc.clear()
210 4de03d63 Shikhar Bhushan
211 4de03d63 Shikhar Bhushan
212 4de03d63 Shikhar Bhushan
class RPC(object):
213 4f650d54 Shikhar Bhushan
214 216bb34c Shikhar Bhushan
    """Base class for all operations.
215 216bb34c Shikhar Bhushan

216 216bb34c Shikhar Bhushan
    Directly corresponds to *<rpc>* requests. Handles making the request, and
217 216bb34c Shikhar Bhushan
    taking delivery of the reply.
218 216bb34c Shikhar Bhushan
    """
219 a7cb58ce Shikhar Bhushan
220 bbd4ce54 Shikhar Bhushan
    #: Subclasses can specify their dependencies on capabilities. List of URI's
221 a7cb58ce Shikhar Bhushan
    # or abbreviated names, e.g. ':writable-running'. These are verified at the
222 a7cb58ce Shikhar Bhushan
    # time of object creation. If the capability is not available, a
223 a7cb58ce Shikhar Bhushan
    # :exc:`MissingCapabilityError` is raised.
224 4de03d63 Shikhar Bhushan
    DEPENDS = []
225 a7cb58ce Shikhar Bhushan
226 bbd4ce54 Shikhar Bhushan
    #: Subclasses can specify a different reply class, but it must be a
227 a7cb58ce Shikhar Bhushan
    # subclass of :class:`RPCReply`.
228 4de03d63 Shikhar Bhushan
    REPLY_CLS = RPCReply
229 4f650d54 Shikhar Bhushan
230 9667bcb2 Shikhar Bhushan
    def __init__(self, session, async=False, timeout=None, raise_mode="none"):
231 4de03d63 Shikhar Bhushan
        self._session = session
232 4de03d63 Shikhar Bhushan
        try:
233 4de03d63 Shikhar Bhushan
            for cap in self.DEPENDS:
234 4de03d63 Shikhar Bhushan
                self._assert(cap)
235 4de03d63 Shikhar Bhushan
        except AttributeError:
236 4f650d54 Shikhar Bhushan
            pass
237 4de03d63 Shikhar Bhushan
        self._async = async
238 4de03d63 Shikhar Bhushan
        self._timeout = timeout
239 6c70b245 Shikhar Bhushan
        self._raise_mode = raise_mode
240 9667bcb2 Shikhar Bhushan
        self._id = uuid1().urn # Keeps things simple instead of having a class attr that has to be locked
241 4de03d63 Shikhar Bhushan
        self._listener = RPCReplyListener(session)
242 4de03d63 Shikhar Bhushan
        self._listener.register(self._id, self)
243 4de03d63 Shikhar Bhushan
        self._reply = None
244 4f650d54 Shikhar Bhushan
        self._error = None
245 a7cb58ce Shikhar Bhushan
        self._event = Event()
246 4f650d54 Shikhar Bhushan
247 9667bcb2 Shikhar Bhushan
    def _build(self, subele):
248 a7cb58ce Shikhar Bhushan
        # internal
249 9667bcb2 Shikhar Bhushan
        ele = new_ele("rpc", {"message-id": self._id}, xmlns=BASE_NS_1_0)
250 9667bcb2 Shikhar Bhushan
        ele.append(subele)
251 9667bcb2 Shikhar Bhushan
        return to_xml(ele)
252 4f650d54 Shikhar Bhushan
253 4de03d63 Shikhar Bhushan
    def _request(self, op):
254 a7cb58ce Shikhar Bhushan
        """Subclasses call this method to make the RPC request.
255 0304f041 Shikhar Bhushan
        
256 0304f041 Shikhar Bhushan
        In synchronous mode, waits until the reply is received and returns
257 a7cb58ce Shikhar Bhushan
        :class:`RPCReply`.
258 0304f041 Shikhar Bhushan
        
259 0304f041 Shikhar Bhushan
        In asynchronous mode, returns immediately, returning a reference to this
260 0304f041 Shikhar Bhushan
        object. The :attr:`event` attribute will be set when the reply has been
261 0304f041 Shikhar Bhushan
        received (see :attr:`reply`) or an error occured (see :attr:`error`).
262 0304f041 Shikhar Bhushan
        
263 a7cb58ce Shikhar Bhushan
        :type opspec: :obj:`dict` or :obj:`string` or :class:`~xml.etree.ElementTree.Element`
264 0304f041 Shikhar Bhushan
        :rtype: :class:`RPCReply` (sync) or :class:`RPC` (async)
265 a7cb58ce Shikhar Bhushan
        """
266 9667bcb2 Shikhar Bhushan
        logger.info('Requesting %r' % self.__class__.__name__)
267 4de03d63 Shikhar Bhushan
        req = self._build(op)
268 66cd54c8 Shikhar Bhushan
        self._session.send(req)
269 66cd54c8 Shikhar Bhushan
        if self._async:
270 9667bcb2 Shikhar Bhushan
            logger.debug('Async request, returning %r', self)
271 0304f041 Shikhar Bhushan
            return self
272 4de03d63 Shikhar Bhushan
        else:
273 9667bcb2 Shikhar Bhushan
            logger.debug('Sync request, will wait for timeout=%r' %
274 9667bcb2 Shikhar Bhushan
                         self._timeout)
275 66cd54c8 Shikhar Bhushan
            self._event.wait(self._timeout)
276 66cd54c8 Shikhar Bhushan
            if self._event.isSet():
277 66cd54c8 Shikhar Bhushan
                if self._error:
278 6c70b245 Shikhar Bhushan
                    # Error that prevented reply delivery
279 0cdb8b3c Shikhar Bhushan
                    raise self._error
280 66cd54c8 Shikhar Bhushan
                self._reply.parse()
281 6c70b245 Shikhar Bhushan
                if self._reply.error is not None:
282 6c70b245 Shikhar Bhushan
                    # <rpc-error>'s [ RPCError ]
283 6c70b245 Shikhar Bhushan
                    if self._raise_mode == "all":
284 7b02d55b Shikhar Bhushan
                        raise self._reply.error
285 6c70b245 Shikhar Bhushan
                    elif (self._raise_mode == "errors" and
286 6c70b245 Shikhar Bhushan
                          self._reply.error.type == "error"):
287 6c70b245 Shikhar Bhushan
                        raise self._reply.error
288 66cd54c8 Shikhar Bhushan
                return self._reply
289 4de03d63 Shikhar Bhushan
            else:
290 216bb34c Shikhar Bhushan
                raise TimeoutExpiredError
291 4f650d54 Shikhar Bhushan
292 a7cb58ce Shikhar Bhushan
    def request(self, *args, **kwds):
293 dd8b8dd7 Shikhar Bhushan
        "Subclasses implement this method."
294 dd225c7a Shikhar Bhushan
        return self._request(self.SPEC)
295 6c70b245 Shikhar Bhushan
    
296 4de03d63 Shikhar Bhushan
    def _assert(self, capability):
297 a7cb58ce Shikhar Bhushan
        """Subclasses can use this method to verify that a capability is available
298 a7cb58ce Shikhar Bhushan
        with the NETCONF server, before making a request that requires it. A
299 216bb34c Shikhar Bhushan
        :exc:`MissingCapabilityError` will be raised if the capability is not
300 a7cb58ce Shikhar Bhushan
        available."""
301 4de03d63 Shikhar Bhushan
        if capability not in self._session.server_capabilities:
302 bbd4ce54 Shikhar Bhushan
            raise MissingCapabilityError('Server does not support [%s]' %
303 bbd4ce54 Shikhar Bhushan
                                         capability)
304 0304f041 Shikhar Bhushan
    
305 a7cb58ce Shikhar Bhushan
    def deliver_reply(self, raw):
306 a7cb58ce Shikhar Bhushan
        # internal use
307 4de03d63 Shikhar Bhushan
        self._reply = self.REPLY_CLS(raw)
308 a7cb58ce Shikhar Bhushan
        self._event.set()
309 4f650d54 Shikhar Bhushan
310 a7cb58ce Shikhar Bhushan
    def deliver_error(self, err):
311 a7cb58ce Shikhar Bhushan
        # internal use
312 0cdb8b3c Shikhar Bhushan
        self._error = err
313 a7cb58ce Shikhar Bhushan
        self._event.set()
314 4f650d54 Shikhar Bhushan
315 4de03d63 Shikhar Bhushan
    @property
316 4de03d63 Shikhar Bhushan
    def reply(self):
317 a7cb58ce Shikhar Bhushan
        ":class:`RPCReply` element if reply has been received or :const:`None`"
318 4de03d63 Shikhar Bhushan
        return self._reply
319 4f650d54 Shikhar Bhushan
320 4de03d63 Shikhar Bhushan
    @property
321 a7cb58ce Shikhar Bhushan
    def error(self):
322 a7cb58ce Shikhar Bhushan
        """:exc:`Exception` type if an error occured or :const:`None`.
323 0304f041 Shikhar Bhushan
        
324 a7cb58ce Shikhar Bhushan
        .. note::
325 a7cb58ce Shikhar Bhushan
            This represents an error which prevented a reply from being
326 a7cb58ce Shikhar Bhushan
            received. An *<rpc-error>* does not fall in that category -- see
327 a7cb58ce Shikhar Bhushan
            :class:`RPCReply` for that.
328 a7cb58ce Shikhar Bhushan
        """
329 a7cb58ce Shikhar Bhushan
        return self._error
330 a7cb58ce Shikhar Bhushan
331 a7cb58ce Shikhar Bhushan
    @property
332 4de03d63 Shikhar Bhushan
    def id(self):
333 a7cb58ce Shikhar Bhushan
        "The *message-id* for this RPC"
334 4de03d63 Shikhar Bhushan
        return self._id
335 4f650d54 Shikhar Bhushan
336 4de03d63 Shikhar Bhushan
    @property
337 4de03d63 Shikhar Bhushan
    def session(self):
338 a7cb58ce Shikhar Bhushan
        """The :class:`~ncclient.transport.Session` object associated with this
339 a7cb58ce Shikhar Bhushan
        RPC"""
340 4de03d63 Shikhar Bhushan
        return self._session
341 4f650d54 Shikhar Bhushan
342 4de03d63 Shikhar Bhushan
    @property
343 a7cb58ce Shikhar Bhushan
    def event(self):
344 a7cb58ce Shikhar Bhushan
        """:class:`~threading.Event` that is set when reply has been received or
345 a7cb58ce Shikhar Bhushan
        error occured."""
346 a7cb58ce Shikhar Bhushan
        return self._event
347 a7cb58ce Shikhar Bhushan
348 a7cb58ce Shikhar Bhushan
    def set_async(self, async=True):
349 a7cb58ce Shikhar Bhushan
        """Set asynchronous mode for this RPC."""
350 a7cb58ce Shikhar Bhushan
        self._async = async
351 a7cb58ce Shikhar Bhushan
        if async and not session.can_pipeline:
352 a7cb58ce Shikhar Bhushan
            raise UserWarning('Asynchronous mode not supported for this device/session')
353 a7cb58ce Shikhar Bhushan
354 6c70b245 Shikhar Bhushan
    def set_raise_mode(self, mode):
355 9667bcb2 Shikhar Bhushan
        assert(choice in ("all", "errors", "none"))
356 6c70b245 Shikhar Bhushan
        self._raise_mode = mode
357 e0e01d37 Shikhar Bhushan
358 a7cb58ce Shikhar Bhushan
    def set_timeout(self, timeout):
359 9667bcb2 Shikhar Bhushan
        """Set the timeout for synchronous waiting; defining how long the RPC
360 9667bcb2 Shikhar Bhushan
        request will block on a reply before raising an error. Irrelevant for
361 9667bcb2 Shikhar Bhushan
        asynchronous usage."""
362 a7cb58ce Shikhar Bhushan
        self._timeout = timeout
363 4f650d54 Shikhar Bhushan
364 a7cb58ce Shikhar Bhushan
    #: Whether this RPC is asynchronous
365 9667bcb2 Shikhar Bhushan
    is_async = property(fget=lambda self: self._async, fset=set_async)
366 4f650d54 Shikhar Bhushan
367 a7cb58ce Shikhar Bhushan
    #: Timeout for synchronous waiting
368 4de03d63 Shikhar Bhushan
    timeout = property(fget=lambda self: self._timeout, fset=set_timeout)