Changeset 12872 for main/waeup.kofa/trunk/src/waeup

Timestamp:

23 Apr 2015, 12:33:51 (10 years ago)

Author:

Henrik Bettermann

Message:

More docs.

Location:

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

Files:

• applicants/batching.py (modified) (1 diff)
• students/batching.py (modified) (5 diffs)

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

@@ -78 +78 @@
 
 class ApplicantProcessor(BatchProcessor):
-    """The Applicant Processor imports application records (applicants).
+    """The Applicant Processor imports application data (applicants).
 
     In create mode `container_code` is required. If `application_number` is

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

@@ -51 +51 @@
 
 class StudentProcessor(BatchProcessor):
-    """A batch processor for IStudent objects.
+    """The Student Processor imports student base data.
+
+    In create mode no locator is required. If no `student_id` is given,
+    the portal automatically assigns a new student id.
+
+    In update or remove mode the processor uses
+    either the `student_id`, `reg_number` or `matric_number` to localize the 
+    student object, exactly in this order. If `student_id` is given and an
+    object can be found, `reg_number` and `matric_number` will be overwritten
+    by the values provided in the import file. If `student_id` is missing,
+    `reg_number` is used to localize the object and only `matric_number`
+    will be overwritten. `matric_number` is used as locator only if both
+    `student_id` and `reg_number` are missing. `student_id` can't be changed
+    by the batch processor.
+
+    There are two ways to change the registration state of the student,
+    an unsafe and a safe way. The safe way makes use of workflow transitions.
+    Transitions are only possible between allowed workflow states. Only
+    transitions ensure that the registration workflow is maintained.
+
+    **Always prefer the safe way!**
     """
     grok.implements(IBatchProcessor)
@@ -397 +417 @@
 
 class StudentStudyCourseProcessor(StudentProcessorBase):
-    """A batch processor for IStudentStudyCourse objects.
+    """The Student Study Course Processor imports data which refer
+    to the student's course of study. The study course container data
+    describe the current state of the course of study and it stores the
+    entry conditions, i.e. when the student started the course.
+
+    Most important is the `certificate` attribute which tells us which course 
+    the student is studying. The terms 'study course' and 'course of study'
+    are used synonymously. The 'certificate' is the study programme described
+    in the acadmic section. The study course object stores a referrer to a
+    certificate in the acadmic section.
+
+    When importing a new certificate code, `checkConversion` does not only
+    check whether a certificate with the same code exists, it also
+    proves if `current_level` is inside the level range of the certificate.
+    For example, some study programmes start at level 200. The imported
+    current level must thus be 200 or higher.
+
+    `checkUpdateRequirements` looks up if the imported values match the
+    certificate already stored with the study course object. The imported
+    `current_level` must be in the range of the certificate already
+    stored.
+
+    .. note::
+
+      The processor does only offer an update mode. An 'empty' study course 
+      object is automatically created when the student object is added. So this
+      object always exists. It can neither be added a second time nor
+      be removed.
+
+    Students can be transferred by import. A transfer is initialized if the
+    `entry_mode` value is ``transfer``. In this case `checkConversion` uses a
+    different interface for data validation and `checkUpdateRequirements`
+    ensures that a student can only be transferred twice. The student transfer
+    process is described elsewhere.
     """
     grok.implements(IBatchProcessor)
@@ -465 +518 @@
     def checkUpdateRequirements(self, obj, row, site):
         """Checks requirements the object must fulfill when being updated.
-
         Returns error messages as strings in case of requirement
         problems.
@@ -494 +546 @@
 
 class StudentStudyLevelProcessor(StudentProcessorBase):
-    """A batch processor for IStudentStudyLevel objects.
+    """The Student Study Level Processor imports study level data.
+    It overwrites the container attributes but not the content of the container,
+    i.e. the course tickets stored inside the container. There is nothing
+    special about this processor.
     """
     grok.implements(IBatchProcessor)
@@ -561 +616 @@
         errs, inv_errs, conv_dict = super(
             StudentStudyLevelProcessor, self).checkConversion(row, mode=mode)
-
-        # We have to check if level is a valid integer.
-        # This is not done by the converter.
         try:
             level = int(row['level'])