Changeset 12861 for main/waeup.kofa/trunk/src/waeup/kofa/students/export.py

Timestamp:

17 Apr 2015, 14:43:42 (10 years ago)

Author:

Henrik Bettermann

Message:

More documentation.

File:

• main/waeup.kofa/trunk/src/waeup/kofa/students/export.py (modified) (16 diffs)

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

@@ -56 +56 @@
 def get_tickets(students, **kw):
     """Get course tickets of `students`.
-
     If code is passed through, filter course tickets
     which belong to this course code and meets level
@@ -89 +88 @@
 def get_payments(students, paid=False, **kw):
     """Get all payments of `students` within given payment_date period.
-
     """
     date_format = '%d/%m/%Y'
@@ -146 +144 @@
 class StudentExporterBase(ExporterBase):
     """Exporter for students or related objects.
-
     This is a baseclass.
     """
@@ -158 +155 @@
     def get_filtered(self, site, **kw):
         """Get students from a catalog filtered by keywords.
-
         students_catalog is the default catalog. The keys must be valid
         catalog index names.
@@ -192 +188 @@
     def get_selected(self, site, selected):
         """Get set of selected students.
-
         Returns a simple empty list or a list with `Student`
         objects.
@@ -206 +201 @@
     def export(self, values, filepath=None):
         """Export `values`, an iterable, as CSV file.
-
         If `filepath` is ``None``, a raw string with CSV data is returned.
         """
@@ -216 +210 @@
     def export_all(self, site, filepath=None):
         """Export students into filepath as CSV data.
-
         If `filepath` is ``None``, a raw string with CSV data is returned.
         """
@@ -226 +219 @@
     def export_filtered(self, site, filepath=None, **kw):
         """Export items denoted by `kw`.
-
         If `filepath` is ``None``, a raw string with CSV data should
         be returned.
@@ -242 +234 @@
 
 class StudentExporter(grok.GlobalUtility, StudentExporterBase):
-    """Exporter for Students.
+    """The Student Exporter first filters the set of students by searching the
+    students catalog. Then it exports student base data of this set of students.
     """
     grok.name('students')
 
-    #: Fieldnames considered by this exporter
     fields = tuple(sorted(iface_names(IStudent))) + (
         'password', 'state', 'history', 'certcode', 'is_postgrad',
         'current_level', 'current_session')
-
-    #: The title under which this exporter will be displayed
     title = _(u'Students')
 
     def mangle_value(self, value, name, context=None):
+        """The mangler prepares the history messages and adds a hash symbol at
+        the end of the phone number to avoid annoying automatic number
+        transformation by Excel or Calc."""
         if name == 'history':
             value = value.messages
@@ -267 +260 @@
 
 class StudentStudyCourseExporter(grok.GlobalUtility, StudentExporterBase):
-    """Exporter for StudentStudyCourses.
+    """The Student Study Course Exporter first filters the set of students
+    by searching the students catalog. Then it exports the data of the current
+    study course container of each student from this set. It does
+    not export their content.
     """
     grok.name('studentstudycourses')
 
-    #: Fieldnames considered by this exporter
     fields = tuple(sorted(iface_names(IStudentStudyCourse))) + ('student_id',)
-
-    #: The title under which this exporter will be displayed
     title = _(u'Student Study Courses')
 
@@ -281 +274 @@
 
     def mangle_value(self, value, name, context=None):
-        """Treat location values special.
+        """The mangler determines the certificate code and the student id.
         """
         if name == 'certificate' and value is not None:
@@ -295 +288 @@
 
 class StudentStudyLevelExporter(grok.GlobalUtility, StudentExporterBase):
-    """Exporter for StudentStudyLevels.
+    """The Student Study Level Exporter first filters the set of students
+    by searching the students catalog. Then it exports the data of the student's
+    study level containers but not their content (course tickets).
+    The exporter iterates over all objects in the students' ``studycourse``
+    containers.
     """
     grok.name('studentstudylevels')
 
-    #: Fieldnames considered by this exporter
     fields = tuple(sorted(iface_names(
         IStudentStudyLevel) + ['level'])) + (
         'student_id', 'number_of_tickets','certcode')
-
-    #: The title under which this exporter will be displayed
     title = _(u'Student Study Levels')
 
@@ -311 +305 @@
 
     def mangle_value(self, value, name, context=None):
-        """Treat location values special.
+        """The mangler determines the student id, nothing else.
         """
         if name == 'student_id' and context is not None:
@@ -321 +315 @@
 
 class CourseTicketExporter(grok.GlobalUtility, StudentExporterBase):
-    """Exporter for CourseTickets.
+    """The Course Ticket  Exporter exports course tickets. Usually,
+    the exporter first filters the set of students by searching the
+    students catalog. Then it collects and iterates over all ``studylevel``
+    containers of the filtered student set and finally
+    iterates over all items inside these containers.
+
+    If the course code is passed through, the exporter uses a different
+    catalog. It searches for students in the course tickets catalog and
+    exports those course tickets which belong to the given course code and
+    also meet level and level_session passed through at the same time.
+    This happens if the exporter is called at course level in the academics
+    section.
     """
     grok.name('coursetickets')
 
-    #: Fieldnames considered by this exporter
     fields = tuple(sorted(iface_names(ICourseTicket) +
         ['level', 'code', 'level_session'])) + ('student_id',
         'certcode', 'display_fullname')
-
-    #: The title under which this exporter will be displayed
     title = _(u'Course Tickets')
 
@@ -337 +339 @@
 
     def mangle_value(self, value, name, context=None):
-        """Treat location values special.
+        """The mangler determines the student's id and fullname.
         """
         if context is not None:
@@ -343 +345 @@
             if name in ('student_id', 'display_fullname') and student is not None:
                 value = getattr(student, name, None)
-            #if name == 'level':
-            #    value = getattr(context, 'level', lambda: None)
-            #if name == 'level_session':
-            #    value = getattr(context, 'level_session', lambda: None)
         return super(
             CourseTicketExporter, self).mangle_value(