docstrings + some clean up

git-svn-id: https://svn.erp5.org/repos/public/erp5/sandbox/portal_types@29252 20353a03-c40f-0410-a6d1-a30d3c3de9de

product/ERP5Security/ERP5GroupManager.py

@@ -24,6 +24,8 @@ from Products.PluggableAuthService.plugins.BasePlugin import BasePlugin
 from Products.PluggableAuthService.utils import classImplements
 from Products.PluggableAuthService.interfaces.plugins import IGroupsPlugin
 from Products.ERP5Type.Cache import CachingMethod
+from Products.ERP5Type.ERP5Type \
+  import ERP5TYPE_SECURITY_GROUP_ID_GENERATION_SCRIPT
 from Products.PluggableAuthService.PropertiedUser import PropertiedUser
 from ZODB.POSException import ConflictError
 
@@ -154,15 +156,14 @@ class ERP5GroupManager(BasePlugin):
                 error = sys.exc_info())
 
         # Get group names from category values
-        group_id_list_generator = getattr(self,
-                                      'ERP5Type_asSecurityGroupIdList', None)
+        # XXX try ERP5Type_asSecurityGroupIdList first for compatibility
+        generator_name = 'ERP5Type_asSecurityGroupIdList'
+        group_id_list_generator = getattr(self, generator_name, None)
         if group_id_list_generator is None:
-          group_id_list_generator = getattr(self, 'ERP5Type_asSecurityGroupId')
-          generator_name = "ERP5Type_asSecurityGroupId"
-        else:
-          generator_name = 'ERP5Type_asSecurityGroupIdList'
+          generator_name = ERP5TYPE_SECURITY_GROUP_ID_GENERATION_SCRIPT
+          group_id_list_generator = getattr(self, generator_name)
         for base_category_list, category_value_list in \
-            security_category_dict.items():
+            security_category_dict.iteritems():
           for category_dict in category_value_list:
             try:
               group_id_list = group_id_list_generator(

product/ERP5Type/Core/ActionInformation.py

@@ -62,56 +62,61 @@ class ActionInformation(XMLObject):
                     )
 
   def testCondition(self, ec):
-    """ Evaluate condition using context, 'ec', and return 0 or 1."""
+    """Evaluate condition using context, 'ec', and return 0 or 1"""
     condition = self.getCondition()
     return condition is None and 1 or condition(ec)
 
   security.declarePublic('getVisibility')
   def getVisibility(self):
-    """ Return whether the action should be visible in the CMF UI."""
+    """Return whether the action should be visible in the CMF UI"""
     return self.isVisible()
 
   def _setActionExpression(self, value):
+    """Overridden setter for 'action' to accept strings and clean null values
+    """
     if isinstance(value, basestring):
       value = value and Expression(value) or None
     self._baseSetActionExpression(value)
   def _setCondition(self, value):
+    """Overridden setter for 'condition' to accept string and clean null values
+    """
     if isinstance(value, basestring):
       value = value and Expression(value) or None
     self._baseSetCondition(value)
   def _setIcon(self, value):
+    """Overridden setter for 'icon' to accept string and clean null values
+    """
     if isinstance(value, basestring):
       value = value and Expression(value) or None
     self._baseSetIcon(value)
 
   def getCondition(self):
+    """Overridden getter for 'condition' to clean null values"""
     if getattr(aq_base(self), 'condition', None) == '':
       del self.condition
     return self._baseGetCondition()
   def getIcon(self):
+    """Overridden getter for 'icon' to clean null values"""
     if getattr(aq_base(self), 'icon', None) == '':
       del self.icon
     return self._baseGetIcon()
 
   security.declareProtected(AccessContentsInformation, 'getActionText')
   def getActionText(self):
-    """
-    """
+    """Return the text of the action expression"""
     return getattr(self.getActionExpression(), 'text', None)
   security.declareProtected(AccessContentsInformation, 'getConditionText')
   def getConditionText(self):
-    """
-    """
+    """Return the text of the condition expression"""
     return getattr(self.getCondition(), 'text', None)
   security.declareProtected(AccessContentsInformation, 'getIconText')
   def getIconText(self):
-    """
-    """
+    """Return the text of the icon expression"""
     return getattr(self.getIcon(), 'text', None)
 
   security.declareProtected(AccessContentsInformation, 'PrincipiaSearchSource')
   def PrincipiaSearchSource(self):
