Changeset 12835

Timestamp:

31 Mar 2015, 14:50:49 (10 years ago)

Author:

Henrik Bettermann

Message:

Add some docstrings.

Location:

main/waeup.kofa/trunk/src/waeup/kofa

Files:

• browser/pages.py (modified) (1 diff)
• permissions.py (modified) (5 diffs)

main/waeup.kofa/trunk/src/waeup/kofa/browser/pages.py

@@ -1106 +1106 @@
                          )
                     )
-            available_fields = sorted(available_fields, key=lambda k: k['f_name'])
+            available_fields = sorted(available_fields, key=lambda k: k[
+                'f_name'])
             importer_props.append(
                 dict(title=x.name, name=x.util_name, fields=available_fields))

main/waeup.kofa/trunk/src/waeup/kofa/permissions.py

@@ -23 +23 @@
 
 class Public(grok.Permission):
-    """Everyone-can-do-this-permission.
-
-    This permission is meant to be applied to objects/views/pages
-    etc., that should be usable/readable by everyone.
-
-    We need this to be able to tune default permissions more
-    restrictive and open up some dedicated objects like the front
-    page.
+    """The everyone-can-do-this-permission is being applied to views/pages
+    that are used by everyone.
     """
     grok.name('waeup.Public')
 
 class Anonymous(grok.Permission):
-    """Only-anonymous-can-do-this-permission.
+    """The waeup.Anonymous permission is applied to
+    views/pages which are dedicated to anonymous users only. Logged-in users
+    can't access these views.
     """
     grok.name('waeup.Anonymous')
 
 class Authenticated(grok.Permission):
-    """Only-logged-in-users-can-do-this-permission.
+    """The waeup.Authenticated permission is applied to pages
+    which can only be used by logged-in users and not by anonymous users.
     """
     grok.name('waeup.Authenticated')
 
-class ViewAcademicsPermission(grok.Permission):
+class ViewAcademics(grok.Permission):
+    """The waeup.viewAcademics permission is applied to all
+    views of the Academic Section. Users with this permission can view but
+    not edit content in the Academic Section.
+    """
     grok.name('waeup.viewAcademics')
 
-class ManageAcademicsPermission(grok.Permission):
+class ManageAcademics(grok.Permission):
+    """The waeup.manageAcademics permission is applied to all edit
+    pages in the Academic Section. Users who have this permission
+    can change/edit context objects.
+    """
     grok.name('waeup.manageAcademics')
 
 class ManagePortal(grok.Permission):
+    """The waeup.managePortal permission is used for very few pages
+    (e.g. the DatacenterSettings page) and is dedicated to portal managers.
+    It is furthermore used to control delete methods of container
+    pages in the Academic Section. The waeup.manageAcademics permission,
+    described above, does enable users to edit content but not to
+    remove sub-containers, like faculties, departments or certificates.
+    Users must have the waeup.managePorta permission too to remove
+    entire containers.
+    """
     grok.name('waeup.managePortal')
 
 class ManageUsers(grok.Permission):
+    """The waeup.manageUsers permission is a real superuser permission
+    and therefore very 'dangerous'. It allows to add, remove or edit
+    user accounts. Editing a user account includes the option to assign
+    or remove roles. That means that a user with this permission can lock out
+    other users by either removing their account or by removing all
+    permsissions. Only the system administrator will be able to revert this.
+    """
     grok.name('waeup.manageUsers')
 
 class ShowStudents(grok.Permission):
+    """Users with this permission can see the 'Students' tab and
+    search and browse all students. If they also have the waeup.exportData
+    permission they can export all student data too.
+
+    Bursary or Department Officers don't have the general waeup.exportData
+    permission (see Roles section) and are only allowed to export bursary
+    or payments overview data respectively.
+    """
     grok.name('waeup.showStudents')
 
 class ClearAllStudents(grok.Permission):
+    """The waeup.clearAllStudents permission allows to clear all students
+    in a department.
+    """
     grok.name('waeup.clearAllStudents')
 
 class EditScores(grok.Permission):
+    """The waeup.editScores permission allows to edit scores in course tickets.
+    """
     grok.name('waeup.editScores')
 
 class EditUser(grok.Permission):
+    """The waeup.editUser permission is required for editing
+    single user accounts.
+    """
     grok.name('waeup.editUser')
 
 class ManageDataCenter(grok.Permission):
+    """The waeup.manageDataCenter permission allows to access all pages
+    in the data center. It does not automatically allow to process data.
+    """
     grok.name('waeup.manageDataCenter')
 
 class ImportData(grok.Permission):
+    """The waeup.importData permission allows to import any kind of portal
+    data.
+    """
     grok.name('waeup.importData')
 
 class ExportData(grok.Permission):
+    """The waeup.exportData permission allows to export any kind of portal
+    data.
+    """
     grok.name('waeup.exportData')
 
@@ -87 +133 @@
 
 class ManagePortalConfiguration(grok.Permission):
+    """The waeup.managePortalConfiguration permission allows to
+    edit global and sessional portal configuration data.
+    """
     grok.name('waeup.managePortalConfiguration')
 
 class ManageACBatches(grok.Permission):
+    """The waeup.manageACBatches permission allows to view and
+    manage accesscodes.
+    """
     grok.name('waeup.manageACBatches')
 
 class PutBiometricDataPermission(grok.Permission):
-    """Permission to upload/change biometric data.
+    """This permission allows to upload/change biometric data.
     """
     grok.name('waeup.putBiometricData')
 
 class GetBiometricDataPermission(grok.Permission):
-    """Permission to read biometric data.
+    """This permission allows to read biometric data.
     """
     grok.name('waeup.getBiometricData')
@@ -281 +333 @@
     grok.name('waeup.AcademicsManager')
     grok.title(u'Academics Manager')
+    title = u'Academics Manager'
     grok.permissions('waeup.viewAcademics',
                      'waeup.manageAcademics')
@@ -325 +378 @@
 
 class PortalManager(grok.Role):
+    """The portal manager role is the maximum set of Kofa permissions
+    which are needed to manage the entire portal. This set must not
+    be changed or customized. It is recommended to assign this role only
+    to only a few portal administrators. A less dangerous manager role is the
+    CCOfficer role described below. For the most tasks the CCOfficer role
+    is sufficient.
+    """
     grok.name('waeup.PortalManager')
     grok.title(u'Portal Manager')
@@ -356 +416 @@
 
 class CCOfficer(grok.Role):
-    """This is basically a copy of the the PortalManager class. We exclude some
-    'dangerous' permissions by commenting them out.
+    """The Computer Center Officer role is basically a copy
+    of the the PortalManager role. Some 'dangerous' permissions are excluded
+    by commenting them out (see source code). If officers need to gain more
+    access rights than defined in this role, do not hastily switch to the
+    PortalManager role but add further manager roles instead. These additional
+    roles could be: UsersManager, ACManager, ImportManager, WorkflowManager
+    or StudentImpersonator.
     """
     grok.baseclass()