Changeset 12997

Timestamp:

23 May 2015, 22:37:39 (9 years ago)

Author:

Henrik Bettermann

Message:

More docs.

Location:

main/waeup.kofa/trunk

Files:

• docs/source/userdocs/datacenter/intro.rst (modified) (1 diff)
• docs/source/userdocs/students.rst (modified) (2 diffs)
• src/waeup/kofa/students/interfaces.py (modified) (8 diffs)
• src/waeup/kofa/utils/batching.py (modified) (1 diff)

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

@@ -84 +84 @@
   Although exporters are part of Kofa's batch processing module, we will
   not call them batch processors. Only importers are called batch
-  processors. Exporters produce CSV files, importer process them.
+  processors. Exporters produce CSV files, importers process them.
 
 

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

@@ -37 +37 @@
 ========
 
-The `Student` class is a container class which means, there are not only attributes describing the student but also content. Each student container contains exactly three sub-containers: ``studycourse``  (instance of `StudentStudyCourse`), ``payments`` (instance of `StudentPaymentsContainer`)  ``accommodation`` (instance of `StudentAccommodation`). The purposes of them are described further below.
+The `Student` class is a container class which means, there are not only attributes describing the student entity but also content. Each student container contains exactly three sub-containers: ``studycourse``  (instance of `StudentStudyCourse`), ``payments`` (instance of `StudentPaymentsContainer`)  ``accommodation`` (instance of `StudentAccommodation`). The purposes of them are described further below.
 
 Let's talk about the attributes and methods belonging to the `Student` class, the so-called 'external behaviour' of student objects specified in Zope 'interfaces'. The data stored with each student object are subdivided into three parts: base data, personal data and clearance data. Each part has its own interface.
@@ -43 +43 @@
 .. note::
 
-  Interfaces are one of the pillars of Zope's Component Architecture (ZCA, see also :ref:`prerequisites`). They document the 'external behaviour' of objects. In Kofa interfaces are used to specify the attributes, methods and schema fields of objects. The first two are well-known Python concepts. A Zope schema field is a bit more complicated. It's a detailed description of a field to be submitted via forms to the server, or which is processed by a batch processor. In both cases the input data are being validated against the schema. In Kofa, schema fields in interfaces are also used to automtically add `FieldProperty` attributes of the same name to most content classes. This is done by a function called :py:func:`attrs_to_fields<waeup.kofa.utils.helpers.attrs_to_fields>`. These class attributes ensure that corresponding attributes of instances of this class - when being added or changed - always meet the requirements of the schema. Another big advantage of such class attributes is, that attributes with a `FieldProperty` do not need to be set in `__init__` methods.
+  **Interfaces** are one of the pillars of Zope's Component Architecture (ZCA, see also :ref:`prerequisites`). They document the 'external behaviour' of objects. In Kofa interfaces are used to specify the attributes, methods and schema fields of objects. The first two are well-known Python concepts. A Zope schema field is a bit more complicated. It's a detailed description of a field to be submitted via forms to the server, or which is processed by a batch processor. In both cases the input data are being validated against the schema. In Kofa, schema fields in interfaces are also used to automtically add `FieldProperty` attributes of the same name to most content classes. This is done by a class function called :py:func:`attrs_to_fields<waeup.kofa.utils.helpers.attrs_to_fields>` during startup. These class attributes ensure that corresponding attributes of instances of this class - when being added or changed - always meet the requirements of the schema. Another big advantage of such class attributes is, that attributes with a `FieldProperty` do not need to be set in `__init__` methods.
+
+All student classes implement `waeup.kofa.students.interfaces.IStudent` which defines a base set of attributes, schema fields and methods all students must provide. This 'behaviour' is fundamental so that we quote and explain the source code here.
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentBase
+
+The first part of the interface lists attributes. Except for the first two (`password` and `temp_password`) they are all read-only property attributes, i.e. attributes with a getter method only. These properties are computed dynamically and can't be set. Most of them return data derived from the ``studycourse`` subobject.
+
+The second part of the interface specifies the schema fields, which are instances of schema classes with their `title`, `description`, `default`, `required`, `readonly` and `source` attributes.
 
 

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

