Changeset 12859

Timestamp:

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

Author:

Henrik Bettermann

Message:

Add more exporter documentation.

Location:

main/waeup.kofa/trunk

Files:

• docs/source/userdocs/datacenter.rst (modified) (2 diffs)
• src/waeup/kofa/accesscodes/export.py (modified) (4 diffs)
• src/waeup/kofa/applicants/export.py (modified) (2 diffs)
• src/waeup/kofa/hostels/export.py (modified) (2 diffs)
• src/waeup/kofa/userscontainer.py (modified) (1 diff)

main/waeup.kofa/trunk/docs/source/userdocs/datacenter.rst

@@ -28 +28 @@
 Regular data exporters (1) collect objects from specific containers, (2) iterate over the collected objects, (3) extract and mangle information from each object, (4) write the information of each object into a row of a CSV file and (5) finally provide the file for download. The CSV file is neither stored in the database nor archived in the filesystem. (3) and (4) means a flattening of the hierarchical data structure, i.e. a mapping of objects to flat relational data to be stored in a CSV table. The extracted information must not necessarily be based only on static attributes of the collected object. The data, finally stored in the CSV file, can also be derived from parent or child objects, or dynamically computed by the object's methods and property attributes. These methods and properties can retrieve information from everywhere in the portal's database.
 
-In the following we list all exporter classes including the two attributes and a method description. The `fields` attribute contain the column titles of the export file. These are not necessarily only attributes of the exported objects. The `title` attribute unveils the name of the exporter under which this exporter will be displayed in the user interface. The `mangle_value()` method shows how some of fields are being dynamically computed.
+In the following we list all exporter classes including two attributes and a method description. The `fields` attribute contain the column titles of the export file. These are not necessarily only attributes of the exported objects. The `title` attribute unveils the name of the exporter under which this exporter will be displayed in the user interface. The `mangle_value()` method shows how some of fields are being dynamically computed.
 
-Academic Section Exporters
---------------------------
+Regular Exporters
+-----------------
+
+.. autoclass:: waeup.kofa.userscontainer.UserExporter()
+  :noindex:
+
+  .. autoattribute:: waeup.kofa.userscontainer.UserExporter.fields
+  .. autoattribute:: waeup.kofa.userscontainer.UserExporter.title
+  .. automethod:: waeup.kofa.userscontainer.UserExporter.mangle_value()
 
 .. autoclass:: waeup.kofa.university.export.FacultyExporter()
@@ -70 +77 @@
 
 
-Application Section Exporters
------------------------------
+.. autoclass:: waeup.kofa.applicants.export.ApplicantsContainerExporter()
+  :noindex:
+
+  .. autoattribute:: waeup.kofa.applicants.export.ApplicantsContainerExporter.fields
+  .. autoattribute:: waeup.kofa.applicants.export.ApplicantsContainerExporter.title
+
+.. autoclass:: waeup.kofa.applicants.export.ApplicantExporter()
+  :noindex:
+
+  .. autoattribute:: waeup.kofa.applicants.export.ApplicantExporter.fields
+  .. autoattribute:: waeup.kofa.applicants.export.ApplicantExporter.title
+  .. automethod:: waeup.kofa.applicants.export.ApplicantExporter.mangle_value()
+
+.. autoclass:: waeup.kofa.accesscodes.export.AccessCodeBatchExporter()
+  :noindex:
+
+  .. autoattribute:: waeup.kofa.accesscodes.export.AccessCodeBatchExporter.fields
+  .. autoattribute:: waeup.kofa.accesscodes.export.AccessCodeBatchExporter.title
+
+.. autoclass:: waeup.kofa.accesscodes.export.AccessCodeExporter()
+  :noindex:
+
+  .. autoattribute:: waeup.kofa.accesscodes.export.AccessCodeExporter.fields
+  .. autoattribute:: waeup.kofa.accesscodes.export.AccessCodeExporter.title
+  .. automethod:: waeup.kofa.accesscodes.export.AccessCodeExporter.mangle_value()
+
+.. autoclass:: waeup.kofa.hostels.export.HostelExporter()
+  :noindex:
+
+  .. autoattribute:: waeup.kofa.hostels.export.HostelExporter.fields
+  .. autoattribute:: waeup.kofa.hostels.export.HostelExporter.title
+
+.. autoclass:: waeup.kofa.hostels.export.BedExporter()
+  :noindex:
+
+  .. autoattribute:: waeup.kofa.hostels.export.BedExporter.fields
+  .. autoattribute:: waeup.kofa.hostels.export.BedExporter.title
 
 
-Student Section Exporters
--------------------------
+Student Data Exporters
+----------------------
 
 

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()