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

Timestamp:

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

Author:

Henrik Bettermann

Message:

More documentation.

Location:

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

Files:

• applicants/export.py (modified) (4 diffs)
• students/export.py (modified) (16 diffs)
• utils/batching.py (modified) (7 diffs)

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

@@ -64 +64 @@
 
 class ApplicantExporter(grok.GlobalUtility, ExporterBase):
-    """The Applicant Exporter exports all application records (= applicants)
+    """The Applicant Exporter exports application records (= applicants)
     stored in the database. In contrast to the exporters in the academics
     section this exporter does not iterate over the items of containers
-    but searches the Applicants Catalog instead.
+    but searches the :class:`ApplicantsCatalog` instead.
+
+    The exporter exports all applicants if started in the Data Center
+    which means in the context of the `DataCenter` object. The exporter can also 
+    be started 'locally' which means in the context of an `ApplicantsContainer`
+    container. Then the :meth:`export_filtered()` instead of the 
+    :meth:`export_all()` method is applied which searches for applicants
+    in the respective container.
     """
     grok.implements(ICSVExporter)
@@ -98 +105 @@
     def export(self, applicants, filepath=None):
         """Export `applicants`, an iterable, as CSV file.
-
         If `filepath` is ``None``, a raw string with CSV data is returned.
         """
@@ -107 +113 @@
 
     def export_all(self, site, filepath=None):
-        """Export applicants into filepath as CSV data.
-
+        """Export all applicants into filepath as CSV data.
         If `filepath` is ``None``, a raw string with CSV data is returned.
         """
@@ -122 +127 @@
 
     def export_filtered(self, site, filepath=None, **kw):
-        """Export applicants in container.
-
+        """Export filtered applicants in container denoted by keywords (`kw`).
         If `filepath` is ``None``, a raw string with CSV data should
         be returned.

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(

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

@@ -493 +493 @@
     def close_outfile(self, filepath, outfile):
         """Close outfile.
-
         If filepath is None, the contents of outfile is returned.
         """
@@ -504 +503 @@
     def get_filtered(self, site, **kw):
         """Get datasets to export filtered by keyword arguments.
-
         Returns an iterable.
         """
@@ -512 +510 @@
         """Get datasets to export for selected items
         specified by a list of identifiers.
-
         Returns an iterable.
         """
@@ -519 +516 @@
     def export(self, iterable, filepath=None):
         """Export `iterable` as CSV file.
-
         If `filepath` is ``None``, a raw string with CSV data should
         be returned.
@@ -528 +524 @@
         """Export all appropriate objects in `site` into `filepath` as
         CSV data.
-
         If `filepath` is ``None``, a raw string with CSV data should
         be returned.
@@ -535 +530 @@
 
     def export_filtered(self, site, filepath=None, **kw):
-        """Export items denoted by `args` and `kw`.
-
+        """Export items denoted by `kw`.
         If `filepath` is ``None``, a raw string with CSV data should
         be returned.
@@ -546 +540 @@
         """Export those items specified by a list of identifiers
         called `selected`.
-
         If `filepath` is ``None``, a raw string with CSV data should
         be returned.