-    # Support for "Find" tab in ZMI
+    """Return keywords for "Find" tab in ZMI"""
     search_source_list = [self.getReference(),
                           self.getTitle(),
                           self.getDescription(),

product/ERP5Type/Core/RoleInformation.py

@@ -51,36 +51,44 @@ class RoleInformation(XMLObject):
 
   security.declarePrivate('testCondition')
   def testCondition(self, ec):
-    """ Evaluate condition using context, 'ec', and return 0 or 1."""
+    """Evaluate condition using context, 'ec', and return 0 or 1"""
     condition = self.getCondition()
     return condition is None and 1 or condition(ec)
 
   def _setCondition(self, value):
+    """Overridden setter for 'condition' to accept string and clean null values
+    """
     if isinstance(value, basestring):
-      value = Expression(value)
+      value = value and Expression(value) or None
     self._baseSetCondition(value)
 
   def getCondition(self):
+    """Overridden getter for 'condition' to clean null values"""
     if getattr(aq_base(self), 'condition', None) == '':
       del self.condition
     return self._baseGetCondition()
 
   security.declareProtected(AccessContentsInformation, 'getConditionText')
   def getConditionText(self):
-    """
-    """
+    """Return the text of the condition"""
     return getattr(self.getCondition(), 'text', None)
 
+  security.declareProtected(AccessContentsInformation, 'PrincipiaSearchSource')
   def PrincipiaSearchSource(self):
-    # Support for "Find" tab in ZMI
-    return ' '.join((self.getId(),
-                     self.getTitle(),
-                     self.getDescription(),
-                     self.getCondition(),
-                     self.base_category_script))
-
-  security.declareProtected(AccessContentsInformation, 'getGroupIdRoleList')
+    """Return keywords for "Find" tab in ZMI"""
+    search_source_list = [self.getReference(),
+                          self.getTitle(),
+                          self.getDescription(),
+                          self.getConditionText(),
+                          self.getRoleBaseCategoryScriptId()]
+    return ' '.join(filter(None, search_source_list))
+
+  security.declarePrivate('getGroupIdRoleList')
   def getGroupIdRoleList(self, ob, user_name=None):
+    """Generate security groups (with roles) to be set on a document
+
+    Each returned value is a 2-tuple (group_id, role_name_list).
+    """
     # get the list of base_categories that are statically defined
     static_base_category_list = [x.split('/', 1)[0]
                                  for x in self.getRoleCategoryList()]

product/ERP5Type/ERP5Type.py

@@ -377,9 +377,12 @@ class ERP5TypeInformation(XMLObject,
       if reindex:
         ob.reindexObjectSecurity()
 
-    security.declareProtected(Permissions.AccessContentsInformation,
-                              "getGroupIdRoleDict")
+    security.declarePrivate("getGroupIdRoleDict")
     def getGroupIdRoleDict(self, ob, user_name=None):
+      """Compute the security that should be applied on an object
+
+      Returned value is a dict: {groud_id: role_name_set, ...}
+      """
       group_id_role_dict = {}
         for roledef in ob.objectValues(portal_type='Role Definition'):
       # Retrieve and parse applicable roles
@@ -390,7 +393,7 @@ class ERP5TypeInformation(XMLObject,
 
     security.declarePrivate('getFilteredRoleListFor')
     def getFilteredRoleListFor(self, ob=None):
-      """Return all roles applicable to the object against user."""
+      """Return all roles applicable to the object."""
       portal = self.getPortalObject()
       if ob is None:
         folder = portal
@@ -471,7 +474,7 @@ class ERP5TypeInformation(XMLObject,
     security.declareProtected(Permissions.AccessContentsInformation,
                               'PrincipiaSearchSource')
     def PrincipiaSearchSource(self):
-      # Support for "Find" tab in ZMI
+     """Return keywords for "Find" tab in ZMI"""
       search_source_list = [self.getId(),
                             self.getTypeFactoryMethodId(),
                             self.getTypeAddPermission(),
@@ -481,14 +484,16 @@ class ERP5TypeInformation(XMLObject,
       return ' '.join(filter(None, search_source_list))
 
 
-    security.declarePrivate('getRoleInformationList')
+    security.declareProtected(Permissions.AccessContentsInformation,
+                              'getRoleInformationList')
     def getRoleInformationList(self):
-      """Return all roles for this portal type"""
+      """Return all Role Information objects stored on this portal type"""
       return self.objectValues(portal_type='Role Information')
 
-    security.declarePrivate('getActionInformationList')
+    security.declareProtected(Permissions.AccessContentsInformation,
+                              'getActionInformationList')
     def getActionInformationList(self):
-      """Return all actions for this portal type"""
+      """Return all Action Information objects stored on this portal type"""
       return self.objectValues(portal_type='Action Information')
 
     def getIcon(self):