Add docs. Add clear_existing()

Signed-off-by: Andy Grover <agrover@redhat.com>

1 files changed, 23 insertions, 6 deletions

diff --git a/rtslib/root.py b/rtslib/root.py
index 033659b..b055c24 100644
--- a/rtslib/root.py
+++ b/rtslib/root.py
@@ -140,6 +140,11 @@ class RTSRoot(CFSNode):
     # RTSRoot public stuff
 
     def dump(self):
+        '''
+        Returns a dict representing the complete state of the target
+        config, suitable for serialization/deserialization, and then
+        handing to restore().
+        '''
         d = super(RTSRoot, self).dump()
         # backstores:storage_object is *usually* 1:1. In any case, they're an
         # implementation detail that the user doesn't need to care about.
@@ -154,15 +159,27 @@ class RTSRoot(CFSNode):
         d['targets'] = [t.dump() for t in self.targets]
         return d
 
-    def restore(self, config, clear_existing=False):
+    def clear_existing(self, confirm=False):
+        '''
+        Remove entire current configuration.
+        '''
+        if not confirm:
+            raise RTSLibError("As a precaution, confirm=True needs to be set")
 
+        # targets depend on storage objects, delete them first
+        for t in self.targets:
+            t.delete()
+        for so in self.storage_objects:
+            so.delete()
+
+    def restore(self, config, clear_existing=False):
+        '''
+        Takes a dict generated by dump() and reconfigures the target to match.
+        '''
         if clear_existing:
-            for so in self.storage_objects:
-                so.delete()
-            for t in self.targets:
-                t.delete()
+            self.clear_existing(confirm=True)
 
-        if not clear_existing and (self.backstores or self.targets):
+        if not clear_existing and (self.storage_objects or self.targets):
             raise RTSLibError("backstores or targets present, not restoring." +
                               " Set clear_existing=True?")