check in latest updates to documentation

[sfa.git] / util / rights.py

diff --git a/util/rights.py b/util/rights.py
index ac5e0fc..92ab583 100644 (file)
--- a/util/rights.py
+++ b/util/rights.py
@@ -1,10 +1,18 @@
-# rights.py
+##
+# This Module implements rights and lists of rights for the Geni wrapper. Rights
+# are implemented by two classes:
 #
-# support for privileges according to GENI specification
-
-# privilege_table:
+# Right - represents a single right
+#
+# RightList - represents a list of rights
 #
-# a list of priviliges and what operations are allowed per privilege
+# A right may allow several different operations. For example, the "info" right
+# allows "listslices", "listcomponentresources", etc.
+##
+
+##
+# privilege_table is a list of priviliges and what operations are allowed
+# per privilege.
 
 privilege_table = {"authority": ["*"],
                    "refresh": ["remove", "update"],
@@ -16,12 +24,24 @@ privilege_table = {"authority": ["*"],
                    "info": ["listslices", "listcomponentresources", "getsliceresources"],
                    "ma": ["*"]}
 
-# a "Right" is a single privilege.
+##
+# The Right class represents a single privilege.
 
 class Right:
+   ##
+   # Create a new right.
+   #
+   # @param kind is a string naming the right. For example "control"
+
    def __init__(self, kind):
       self.kind = kind
 
+   ##
+   # Test to see if this right object is allowed to perform an operation.
+   # Returns True if the operation is allowed, False otherwise.
+   #
+   # @param op_name is a string naming the operation. For example "listslices".
+
    def can_perform(self, op_name):
       allowed_ops = privilege_table.get(self.kind.lower(), None)
       if not allowed_ops:
@@ -33,6 +53,13 @@ class Right:
 
       return (op_name.lower() in allowed_ops)
 
+   ##
+   # Test to see if this right is a superset of a child right. A right is a
+   # superset if every operating that is allowed by the child is also allowed
+   # by this object.
+   #
+   # @param child is a Right object describing the child right
+
    def is_superset(self, child):
       my_allowed_ops = privilege_table.get(self.kind.lower(), None)
       child_allowed_ops = privilege_table.get(child.kind.lower(), None)
@@ -46,19 +73,33 @@ class Right:
 
       return True
 
-# a "RightList" is a list of privileges
+##
+# A RightList object represents a list of privileges.
 
 class RightList:
+    ##
+    # Create a new rightlist object, containing no rights.
+    #
+    # @param string if string!=None, load the rightlist from the string
+
     def __init__(self, string=None):
         self.rights = []
         if string:
             self.load_from_string(string)
 
+    ##
+    # Add a right to this list
+    #
+    # @param right is either a Right object or a string describing the right
+
     def add(self, right):
         if isinstance(right, str):
             right = Right(kind = right)
         self.rights.append(right)
 
+    ##
+    # Load the rightlist object from a string
+
     def load_from_string(self, string):
         self.rights = []
 
@@ -70,6 +111,10 @@ class RightList:
         for part in parts:
             self.rights.append(Right(part))
 
+    ##
+    # Save the rightlist object to a string. It is saved in the format of a
+    # comma-separated list.
+
     def save_to_string(self):
         right_names = []
         for right in self.rights:
@@ -77,12 +122,27 @@ class RightList:
 
         return ",".join(right_names)
 
+    ##
+    # Check to see if some right in this list allows an operation. This is
+    # done by evaluating the can_perform function of each operation in the
+    # list.
+    #
+    # @param op_name is an operation to check, for example "listslices"
+
     def can_perform(self, op_name):
         for right in self.rights:
             if right.can_perform(op_name):
                 return True
         return False
 
+    ##
+    # Check to see if all of the rights in this rightlist are a superset
+    # of all the rights in a child rightlist. A rightlist is a superset
+    # if there is no operation in the child rightlist that cannot be
+    # performed in the parent rightlist.
+    #
+    # @param child is a rightlist object describing the child
+
     def is_superset(self, child):
         for child_right in child.rights:
             allowed = False