Changeset 12869 for main/waeup.kofa/trunk/src/waeup/kofa/university/batching.py

Timestamp:

22 Apr 2015, 19:14:14 (9 years ago)

Author:

Henrik Bettermann

Message:

Start documenting batch processors.

File:

• main/waeup.kofa/trunk/src/waeup/kofa/university/batching.py (modified) (9 diffs)

main/waeup.kofa/trunk/src/waeup/kofa/university/batching.py

@@ -44 +44 @@
 
 class FacultyProcessor(BatchProcessor):
-    """A batch processor for IFaculty objects.
+    """The Faculty Processor processes faculties in the `faculties` container.
+    The `FacultyProcessor` class also serves as a baseclass for all other 
+    batch processors in the academic section.
+
+    The processor makes some efforts to set local roles.
+    If new roles are provided, the `updateEntry` method first removes
+    all existing roles and then sets the new roles as given in the import
+    file. That means the entire set of local roles is replaced.
     """
     grok.implements(IBatchProcessor)
@@ -103 +110 @@
             role_map = IPrincipalRoleMap(obj)
             # Remove all existing local roles.
-            for local_role, user_name, setting in role_map.getPrincipalsAndRoles():
+            for local_role, user_name, setting in \
+                role_map.getPrincipalsAndRoles():
                 role_manager.unsetRoleForPrincipal(local_role, user_name)
                 notify(LocalRoleSetEvent(
@@ -114 +122 @@
                     local_role = rolemap['local_role']
                     role_manager.assignRoleToPrincipal(local_role, user)
-                    notify(LocalRoleSetEvent(obj, local_role, user, granted=True))
-                    items_changed += (
-                        '%s=%s, ' % ('local_roles', '%s|%s' % (user,local_role)))
+                    notify(LocalRoleSetEvent(
+                        obj, local_role, user, granted=True))
+                    items_changed += ('%s=%s, '
+                        % ('local_roles', '%s|%s' % (user,local_role)))
             row.pop('local_roles')
 
@@ -151 +160 @@
                 if not 'user_name' in rolemap.keys() or not \
                     'local_role' in rolemap.keys():
-                    errs.append(('local_roles','user_name or local_role missing'))
+                    errs.append((
+                        'local_roles','user_name or local_role missing'))
                     return errs, inv_errs, conv_dict
                 local_role = rolemap['local_role']
@@ -165 +175 @@
 
 class DepartmentProcessor(FacultyProcessor):
-    """A batch processor for IDepartment objects.
+    """The Department Processor works in the same way as the Faculty
+    Processor. Since department codes are not necessarily unique, it needs the
+    `faculty_code` to create and update objects.
     """
     grok.implements(IBatchProcessor)
@@ -213 +225 @@
 
 class CertificateProcessor(FacultyProcessor):
-    """A batch processor for ICertificate objects.
+    """The Certificate Processor gets the parent object (the
+    `certificates` attribute of the department container) in two ways.
+    If both faculty and department codes are provided, `getPartents` uses
+    these to locate the certificate. If department code or
+    faculty code are missing, it use the certificates catalog to find the
+    certificate.
     """
     grok.implements(IBatchProcessor)
@@ -270 +287 @@
             return dept.certificates
         # If department code or faculty code is missing,
-        # use catalog to get parent. Makes only sense in update mode but
-        # does also work in create mode.
+        # use catalog to get parent. 
         cat = queryUtility(ICatalog, name='certificates_catalog')
         results = list(
@@ -296 +312 @@
 
 class CourseProcessor(CertificateProcessor):
-    """A batch processor for ICourse objects.
+    """The Course Processor works exactly in the same way as the
+    Certificate Processor. It uses the courses catalog instead of the
+    certificates catalog.
     """
     grok.implements(IBatchProcessor)
@@ -343 +361 @@
 
 class CertificateCourseProcessor(FacultyProcessor):
-    """A batch processor for ICertificateCourse objects.
+    """The Certificate Course Processor needs more location fields.
+    Certificate courses are stored inside the certificate container.
+    Thus, `faculty_code`, `department_code` and the
+    `certificate_code` are necessary to find the parent container.
+    It furthermore needs the `course` and the `level` field to locate
+    existing objects as they are part of the object id (code).
     """
     grok.implements(IBatchProcessor)