cleo/DocScoDocPE
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
6a774a7271
DocScoDocPE/docs/ApiGenerationBulletinsPdf.md

17 KiB
Raw Blame History

Générer des bulletins en Python

Il est possible de coder de nouveaux styles de bulletins de notes (web et/ou PDF), pour répondre précisément aux besoins de votre établissement.

Ce n'est pas très difficile, mais il faudra coder en langage Python avec pour le PDF la bibliothèque ReportLab (qui est bien documentée, voir le guide).

ScoDoc demande la création d'un bulletin pour un étudiant donné dans semestre donné (formsemestre_id). Le bulletin doit être rendu sous forme d'une liste d'objets PLATYPUS (voir le chapitre 5 du "User Guide" de ReportLab cité plus haut).

/!\ Attention (août 2011): nouvelle version, changement d'API: les informations ci-dessous s'appliquent à partir de la subversion 1047.

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

#!python
# -*- mode: python -*-
# -*- coding: utf-8 -*-

"""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, format=*):
        """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](ScoDoc.md):
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 format 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:

#!python
    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:

#!python
    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.

/!\ 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.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);
  • self.context: contexte ScoDoc, permettant l'accès à l'API complète.

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.

Exemple: infos['SCOLAR_FONT_SIZE'] est un entier, infos['UnivName'] est le nom de l'université.

Informations sur le semestre

Un semestre est représenté par un dictionnaire avec les attributs suivants:

Type Nom Description Exemple de valeur
int semestre_id Indice dans le parcours 1
string titre 'DUT GEII'
string titre_num 'DUT GEII, semestre 1'
string titreannee 'DUT GEII, semestre 1 FI 2011'
string titremois 'DUT GEII, semestre 1 FI (Mars 2011 - Jul 2011)'
string annee_debut '2011'
string annee_fin '2011'
anneescolaire '2010 - 2011'
string date_debut '09/03/2011'
date_debut_iso '2011-03-09'
date_fin '31/07/2011'
date_fin_iso '2011-07-31'
dateord '2011-03-09'
mois_debut 'Mars 2011'
int mois_debut_ord 3
mois_fin 'Jul 2011'
int mois_fin_ord 7
string modalite 'FI'
string etape_apo Code étape Apogée 'V1TR2'
string etape_apo2 Code étape Apogée (si 2 codes) *
string etat verrouillé ('0') ou non ('1') '1'
formation_id id interne de la formation 'FORM14570'
formsemestre_id id interne du semestre 'SEM15176'
string gestion_compensation '0'
string gestion_semestrielle '0'
string responsable_id 'viennet'
int {0,1} ens_can_edit_eval 0
int {0,1} resp_can_change_ens 0
int {0,1} resp_can_edit 0
string bul_bgcolor *
string bul_hide_xml '0'

Pour le semestre à traiter, ces attributs sont directement dans infos.

On trouve aussi dans infos['etud'] tous les semestres par lesquels est passé l'étudiant.

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.

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 ets 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 'EVAL15226'
list gr_incomplets []
list gr_moyennes []
list groups liste des groupes {}
datetime last_modif <mx.DateTime.DateTime object>
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")