@@ -72 +72 @@
 class IStudentsUtils(Interface):
     """A collection of methods which are subject to customization.
-
     """
     def setReturningData(student):
@@ -144 +143 @@
 class IStudentsContainer(IKofaObject):
     """A students container contains university students.
-
     """
     def addStudent(student):
         """Add an IStudent object and subcontainers.
-
         """
 
@@ -185 +182 @@
 class IStudentNavigation(IStudentNavigationBase):
     """Interface needed for student navigation, logging, etc.
-
     """
     student = Attribute('Student object of context.')
@@ -196 +192 @@
 class IStudentBase(IKofaObject):
     """Representation of student base data.
-
-    """
-    history = Attribute('Object history, a list of messages')
-    state = Attribute('Returns the registration state of a student')
-    password = Attribute('Encrypted password of a student')
+    """
+    password = Attribute('Encrypted password')
     temp_password = Attribute(
         'Dictionary with user name, timestamp and encrypted password')
-    certcode = Attribute('The certificate code of any chosen study course')
-    depcode = Attribute('The department code of any chosen study course')
-    faccode = Attribute('The faculty code of any chosen study course')
-    entry_session = Attribute('The entry session of the student')
-    current_session = Attribute('The current session of the student')
-    current_level = Attribute('The current level of the student')
-    current_mode = Attribute('The current mode of the student')
-    current_verdict = Attribute('The current verdict of the student')
+    history = Attribute('Object history, a list of messages')
+    state = Attribute('Registration state')
+    certcode = Attribute('Certificate code of any chosen study course')
+    depcode = Attribute('Department code of any chosen study course')
+    faccode = Attribute('Faculty code of any chosen study course')
+    entry_session = Attribute('Entry session')
+    current_session = Attribute('Current session')
+    current_level = Attribute('Current level')
+    current_mode = Attribute('Current mode')
+    current_verdict = Attribute('Current verdict')
     fullname = Attribute('All name parts separated by hyphens')
-    display_fullname = Attribute('The fullname of an applicant')
+    display_fullname = Attribute('Fullname as displayed on pages')
     is_postgrad = Attribute('True if postgraduate student')
+    is_special_postgrad = Attribute('True if special postgraduate student')
+    is_fresh = Attribute('True if fresh student')
+    before_payment = Attribute('True if no previous payment has to be made')
+    personal_data_expired = Attribute('True if personal data expired')
+    transcript_enabled = Attribute('True if transcript processing is enabled')
 
     suspended = schema.Bool(
@@ -286 +286 @@
         )
 
+    def writeLogMessage(view, message):
+        """Write formatted log message into student.log.
+        """
+
     def setTempPassword(user, password):
         """Set a temporary password (LDAP-compatible) SSHA encoded for
         officers.
-
         """
 
     def getTempPassword():
         """Check if a temporary password has been set and if it
-        is not expired.
-
-        Return the temporary password if valid,
+        is not expired. Return the temporary password if valid,
         None otherwise. Unset the temporary password if expired.
         """
@@ -303 +304 @@
         current_level, current_verdict):
         """ Creates a new studycourse and backups the old one.
-
+        """
+
+    def revert_transfer():
+        """ Revert previous transfer.
         """
 
 class IUGStudentClearance(IKofaObject):
     """Representation of undergraduate student clearance data.
-
     """
     officer_comment = schema.Text(
@@ -383 +386 @@
 class IStudentPersonalEdit(IStudentPersonal):
     """Interface for editing personal data by students.
-
     Here we can repeat the fields from IStudentPersonal and set the
     `required` if necessary.
@@ -395 +397 @@
 class IStudentUpdateByRegNo(IStudent):
     """Representation of a student. Skip regular reg_number validation.
-
     """
     reg_number = schema.TextLine(

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

@@ -297 +297 @@
         1. An empty row is skipped.
 
-        2. Empty strings in the row are replaced by ignore-markers.
+        2. Empty strings or lists (``[]``) in the row are replaced by
+           ignore markers.
 
         3. The `BatchProcessor.checkConversion` method validates and converts