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

Timestamp:

19 Apr 2015, 05:32:19 (10 years ago)

Author:

Henrik Bettermann

Message:

Finalize exporter documentation.

Location:

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

Files:

• applicants/export.py (modified) (1 diff)
• browser/pages.py (modified) (1 diff)
• permissions.py (modified) (2 diffs)
• students/export.py (modified) (17 diffs)
• university/vocabularies.py (modified) (1 diff)

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

@@ -65 +65 @@
 class ApplicantExporter(grok.GlobalUtility, ExporterBase):
     """The Applicant Exporter exports application records (= applicants)
-    stored in the database. In contrast to the exporters in the academics
+    stored in the database. In contrast to the exporters in the academic
     section this exporter does not iterate over the items of containers
     but searches the :class:`ApplicantsCatalog` instead.

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

@@ -741 +741 @@
 
 class SearchPage(KofaPage):
-    """General search page for the academics section.
+    """General search page for the academic section.
     """
     grok.context(IFacultiesContainer)

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

@@ -377 +377 @@
 class AcademicsOfficer(grok.Role):
     """An Academics Officer can view but not edit data in the
-    Academics Section. 
+    academic section.
 
     This is the default role which is automatically assigned to all
@@ -389 +389 @@
 class AcademicsManager(grok.Role):
     """An Academics Manager can view and edit all data in the
-    Academics Section, i.e. access all manage pages
+    scademic section, i.e. access all manage pages
     at faculty, department, course, certificate and certificate course level.
     """

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

@@ -290 +290 @@
     """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).
+    study level container data but not their content (course tickets).
     The exporter iterates over all objects in the students' ``studycourse``
     containers.
@@ -325 +325 @@
     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
+    This happens if the exporter is called at course level in the academic
     section.
     """
@@ -351 +351 @@
 
 class StudentPaymentsExporter(grok.GlobalUtility, StudentExporterBase):
-    """Exporter for OnlinePayment instances.
+    """The Student Payments Exporter first filters the set of students
+    by searching the students catalog. Then it exports student payment
+    tickets by iterating over the items of the student's ``payments``
+    container. If the payment period is given only tickets, which were
+    paid in payment period, are considered for export.
     """
     grok.name('studentpayments')
 
-    #: Fieldnames considered by this exporter
     fields = tuple(
         sorted(iface_names(
@@ -361 +364 @@
             omit=['display_item']))) + (
             'student_id','state','current_session')
-
-    #: The title under which this exporter will be displayed
     title = _(u'Student Payments')
 
@@ -369 +370 @@
 
     def mangle_value(self, value, name, context=None):
-        """Treat location values special.
+        """The mangler determines the student's id, registration
+        state and current session.
         """
         if context is not None:
@@ -381 +383 @@
 
 class DataForBursaryExporter(StudentPaymentsExporter):
-    """Exporter for OnlinePayment instances.
+    """The DataForBursary Exporter works just like the Student Payments Exporter
+    but it exports much more information about the student. It combines
+    payment and student data in one table in order to spare postprocessing of 
+    two seperate export files. The exporter is primarily used by bursary
+    officers who have exclusively access to this exporter.
     """
     grok.name('bursary')
@@ -388 +394 @@
         return get_payments(x, paid=True, **kw)
 
