more doc updates

[ncclient] / ncclient / operations / lock.py

diff --git a/ncclient/operations/lock.py b/ncclient/operations/lock.py
index d6cef80..13f5bdb 100644 (file)
--- a/ncclient/operations/lock.py
+++ b/ncclient/operations/lock.py
@@ -1,4 +1,4 @@
-# Copyright 2009 Shikhar Bhushan
+# Copyright 2h009 Shikhar Bhushan
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,58 +12,59 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-'Locking-related NETCONF operations'
+"Locking-related NETCONF operations"
 
-from ncclient.rpc import RPC
+from ncclient.xml_ import *
 
-import util
+from rpc import RaiseMode, RPC
+
+# TODO: parse session-id from a lock-denied error, and raise a tailored exception?
 
 class Lock(RPC):
+
+    "`lock` RPC"
     
-    SPEC = {
-        'tag': 'lock',
-        'children': {
-            'tag': 'target',
-            'children': {'tag': None }
-        }
-    }
-    
-    def request(self, target='running'):
-        if target=='candidate':
-            self._assert(':candidate')
-        spec = Lock.SPEC.copy()
-        spec['children']['children']['tag'] = target
-        return self._request(spec)
+    def request(self, target):
+        """Allows the client to lock the configuration system of a device.
+
+        *target* is the name of the configuration datastore to lock
+        """
+        node = new_ele("lock")
+        sub_ele(sub_ele(node, "target"), target)
+        return self._request(node)
 
 
 class Unlock(RPC):
+
+    "`unlock` RPC"
     
-    SPEC = {
-        'tag': 'unlock',
-        'children': {
-            'tag': 'target',
-            'children': {'tag': None }
-        }
-    }
-    
-    def request(self, target='running'):
-        if target=='candidate':
-            self._assert(':candidate')
-        spec = Unlock.SPEC.copy()
-        spec['children']['children']['tag'] = target
-        return self._request(spec)
+    def request(self, target):
+        """Release a configuration lock, previously obtained with the lock operation.
+
+        *target* is the name of the configuration datastore to unlock
+        """
+        node = new_ele("unlock")
+        sub_ele(sub_ele(node, "target"), target)
+        return self._request(node)
 
 
 class LockContext:
-        
-    def __init__(self, session, target='running'):
+
+    """A context manager for the :class:`Lock` / :class:`Unlock` pair of RPC's.
+
+    Any `rpc-error` will be raised as an exception.
+
+    Initialise with (:class:`Session <ncclient.transport.Session>`) instance and lock target.
+    """
+
+    def __init__(self, session, target):
         self.session = session
         self.target = target
-        
+
     def __enter__(self):
-        Lock(self.session).request(self.target)
+        Lock(self.session, raise_mode=RaiseMode.ERRORS).request(self.target)
         return self
-    
-    def __exit__(self, t, v, tb):
-        Unlock(self.session).request(self.target)
+
+    def __exit__(self, *args):
+        Unlock(self.session, raise_mode=RaiseMode.ERRORS).request(self.target)
         return False