DocAssiduites/docs/ApiGenerationBulletinsPdf.md

436 lines
15 KiB
Markdown

# Génération des bulletins en Python
Informations internes à destination des développeurs.
## Types de bulletins
- Formations classiques
- HTML, court, intermédiaire, long
- XML (deprecated)
- JSON
- PDF
- Formations BUT
- JSON (utilisé par la version HTML)
- XML (partiel, deprecated)
- PDF
- "but court" HTML
- "but court" PDF
## Balises décisions de jury pour chaque type
## Organisation
A minima, il vous faut créer un module python (fichier .py) qui se définira une
classe chargée de générer vos bulletins.
Ce fichier doit être placé dans le répertoire `/opt/scodoc/instance/Products/ScoDoc`
Il faut aussi l'importer dans `sco_bulletins_generator.py` (voir tout à la fin
de ce fichier).
Voici un module minimal commenté (le fichier `sco_bulletins_example.py` est
fournit avec ScoDoc):
```py
"""Génération d'un bulletin de note style "Exemple"
(commentaire libre ici)
"""
# Quelques modules [ScoDoc](ScoDoc.md) utiles:
from sco_pdf import *
import sco_preferences
from notes_log import log
import sco_bulletins_generator
import sco_bulletins_standard
class [BulletinGeneratorExample](BulletinGeneratorExample.md)(sco_bulletins_standard.BulletinGeneratorStandard):
"""Un exemple simple de bulletin de notes en version PDF seulement.
Part du bulletin standard et redéfini la partie centrale.
"""
description = 'exemple (ne pas utiliser)' # la description doit être courte: elle apparait dans le menu de paramétrage
supported_formats = [ 'pdf' ] # indique que ce générateur ne peut produire que du PDF (la version web sera donc celle standard de [ScoDoc](ScoDoc.md))
# En général, on veut définir un format de table spécial, sans changer le reste (titre, pied de page).
# Si on veut changer le reste, surcharger les méthodes:
# .bul_title_pdf(self) : partie haute du bulletin
# .bul_part_below(self, format=*) : infos sous la table
# .bul_signatures_pdf(self) : signatures
def bul_table(self, fmt=*):
"""Défini la partie centrale de notre bulletin PDF.
Doit renvoyer une liste d'objets PLATYPUS
"""
assert format == 'pdf' # garde fou
return [
Paragraph( SU("L'étudiant %(nomprenom)s a une moyenne générale de %(moy_gen)s" % self.infos),
self.CellStyle # un style pdf standard
)
]
# Déclarer votre classe à ScoDoc
sco_bulletins_generator.register_bulletin_class(BulletinGeneratorExample)
```
Si l'on voulait générer aussi du HTML (pour la version web), il suffirait de le
déclarer dans la liste `supported_formats` et que la méthode `bul_table()`
renvoie une chaîne HTML si le paramètre `fmt` vaut `'html'`.
Pour modifier l'en-tête du bulletin PDF (partie au dessus de la table), il faut
surcharger la méthode `bul_title_pdf` qui elle aussi renvoie une liste d'objets
PLATYPUS:
```py
def bul_title_pdf(self):
...
```
De même, les informations placées sous la table principale sont renvoyées par la méthode `gen_part_below`:
```py
def gen_part_below(self, format=*):
"""Génère les informations placées sous la table de notes
(absences, appréciations, décisions de jury...)
Renvoie:
- en HTML: une chaine
- en PDF: une liste d'objets platypus
"""
...
```
et les signatures (seulement sur le PDF) par `bul_signatures_pdf`. Toutes ces
méthodes renvoient des listes d'objets PLATYPUS quelconques.
Vous pouvez partir d'un format de bulletin existant et proche de ce que voulez
obtenir et définir une sous-classe modifiant (surchargeant) seulement les
méthodes qui génèrent les éléments que vous voulez modifier.
<img src="/img/alert.png" style="vertical-align: bottom; margin:0 0 0 0;"
alt="/!\" /> Attention: ne pas modifier après coup le nom des classes de
générateurs (ici `BulletinGeneratorExample`), car il va être stocké en base de
données par ScoDoc.
## Accès aux informations
La plupart des informations nécessaires sont accessibles via des attributs de
votre instance de générateur que ScoDoc aura positionné avant d'appeler vos
méthodes. Notamment:
* `self.formsemestre`: l'objet `FormSemestre`
* `self.infos`: un (grand) dictionnaire python avec la plupart des informations
préparée pour le bulletin à générer (voir plus loin);
* `self.version`: indique la version de bulletin demandée par l'utilisateur
("long" ou "short", vous pouvez en faire ce que bon vous semble);
## Le dictionnaire d'informations
L'attribut `infos` est un dictionnaire qui contient de très nombreuses
informations. il doit être utilisé en **lecture seule** (il est possible que des
informations soient partagées entre threads différents, aussi les modifier peut
avoir des effets indésirables). .
### Paramètres (préférences)
Tous les paramètres du semestre sont accessibles via leur nom. Voir la liste sur
la page [NomsPreferences](NomsPreferences.md).
Exemple: `infos['SCOLAR_FONT_SIZE']` est un entier, `infos['UnivName']` est le
nom de l'université.
### Informations sur l'étudiant
#### Identité
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
| string * | etudid | id ScoDoc de l'étudiant | 'EID15219' |
string | code_ine | | *
string | code_nip | | *
string | codepostaldomicile | | '75018'
| date_naissance | | *
| annee_naissance | | '1947'
| domicile | | *
| email | | *
| lieu_naissance | | *
| nationalite | | *
| ne | "e" si étudiante, vide sinon | *
| nom | | 'FOURIER'
| prenom | | 'JOSEPH'
| sexe | | 'M.'
| nomprenom | | 'M. Joseph Fourier'
| paysdomicile | | *
| telephone | | *
| telephonemobile | | *
| telephonemobilestr | | *
| telephonestr | | *
| typeadresse | | 'domicile'
| villedomicile | | *
| villelycee | |
#### Admission
Informations importées dans ScoDoc lors de la création de l'étudiant
(import des données d'admission): établissement d'origine, notes de
lycée, etc.)
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
| bac | Série de bac | 'S'
| specialite | Spécialité de bac | 'SVT'
| math | note math antérieure (en terminale ou au bac ou ...) | *
| physique | note physique antérieure | *
| francais | note francais (au bac en général) | *
| anglais | note anglais antérieure | *
| annee_bac | année d'obtention du bac | '2010'
| nomlycee | | *
| codelycee | | *
| codepostallycee | | *
| qualite | note de qualité du dossier attribuée par le jury d'admission | *
| rang | rang de cet établissement dans les voeux du candidat (si applicable) | *
| rap | | "Pas d'informations sur les conditions d'admission."
| rapporteur | pseudo du collègue chargé de l'examen de ce dossier | *
| score | Score calculé pour ce dossier à l'admission | *
| commentaire | Commentaire du jury d'admission| *
| decision | Décision du jury d'admission | 'ADMIS'
| description | Comment l'étudiant a été inscrit | '(creation individuelle)'
#### Inscription
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
int | annee | | 2011
string | etatincursem | état (I=inscrit, D=démissionnaire) | 'I'
string | inscription | | 'DUT GEII, semestre 1 FI (Mars 2011 - Jul 2011)'
string | situation | | 'inscrit en DUT GEII, semestre 1 FI (Mars 2011 - Jul 2011) le 11/09/2011'
string | statut | ? | *
| descr_inscription | | 'Inscrit le 27/06/2011.'
En outre, les attributs `sems`, `cursem` et `ins` apportent des informations
sur les semestres auxquels l'étudiant est ou a été inscrit.
`etud['sems']`est une liste de dictionnaire représentants les
semestres auxquels est ou a été inscrit l'étudiant.
#### Parcours et référentiel BUT
Type | Nom | Description | Exemple de valeur
--------| ---------------------- | ---- | ---
string | parcours_titre | titre du parcours | "Cybersécurité"
string | parcours_code | code du parcours | "Cyber"
string | refcomp_specialite | code spécialité | "RT"
string | refcomp_specialite_long| spécialité | "Réseaux et Télécommunications"
### Résultats (notes) de l'étudiant dans le semestre
Quelques infos sur les résultats. Le détail des notes est dans la
liste `infos['ues']` et ses sous-listes imbriquées (modules, evaluation).
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
string | moy_gen | moyenne générale de l'étudiant dans le semestre | '12.00'
string | bonus_sport_culture | bonus appliqué | 0
string | moy_max | moyenne max promo | '12.00'
string | moy_min | moyenne min promo | '10.00'
string | moy_moy | moyenne des moyennes promo | '11.00'
int | nb_inscrits | nombre étudiants du semestre (incluant démissionnaires et défaillants) | 78
int | nb_demissions | nombre de démissions dans le semestre | 3
int | nb_defaillants | nombre de défaillants dans le semestre | 2
int | nbabs | nombre de 1/2 journées d'absences | 0L
int | nbabsjust | idem, justifiées | 0L
string | rang | classement | '(attente)'
string | rang_txt | classement (avec titre) | 'Rang (attente) / 2'
list | ues | résultats dans les UE, voir ci-dessous | [ liste de dict ]
Chaque élément de la liste `ues` représente les résultats de
l'étudiant dans une UE.
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
string | acronyme | | 'UE 1'
string | coef_ue_txt | Coefficient (chaîne) | '2'
string| cur_moy_ue_txt | Moyenne prise en compte pour cette UE | '12.00'
float | max | moyenne max promo | 12.0
float | min | moyenne min promo | 10.0
list | modules | détails notes dans les modules de l'UE | [ liste de dict]
list | modules_capitalized | | []
float | moy | | 11.0
string | moy_ue_txt | moyenne étudiant dans UE | '12.00'
int | nb_moy | nombre de moyenens calculées dans cette UE (inscrits, sans démissionnaires ni défaillants) | 76
int | numero | rang tri UE | 1
string | titre | | 'Formation Générale'
int | type | code type UE | 0
string | ue_code | code dans programme formation | 'UCOD5'
string | ue_descr_html | rang ou autre info à afficher | '(attente)/2'
string | ue_descr_txt | rang ou autre info à afficher | '(attente)/2'
string | ue_id | id interne ScoDoc | 'UE14572'
dict | ue_status | statut de l'UE (voir ci-dessous)| { dict }
**Statut d'une UE (champ `ue_status`):**
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
float | coef_ue | | 2.0
| coefs_bonus_gen | | []
| cur_coef_ue | | 2.0
| cur_moy_ue | | 12.0
string | expr_diag | infos erreur calcul formule utilisateur | {}
bool | is_capitalized | est-elle capitalisée? | False
| moy | | 12.0
| nb_missing | | 1
| nb_notes | | 1
| notes_bonus_gen | | []
| sum_coefs | | 2.0
| was_capitalized | | False
**Résultats dans un module:**
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
| code | | *
| code_html | | *
| code_txt | | *
| computation_expr | | *
| ens | | []
| evaluations | | []
| formsemestre_id | | 'SEM15176'
| mat | | {'titre': 'Mathématiques' }
| mod_coef_txt | | '2'
| mod_descr_txt | | "Module Fondamentaux d'algèbre et de trigonométrie, coef. 2 (Béatrice DUPONT)"
| mod_eff | | 2
| mod_moy_txt | | '12.00'
| mod_rang | | '(attente)'
| mod_rang_txt | | '(attente)/2'
| module | | {voir plus loin}
| module_id | | 'MOD14576'
| moduleimpl_id | | 'MIP15178'
| name | | 'Algèbre'
| responsable_id | id du responsable | 'dupont'
| stats | statistiques sur les notes du module | `{'moy': 9.576, 'nb_missing': 2, 'max': 16.5, 'min': 0.0, 'nb_notes': 39, 'nb_valid_evals': 1}`
Le module (tel que décrit dans le programme de la formation) est représenté par:
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
string | titre | | "Fondamentaux d'algèbre et de trigonométrie"
string | abbrev | | 'Algèbre'
string | code | | 'M1'
float | coefficient | | 2.0
| ects | | None
| formation_id | | 'FORM14570'
| heures_cours | | 0.0
| heures_td | | 30.0
| heures_tp | | 0.0
| matiere_id | | 'MAT14574'
| module_id | | 'MOD14576'
| numero | | 10
| semestre_id | | 1
| ue_id | | 'UE14572'
**Résultat dans une évaluation:**
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
| coef_txt | | '1'
| coefficient | | 1.0
| descrheure | | ' ? 08h00'
| description | | *
| duree | | '2h'
| etat | | { voir plus loin }
| evaluation_id | | 'EVAL15226'
| evaluation_type | | 0
| heure_debut | | '08h00'
| heure_fin | | '08h00'
| jour | | '01/07/2011'
| moduleimpl_id | | 'MIP15178'
| name | | 'le 01/07/2011'
| nb_abs | | 0
| nb_att | | 0
| nb_inscrits | | 2
| nb_neutre | | 0
| nb_notes | | 2
| note_html | | '12.00'
| note_max | | 20.0
| note_txt | | '12.00'
| notes | | { voir plus loin }
| publish_incomplete | | '0'
| visibulletin | | '1'
**Etat d'une évaluation:**
Le champ `etat` d'une évaluation est un dict donnant des informations sur les résultats de la promo (et des groupes) dans cette évaluation:
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
bool | evalattente | | False
bool | evalcomplete | | True
| evaluation_id | id interne | 15226
list | gr_incomplets | | []
list | gr_moyennes | | []
list | groups | liste des groupes | {}
datetime | last_modif | | datetime
string | median | note médianne promo | '11.00'
string | moy | note moyenne promo | '11.00'
| nb_abs | nb étudiants absents | 0
| nb_att | nb notes en attente | 0
| nb_inscrits | nb inscrits à ce module | 2
| nb_neutre | nb notes neutralisées | 0
| nb_notes | nb notes saisies | 2
`gr_moyennes` est un dict:
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
| gr_median | | '11.00'
| gr_moy | | '11.00'
| gr_nb_att | | 0
| gr_nb_notes | | 2
| group_id | | 'G24919'
| group_name | | None
**Notes dans une évaluation:**
Le champ `notes` dans une évaluation est un dictionnaire dont les clés sont les `etudids`, et les valeurs des dictionnaires donnant les informations sur la note de l'étudiant dans cette évaluation:
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
string | comment | commentaire saisie note | *
datetime | date | date de saisie | <mx.DateTime.DateTime object>
string | etudid | | 'EID15214'
string | evaluation_id | | 'EVAL15226'
string | uid | utilisateur ayant saisi la note | 'admin'
float | value | valeur de la note (sur 20) | 10.0
### Décisions de jury et autres informations
Type | Nom | Description | Exemple de valeur
----| --- | ---- | ---
| decision_sem | | None ou dict
string | decision_jury | décision du jury en clair (présent seulement si décision saisie) | 'Validé'
list | appreciations | | []
list | appreciations_list | | []
list | appreciations_txt | | []
string | mention | texte de la mention calculée | 'Très bien'
| filigranne | texte en surimpression | 'Provisoire'
## Note: la fonction log
Pour la mise au point, il peut être utile de recourir à la bonne vieille
fonction log, qui envoie du texte dans le fichier de log courant, normalement
`/opt/scodoc-data/log/scodoc.log`. La date et le saut de ligne final sont
automatiquement ajoutés.
```
log("toto")
```