Changeset 12999 for main

Timestamp:

25 May 2015, 20:50:37 (9 years ago)

Author:

Henrik Bettermann

Message:

More docs.

Location:

main/waeup.kofa/trunk

Files:

• docs/source/userdocs/students.rst (modified) (3 diffs)
• src/waeup/kofa/students/interfaces.py (modified) (24 diffs)

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 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.
+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`)  and ``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.
@@ -45 +45 @@
 .. 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 field. 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 field. 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 field requirements. In Kofa, schema fields (see also note below) in interfaces are also used to automtically add `FieldProperty` attributes of the same name to most content classes. This is done by a function :py:func:`attrs_to_fields<waeup.kofa.utils.helpers.attrs_to_fields>` which is called once during startup of Kofa. These class attributes ensure that corresponding attributes of instances of this class - when being added or changed - always meet the requirements of the schema field. 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.
+The `Student` class implements several interfaces which we will quote to unveil the student's 'external behaviour'.
+
+`IStudentBase`
+--------------
+
+`waeup.kofa.students.interfaces.IStudentBase` defines a fundamental set of attributes, schema fields and methods which are being used throughout the portal. This set is immutable. No class statement must be removed or added in customized versions of Kofa.
 
 .. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
@@ -70 +75 @@
 The **third part** of the interface lists the methods which can be applied to student objects.
 
+`IUGStudentClearance`
+---------------------
+
+Much like all the following student interfaces, `waeup.kofa.students.interfaces.IUGStudentClearance` describes an additional set of schema fields which are exclusively used on form pages. They do not play any role beyond that purpose. Any kind of schema field can be safely added in customized versions of these interfaces to meet the conditions of the university's matriculation process. Also `date_of_birth` and `nationality` are not used in the base package for further data processing which means, there is no dependency on these two parameters. Attention: This might be different in customized versions of Kofa. Some views might use these parameters to restrict access or make actions (e.g. payment of items) conditional on the student's nationality or current age.
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IUGStudentClearance
+
+`clearance_locked` controls the access to the edit form page of clearance data. The corresponding attribute is automatically set by workflow transitions to lock or unlock the edit form page respectively. The attribute can also be set by officers via the manage form page to lock or unlock the page manually.
+
+`officer_comment` is usually edited by clearance officers when rejecting clearance previously requested by the student. The attribute contains the message which informs the student about the reasons of rejection. The attribute is cleared after final clearance. The message can be also found in ``students.log``.
+
+Both `clearance_locked` and `officer_comment` are controlled by workflow transitions not by states, see below.
+
+`IPGStudentClearance`
+---------------------
+
+Most universities acquire different data from undergraduate (UG) and postgraduate (PG) students. The forms vary widely. Therefore Kofa offers a second interface for acquiring PG clearance data. In the base package `IPGStudentClearance` inherits from the `IUGStudentClearance` interface. The additional `employer` field in the base package only serves as an example.
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IPGStudentClearance
+
+`IStudentPersonal`
+------------------
+
+`waeup.kofa.students.interfaces.IUGStudentPersonal` defines an additional set of personal student data which are permantly editable by students. The set usually contains further contact data and information about the student's relatives.
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentPersonal
+
+Kofa provides a mechanism which ensures that personal data are being kept up to date. Students are regularly requested to update the personal data directly after login. The personal data expire 180 days after saving the data for the last time which is stored in the `personal_updated` attribute. Then the `personal_data_expired` property returns ``True`` and the student is redirected to the personal data edit page when logging in.
 
 Student Study Courses
 =====================
 
+All data related to the student's course of study are stored with the ``studycourse`` object which is an instance of the `StudentStudyCourse` class. The latter implements `waeup.kofa.students.interfaces.IStudentStudyCourse`.
+
+`IStudentStudyCourse`
+---------------------
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentStudyCourse
+
 Student Study Levels
+====================
+
+`IStudentStudyLevel`
 --------------------
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentStudyLevel
+
+`ICourseTicket`
+---------------
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: ICourseTicket
 
 Student Payments
 ================
 
+`IStudentOnlinePayment`
+-----------------------
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentOnlinePayment
+
 Student Accommodation
 =====================
 
+`IBedTicket`
+------------
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IBedTicket
+
+
+Registration Workflow
+=====================
+
+Browser Pages
+=============
+
 
 .. _zope schema: http://docs.zope.org/zope.schema

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

@@ -122 +122 @@
     def getAccommodation_details(student):
         """Determine the accommodation dates of a student.
-
         """
 
     def selectBed(available_beds):
         """Select a bed from a list of available beds.
-
         In the standard configuration we select the first bed found,
         but can also randomize the selection if we like.
@@ -138 +136 @@
     def renderPDF(view, subject='', filename='slip.pdf',):
         """Render pdf slips for various pages.
-
         """
 
@@ -194 +191 @@
     """
     password = Attribute('Encrypted password')
-    temp_password = Attribute(
-        'Dictionary with user name, timestamp and encrypted password')
+    temp_password = Attribute('Dictionary with user name, timestamp and encrypted password')
     history = Attribute('Object history, a list of messages')
     state = Attribute('Registration state')
@@ -287 +283 @@
 
     def writeLogMessage(view, message):
-        """Write formatted log message into student.log.
+        """Write formatted log message into students.log.
         """
 
@@ -344 +340 @@
 class IPGStudentClearance(IUGStudentClearance):
     """Representation of postgraduate student clearance data.
-
     """
     employer = schema.TextLine(
@@ -354 +349 @@
 class IStudentPersonal(IKofaObject):
     """Representation of student personal data.
-
     """
     personal_updated = schema.Datetime(
@@ -369 +363 @@
 class IStudentTranscript(IKofaObject):
     """Representation of student transcript data.
-
     """
 
@@ -381 +374 @@
     IStudentPersonal, IStudentTranscript):
     """Representation of a student.
-
     """
 
@@ -405 +397 @@
 class IStudentUpdateByMatricNo(IStudent):
     """Representation of a student. Skip regular matric_number validation.
-
     """
     matric_number = schema.TextLine(
@@ -413 +404 @@
 
 class IStudentRequestPW(IStudent):
-    """Representation of an student for first-time password request.
-
+    """Representation of a student for first-time password request.
     This interface is used when students use the requestpw page to
     login for the the first time.
@@ -435 +425 @@
 
 class IStudentStudyCourse(IKofaObject):
-    """A container for student study levels.
-
+    """Representation of student study course data.
     """
     certificate = schema.Choice(
@@ -488 +477 @@
 
 class IStudentStudyCourseTransfer(IStudentStudyCourse):
-    """An student transfers.
-
-    """
-
+    """An interface used for student transfers.
+    """
     certificate = schema.Choice(
         title = _(u'Certificate'),
@@ -521 +508 @@
 class IStudentStudyCourseTranscript(IKofaObject):
     """An interface for student transcripts.
-
-    """
-
+    """
     entry_mode = schema.Choice(
         title = _(u'Entry Mode'),
@@ -541 +526 @@
 class IStudentVerdictUpdate(IKofaObject):
     """A interface for verdict imports.
-
-    """
-
+    """
     current_verdict = schema.Choice(
         title = _(u'Current Verdict'),
@@ -573 +556 @@
 
 class IStudentStudyLevel(IKofaObject):
-    """A container for course tickets.
-
+    """A representation of student study level data. 
     """
     number_of_tickets = Attribute('Number of tickets contained in this level')
@@ -635 +617 @@
 
 class ICourseTicket(IKofaObject):
-    """An interface for course tickets.
-
+    """A representation of course ticket data.
     """
     code = Attribute('code of the original course')
@@ -705 +686 @@
 class ICourseTicketAdd(IKofaObject):
     """An interface for adding course tickets.
-
     """
     course = schema.Choice(
@@ -715 +695 @@
 class ICourseTicketImport(ICourseTicket):
     """An interface for importing course results and nothing more.
-
     """
     score = schema.Int(
@@ -732 +711 @@
 class IStudentAccommodation(IKofaObject):
     """A container for student accommodation objects.
-
     """
 
@@ -741 +719 @@
 
 class IBedTicket(IKofaObject):
-    """A ticket for accommodation booking.
-
+    """A representation of accommodation booking data.
     """
     bed = Attribute('The bed object.')
@@ -785 +762 @@
     def getSessionString():
         """Returns the title of academic_sessions_vocab term.
-
         """
 
 class IStudentPaymentsContainer(IPaymentsContainer):
     """A container for student payment objects.
-
     """
 
 class IStudentOnlinePayment(IOnlinePayment):
     """A student payment via payment gateways.
-
     """
 
@@ -811 +785 @@
     def doAfterStudentPayment():
         """Process student after payment was made.
-
         """
 
     def doAfterStudentPaymentApproval():
         """Process student after payment was approved.
-
         """
 
     def approveStudentPayment():
         """Approve payment and process student.
-
         """
 
@@ -829 +800 @@
 class IStudentPreviousPayment(IKofaObject):
     """An interface for adding previous session payments.
-
     """
 
@@ -853 +823 @@
 class IStudentBalancePayment(IKofaObject):
     """An interface for adding balances.
-
     """