-    #: Fieldnames considered by this exporter
     fields = tuple(
         sorted(iface_names(
@@ -398 +403 @@
             'entry_session', 'entry_mode',
             'faccode', 'depcode','certcode')
-
-    #: The title under which this exporter will be displayed
     title = _(u'Payment Data for Bursary')
 
     def mangle_value(self, value, name, context=None):
-        """Treat location values special.
+        """The mangler fetches the student data.
         """
         if context is not None:
@@ -419 +422 @@
 
 class BedTicketsExporter(grok.GlobalUtility, StudentExporterBase):
-    """Exporter for BedTicket instances.
+    """The Bed Tickets Exporter first filters the set of students
+    by searching the students catalog. Then it exports bed
+    tickets by iterating over the items of the student's ``accommodation``
+    container.
     """
     grok.name('bedtickets')
 
-    #: Fieldnames considered by this exporter
     fields = tuple(
         sorted(iface_names(
@@ -429 +434 @@
             omit=['display_coordinates']))) + (
             'student_id', 'actual_bed_type')
-
-    #: The title under which this exporter will be displayed
     title = _(u'Bed Tickets')
 
@@ -437 +440 @@
 
     def mangle_value(self, value, name, context=None):
-        """Treat location values and others special.
+        """The mangler determines the student id and the type of the bed
+        which has been booked in the ticket.
         """
         if context is not None:
@@ -452 +456 @@
 
 class StudentPaymentsOverviewExporter(StudentExporter):
-    """Exporter for students with payment overview.
+    """The Student Payments Overview Exporter first filters the set of students
+    by searching the students catalog. Then it exports some student base data
+    together with the total school fee amount paid in each year over a
+    predefined year range (current year - 9, ... , current year + 1).
     """
     grok.name('paymentsoverview')
@@ -460 +467 @@
     year_range_tuple = tuple([str(year) for year in year_range])
 
-    #: Fieldnames considered by this exporter
     fields = ('student_id', 'matric_number', 'display_fullname',
         'state', 'certcode', 'faccode', 'depcode', 'is_postgrad',
         'current_level', 'current_session', 'current_mode',
         ) + year_range_tuple
-
-    #: The title under which this exporter will be displayed
     title = _(u'Student Payments Overview')
 
     def mangle_value(self, value, name, context=None):
+        """The mangler summarizes the school fee amounts made per year. It
+        iterates over all paid school fee payment tickets and
+        adds together the amounts paid in a year. Waived payments
+        are marked ``waived``.
+        """
         if name in self.year_range_tuple and context is not None:
             value = 0
@@ -490 +499 @@
 
 class StudentStudyLevelsOverviewExporter(StudentExporter):
-    """Exporter for students with study level overview.
+    """The Student Study Levels Overview Exporter first filters the set of
+    students by searching the students catalog. Then it exports some student
+    base data together with the session key of registered levels.
+    Sample output:
+
+    header: ``...100,110,120,200,210,220,300...``
+
+    data: ``...2010,,,2011,2012,,2013...``
+
+    This csv data string means that level 100 was registered in session 
+    2010/2011, level 200 in session 2011/2012, level 210 (200 on 1st probation)
+    in session 2012/2013 and level 300 in session 2013/2014.
     """
     grok.name('studylevelsoverview')
@@ -496 +516 @@
     avail_levels = tuple([str(x) for x in study_levels(None)])
 
-    #: Fieldnames considered by this exporter
     fields = ('student_id', ) + (
         'state', 'certcode', 'faccode', 'depcode', 'is_postgrad',
         'entry_session', 'current_level', 'current_session',
         ) + avail_levels
-
-    #: The title under which this exporter will be displayed
     title = _(u'Student Study Levels Overview')
 
     def mangle_value(self, value, name, context=None):
+        """The mangler checks if a given level has been registered. It returns
+        the ``level_session`` attribute of the student study level object
+        if the named level exists.
+        """
         if name in self.avail_levels and context is not None:
             value = ''
             for level in context['studycourse'].values():
                 if level.level == int(name):
-                    #value = '%s|%s|%s|%s' % (
-                    #    level.level_session,
-                    #    len(level),
-                    #    level.validated_by,
-                    #    level.level_verdict)
                     value = '%s' % level.level_session
                     break
@@ -522 +538 @@
 
 class ComboCardDataExporter(grok.GlobalUtility, StudentExporterBase):
-    """Exporter for Interswitch Combo Card Data.
+    """Like all other exporters the Combo Card Data Exporter first filters the
+    set of students by searching the students catalog. Then it exports some
+    student base data which are neccessary to print for the Interswitch combo 
+    card (identity card for students). The output contains a ``passport_path``
+    column which contains the filesystem path of the passport image file.
+    If no path is given, no passport image file exists.
     """
     grok.name('combocard')
 
-    #: Fieldnames considered by this exporter
     fields = ('display_fullname',
               'student_id','matric_number',
               'certificate', 'faculty', 'department', 'passport_path')
-
-    #: The title under which this exporter will be displayed
     title = _(u'Combo Card Data')
 
     def mangle_value(self, value, name, context=None):
+        """The mangler determines the titles of faculty, department
+        and certificate. It also computes the path of passport image file
+        stored in the filesystem.
+        """
         certificate = context['studycourse'].certificate
         if name == 'certificate' and certificate is not None:
@@ -543 +565 @@
             value = certificate.__parent__.__parent__.__parent__.longtitle
         if name == 'passport_path' and certificate is not None:
-            file_id = IFileStoreNameChooser(context).chooseName(attr='passport.jpg')
+            file_id = IFileStoreNameChooser(context).chooseName(
+                attr='passport.jpg')
             os_path = getUtility(IExtFileStore)._pathFromFileID(file_id)
             if not os.path.exists(os_path):

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

@@ -16 +16 @@
 ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 ##
-"""Vocabularies and sources for the academics section.
+"""Vocabularies and sources for the academic section.
 """
 from zc.sourcefactory.basic import BasicSourceFactory