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

Timestamp:

16 Apr 2015, 18:49:08 (10 years ago)

Author:

Henrik Bettermann

Message:

Add more exporter documentation.

Location:

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

Files:

• accesscodes/export.py (modified) (4 diffs)
• applicants/export.py (modified) (2 diffs)
• hostels/export.py (modified) (2 diffs)
• userscontainer.py (modified) (1 diff)

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

@@ -27 +27 @@
 
 class AccessCodeBatchExporter(grok.GlobalUtility, ExporterBase):
-    """Exporter for accesscodebatches.
+    """The Access Code Batch Exporter exports container data. It does not
+    export access codes inside the container.
     """
     grok.implements(ICSVExporter)
     grok.name('accesscodebatches')
 
-    #: Fieldnames considered by this exporter
     fields = tuple(sorted(iface_names(IAccessCodeBatch))) + ('batch_id',)
-
-    #: The title under which this exporter will be displayed
     title = _(u'Access Code Batches')
 
@@ -48 +46 @@
     def export_all(self, site, filepath=None):
         """Export accesscode batches into filepath as CSV data.
-
         If `filepath` is ``None``, a raw string with CSV data is returned.
         """
@@ -57 +54 @@
         return self.close_outfile(filepath, outfile)
 
+
 class AccessCodeExporter(grok.GlobalUtility, ExporterBase):
-    """Exporter for courses.
+    """The Access Code Exporter exports all access codes stored in the
+    access code batch containers. The exporter iterates over all access code
+    batches and over all access codes inside each batch container.
     """
     grok.implements(ICSVExporter)
     grok.name('accesscodes')
 
-    #: Fieldnames considered by this exporter
     fields = tuple(sorted(iface_names(IAccessCode)))
-
-    #: The title under which this exporter will be displayed
     title = _(u'Access Codes')
 
     def mangle_value(self, value, name, context=None):
+        """The mangler adds a hash symbol at the end of ``random_num``
+        to avoid annoying automatic number transformation by Excel or Calc.
+        """
         if name == 'random_num' and value is not None:
             # Append hash '#' to numbers to circumvent
@@ -80 +80 @@
     def export_all(self, site, filepath=None):
         """Export accesscodes into filepath as CSV data.
-
         If `filepath` is ``None``, a raw string with CSV data is returned.
         """

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

@@ -29 +29 @@
 
 class ApplicantsContainerExporter(grok.GlobalUtility, ExporterBase):
-    """Exporter for ApplicantsContainers.
+    """The Applicants Container Exporter exports container data. It does not
+    export applicants (application records) inside the container.
     """
     grok.implements(ICSVExporter)
     grok.name('applicantscontainers')
 
-    #: Fieldnames considered by this exporter
     fields = tuple(sorted(iface_names(IApplicantsContainer)))
-    #: The title under which this exporter will be displayed
     title = _(u'Applicants Containers')
 
@@ -63 +62 @@
         return self.export(containers.values(), filepath)
 
+
 class ApplicantExporter(grok.GlobalUtility, ExporterBase):
-    """Exporter for Applicants.
+    """The Applicant Exporter exports all 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.
     """
     grok.implements(ICSVExporter)
     grok.name('applicants')
 
-    #: Fieldnames considered by this exporter
     fields = tuple(sorted(IApplicantBaseData.names())) + ('container_code',)
-
-    #: The title under which this exporter will be displayed
     title = _(u'Applicants')
 
     def mangle_value(self, value, name, context=None):
+        """The mangler determines the the codes of the atributes `course1`,
+        `course2` and `course_admitted`. It furthermore 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 in (
             'course1', 'course2', 'course_admitted') and value is not None:

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

@@ -26 +26 @@
 
 class HostelExporter(grok.GlobalUtility, ExporterBase):
-    """Exporter for hostels.
+    """The Hostel Exporter exports container data. It does not
+    export beds inside the container.
     """
     grok.implements(ICSVExporter)
     grok.name('hostels')
 
-    #: Fieldnames considered by this exporter
     fields = tuple(sorted(iface_names(IHostel))) 
-
-    #: The title under which this exporter will be displayed
     title = _(u'Hostels')
 
     def export_all(self, site, filepath=None):
         """Export hostels into filepath as CSV data.
-
         If `filepath` is ``None``, a raw string with CSV data is returned.
         """
@@ -48 +45 @@
         return self.close_outfile(filepath, outfile)
 
+
 class BedExporter(grok.GlobalUtility, ExporterBase):
-    """Exporter for courses.
+    """The Bed Exporter exports all beds stored in the
+    hostel containers. The exporter iterates over all hostels
+    and over all beds inside each hostel container.
     """
     grok.implements(ICSVExporter)
     grok.name('beds')
 
-    #: Fieldnames considered by this exporter
     fields = tuple(sorted(iface_names(IBed))) + (
         'hall', 'block', 'room', 'bed', 'special_handling', 'sex', 'bt')
-
-    #: The title under which this exporter will be displayed
     title = _(u'Beds')
 
     def export_all(self, site, filepath=None):
         """Export beds into filepath as CSV data.
-
         If `filepath` is ``None``, a raw string with CSV data is returned.
         """

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

@@ -62 +62 @@
 
 class UserExporter(grok.GlobalUtility, ExporterBase):
-    """Exporter for user accounts.
+    """The User Exporter exports all user accounts. It iterates over all
+    objects of the ``users`` container.
     """
     grok.implements(ICSVExporter)
     grok.name('users')
 
-    #: Fieldnames considered by this exporter
     fields = ('name', 'title', 'public_name', 'description',
               'email', 'phone', 'roles', 'local_roles', 'password')
-
-    #: The title under which this exporter will be displayed
     title = _(u'Users')
 
     def mangle_value(self, value, name, context=None):
-        """Treat location values special.
+        """The mangler determines the local roles each user has and computes
+        a Python expression like:
+
+        ``{u'waeup.local.ClearanceOfficer': [u'faculties/ABC/', u'faculties/DEF/']}``
         """
-
         if name == 'local_roles' and context is not None:
             local_roles = context.getLocalRoles()