Changeset 13002 for main/waeup.kofa/trunk/docs/source/userdocs/students.rst

Timestamp:

26 May 2015, 15:34:36 (9 years ago)

Author:

Henrik Bettermann

Message:

More docs. Complete IStudentStudyCourse and IStudentStudyLevel interfaces and adjust unit tests.

File:

• main/waeup.kofa/trunk/docs/source/userdocs/students.rst (modified) (2 diffs)

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

@@ -118 +118 @@
    :pyobject: IStudentStudyCourse
 
-The first schema field is a `Choice` field and only values from the `CertificateSource` are allowed. The source provides all certificates stored in the portal. This way, `StudentStudyCourse` objects point to exactly one `Certificate` object in the portal. If the certificate is removed, an event handler takes care of clearing also all referring `certificate` attribute. The tokens of the `CertificateSource` are the certicate codes which means, that in forms and import files the unique code must be given and the desired `Certificate` object will be stored.
+All attributes are read-only property attributes which are computed dynamically.
+
+The first schema field is a `Choice` field which allows values from the `CertificateSource`. The source provides all certificates stored in the portal. This way, `StudentStudyCourse` objects point to exactly one `Certificate` object in the portal. If the certificate is removed, an event handler takes care of clearing also all referring `certificate` attribute. The tokens of the `CertificateSource` are the certicate codes which means, that in forms and import files the unique code must be given and the desired `Certificate` object will be stored.
 
 The interface has two entry parameter fields. `entry_mode` stores the study mode of the programme and `entry_session` the academic year when the study course was started. Usually these parameters are fixed and must not be changed during course of study.
@@ -126 +128 @@
 What is a verdict? A verdict is the individual judgement of a jury (senate in Nigeria) at the end of each academic session. The jury's verdict tells the portal, if the student has successfully completed an academic session or not. Depending on the verdict, the student will be either allowed to proceed to the next study level or forced to repeat the current level. Without a verdict, the student gets stuck and cannot even pay school fees for the next academic year. This will be further exlplained in the workflow section below.
 
-`StudentStudyCourse` is a container class. Study courses contain `StudentStudyLevel` instances.
+`StudentStudyCourse` is a container class. Study courses contain `StudentStudyLevel` instances which implement `waeup.kofa.students.interfaces.IStudentStudyLevel`.
 
 `IStudentStudyLevel`
 --------------------
 
+`StudentStudyLevel` instances contain information about the study progress achieved at that level. In Kofa study levels range from 100 to 900. There are two additional levels: a pre-studies level (10) and a special postgraduate level (999). There are also two probation levels per regular study level. Level 120, for instance, means level 100 on second probation. The complete numbering of study levels can be viewed `here <https://kofa-demo.waeup.org/sources#collapseStudyLevels>`_.
+
+`StudentStudyLevel` instances are container objects which contain course tickets. We therefore sometimes speak of a level course list instead of a study level. The study level stores and provides the information when (`validation_date`) and by whom (`validated_by`) the course list was validated, in which session the level was taken (`level_session`) and which verdict the student finally obtained.
+
 .. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
    :pyobject: IStudentStudyLevel
+
+`StudentStudyLevel` instances also compute some statistical values on the fly to give an overview of the courses taken. These read-only property attributes are: `number_of_tickets`, `passed_params`, `gpa_params`, `gpa_params_rectified`, `cumulative_params`, `total_credits` and `gpa`. The attentive reader may wonder why the latter two are not listed in the attributes section of the interface, but as read-only schema fields further below. This is a trick which we used to properly display these fields on some form pages and pdf slips. However, the `attrs_to_fields` function explicitly excludes them when starting the portal, so that these fields are not used for persistent storage of same-named attributes in the database.
 
 `ICourseTicket`