.. _activite4 : *********************************************************************************************** Activité 4 |:| Prise en main des formats de représentation des événements (2h) *********************************************************************************************** .. _format_ics: ============= Le format ics ============= Le format ``.ics`` désigne la structure servant à décrire les informations/événements d'un calendrier. Ce format est compatible avec le standard `iCalendar `_ et permet une représentation textuelle des événements, souvent stockée dans un fichier d'extension :fichier:`.ics`. Il utilise un ensemble d'**identificateurs textuels** pour décrire différentes **propriétés d'un événement** (date, heure, lieu, ...). -------------------------- Format ics d'un événement -------------------------- Prenons l'exemple du TP suivant exporté d'ADE |:| .. figure:: ../images/un_evenement_ADE.png :width: 50% Identificateurs principaux -------------------------- Sa représentation au format ``.ics`` est |:| .. _exemple_evenement_ics: .. code-block:: none :caption: Exemple d'événement ics BEGIN:VEVENT UID:ADE6050726f6a6574535453323032312d323032322d31373030382d302d31 SUMMARY:R104-TP-Eln CATEGORIES:S1G1 DESCRIPTION:FAYOLLE GERARD,KASPER KEVIN LOCATION:IUT1_126 DTSTART:20211126T080000Z DTEND:20211126T120000Z DTSTAMP:20211016T000000Z TRANSP:OPAQUE END:VEVENT dans laquelle les identificateurs textuels s'interprètent comme suit |:| * ``BEGIN`` et ``END`` marquent le début et la fin de la description d'un événement de type (ici) ``VEVENT`` et forme un **noeud** d'informations * ``UID`` déclare la valeur d'un **identifiant unique** associé à cet événement (ici) ``ADE6050726f6a6574535453323032312d323032322d31373030382d302d31`` ; deux événements différents ne pourront donc jamais avoir le même identifiant. * ``SUMMARY`` déclare l'**intitulé** de l'événement (ici) ``R104-TP-Eln`` * ``CATEGORIES`` est utilisé pour indiquer **les groupes de TD** pour lesquels l'événement a lieu (ici) ``S1G1`` * ``DESCRIPTION`` donne **les enseignants** qui interviennent sur l'événement (ici) Gérard FAYOLLE et Kévin KASPER * ``LOCATION`` précise **la ou les salles** dans lesquelles se tiennent l'événement (ici) en ``IUT1_126`` * ``DTSTART`` et ``DTEND`` précisent la **date de début** et la **date de fin** de l'événement (``DTSTAMP`` est la date de création d'un message en lien avec l'événement et ne sera pas utilisé ici), dans un format vu pendant l':ref:`activité 3 ` * ``TRANSP`` ne sera pas utilisé dans ce projet .. note:: * Le caractère ``":"`` sépare systématiquement l'identificateur de la description de la propriété. * Les propriétés peuvent être optionnelles, auquel cas l'identificateur n'apparaît pas dans la description ``.ics``. * Les propriétés ne sont pas ordonnées (l'ordre de déclaration peut changer d'un évènement à un autre). --------------------------- Format ics d'un calendrier --------------------------- Un calendrier au format :fichier:`.ics` liste les événements qui le composent, les uns après les autres (de leur identificateur ``BEGIN`` à leur identicateur ``END``) en |:| * les encapsulant dans un **noeud** de type ``VCALENDAR`` * décrivant des propriétés du calendrier grâce à des identificateurs textuels spécifiques Prenons l'exemple du calendrier (extrait du calendrier des UFA) |:| .. _exemple_3_evenements_UFA: .. code-block:: none :caption: Exemple de calendrier ics BEGIN:VCALENDAR PRODID:ics.py - http://git.io/lLljaA VERSION:2.0 BEGIN:VEVENT DTSTAMP:20211029T000000Z DTSTART:20220405T090000Z DTEND:20220405T113000Z SUMMARY:M4206-DS-PartTP-Android DESCRIPTION:DELNONDEDIEU YVES,GOEURIOT LORRAINE LOCATION:IUT1_T33 res1,IUT1_T32 res2 TRANSP:OPAQUE UID:ADE6050726f6a6574535453323032312d323032322d353337372d302d30 CATEGORIES:S4UFA END:VEVENT BEGIN:VEVENT DTSTAMP:20211029T000000Z DTSTART:20210906T090000Z DTEND:20210906T100000Z SUMMARY:Réunion de rentrée UFA DESCRIPTION:CHOLLET REMY,VEDEL FRANCK LOCATION:IUT1_121_GE TRANSP:OPAQUE UID:ADE6050726f6a6574535453323032312d323032322d34313931332d302d30 CATEGORIES:S3UFA END:VEVENT BEGIN:VEVENT DTSTAMP:20211029T000000Z DTSTART:20220506T080000Z DTEND:20220506T100000Z SUMMARY:M4201-TD-Anglais DESCRIPTION:NICOLL NICOLA,ROYER SANDRA LOCATION:IUT1_C007,IUT1_C011 TRANSP:OPAQUE UID:ADE6050726f6a6574535453323032312d323032322d32333037302d302d30 CATEGORIES:S4UFA END:VEVENT END:VCALENDAR dans lequel les identificateurs textuels s'interprètent comme suit |:| * Le ``BEGIN`` initial (ligne 1) et le ``END`` final (dernière ligne) marquent le début et la fin de la description du calendrier de type (ici) ``VCALENDAR`` * ``VERSION`` et ``PRODID`` donnent des informations sur le mode de production du calendrier `.ics` * sont ensuite décrits 3 événements intitulés *4206-PartTP-Android*, *Réunion de rentrée UFA* et *4201-Anglais* .. note:: * La description d'un événement ne peut pas être commencée (``BEGIN``) avant que celle du précédent soit terminée (``END``). * Il n'y a jamais de ligne vide. --------- Remarques --------- Les données :fichier:`.ics` sur lesquelles vous allez travailler ont été pré-traitées par les enseignants pour les simplifier et se libérer de certaines contraintes de la norme, qui *à titre d'information* stipulent que |:| * Dans la norme, les lignes ont une longueur maximale de 75 caractères par ligne. Elles peuvent commencer par un espace pour former la suite de la propriété commencée à la ligne précédente. Avec le pré-traitement, les lignes pourront faire plus de 75 caractères ; elles débuteront systématiquement par un identificateur et donneront la propriété *en entier*. * Dans la norme, les retours à la ligne sont ceux du système Windows. Ils utilisent la combinaison de caractères spéciaux ``"\r\n"`` (*Cariage Return* + *Line Feed*). Avec le pré-traitement, les retours à la ligne utilisent un simple ``'\n'``. .. warning:: La première étape de votre projet a pour objectif d'extraire les données des calendriers au format `.ics` fournis et de les transformer en un format plus compact et plus exploitable décrit ci-après. Il s'agit d'une étape dite de **parsing** ou d'une action de **parser** (anglicismes couramment répandus). .. _format_pseudo_csv: =================== Format *pseudo-csv* =================== Le format dit *pseudo-csv* n'est pas un format normalisé ; c'est un choix de représentation, fait par les enseignants au moment de l'élaboration du cahier des charges, pour **représenter le calendrier et ses événements de manière plus compacte**. ---------------------------------- Format d'un événement *pseudo-csv* ---------------------------------- Un événement au format *pseudo-csv* est décrit par une chaine de caractères de la forme |:| .. _exemple_evenement_csv: .. code-block:: python uid;date;heure;duree;code;modalite;intitule;salle1|salle2|...;prof1|prof2|...;groupe1|groupe2|... représentant les différentes propriétés d'un événement, séparées les unes des autres par des ``';'`` avec |:| * ``uid`` (``uid``) |:_| l'identifiant unique de l'événement * ``date`` (``date``) |:_| la date au format ``JJ-MM-AAAA`` à laquelle débute l'événement * ``heure`` (``time``) |:_| l'heure au format ``HH:MM`` marquant le début (horaire) de l'événement avec mention de l'heure ``HH`` et des minutes ``MM`` chacun sur 2 chiffres (les secondes étant omises) * ``duree`` (``duration``) |:_| la durée de l'événement traduite au format ``HH:MM`` avec mention du nombre d'heures pleines ``HH`` et du nombre de minutes restantes ``MM`` chacun sur 2 chiffres (les secondes étant omises) * ``code`` (``code``) |:_| le :term:`code` de :term:`module` (ressource, SAé ou module) auquel est rattaché l'événement * ``modalite`` (``modality``) |:_| la :term:`modalité` (CM/TD/TP/Proj/DS) de l'événement * ``intitule`` (``title``) |:_| l'intitulé de l'événement (tel qu'il apparait dans ADE) * ``salle1|salle2|...`` (``rooms``) |:_| les :term:`salles` réservées pour le créneau, séparées par des ``|`` * ``prof1|prof2|...`` (``teachers``) |:_| les :term:`professeurs` qui encadrent le créneau, séparés par des ``|`` * ``groupe1|groupe2|...`` (``groups``) |:_| les :term:`groupes de TD` qui suivent le créneau, séparés par des ``|`` L'événement de l'exemple précédent (cf. :ref:`Exemple d'événement ics `) a donc pour description au format pseudo-csv |:| .. code-block:: python ADE6050726f6a6574535453323032312d323032322d31373030382d302d31;26-11-2011;08:00;R104;TP;R104-TP-Eln;IUT1_126;FAYOLLE GERARD|KASPER KEVIN;S1G1 .. note:: Lorsqu'un événement n'est pas rattaché à un module, par exemple, la **Réunion de rentrée** de 1ère année, le code est ``"Autre"``. La modalité d'un événement peut être ````. ----------------------------------- Format d'un calendrier *pseudo-csv* ----------------------------------- Un calendrier au format *pseudo-csv* est une **suite** d'événements (un par ligne), chaque événement étant décrit au format *pseudo-csv* (décrit précédemment). Le calendrier de l'exemple précédent (cf. :ref:`exemple_3_evenements_UFA`) a donc la description suivante dans un fichier au format *pseudo-csv* |:| .. code-block:: python ADE6050726f6a6574535453323032312d323032322d353337372d302d30;05-04-2022;09:00;02:30;M4206;DS;M4206-DS-PartTP-Android;IUT1_T33 res1|IUT1_T32 res2;DELNONDEDIEU YVES|GOEURIOT LORRAINE;S4UFA ADE6050726f6a6574535453323032312d323032322d34313931332d302d30;06-09-2021;09:00;01:00;Autre;;Réunion de rentrée UFA;IUT1_121_GE;CHOLLET REMY|VEDEL FRANCK;S3UFA ADE6050726f6a6574535453323032312d323032322d32333037302d302d30;06-05-2022;02:00;M4201;TD;M4201-TD-Anglais;IUT1_C007|IUT1_C011;NICOLL NICOLA|ROYER SANDRA;S4UFA C'est une suite de 3 lignes, chacune décrivant un événement. .. note:: Remarquez la *Réunion de rentrée* dont le code est ``"Autre"`` et la modalité est ````. ================================== Stratégie de prise en main ================================== Votre objectif pour cette activité est de prendre en main le format :fichier:`.ics` pour pouvoir ensuite commencer à réaliser la première étape de votre projet |:| *parser* les événements pour les convertir au format *pseudo-csv*. ----------------------------------------------------------------- Préparer un script Awk ----------------------------------------------------------------- A la racine du répertoire de votre projet (répertoire :file:`~/SAE15`) |:| 1. Créez un nouveau fichier :file:`projet_ics.awk` 2. Recopiez le code suivant |:| (par un simple copier-coller) .. code-block:: awk BEGIN { print "Le script commence !" vevent = "ADE6050726f6a6574535453323032312d323032322d353337372d302d30;05-04-2022;09:00;02:30;M4206;DS;M4206-DS-PartTP-Android;IUT1_T33 res1,IUT1_T32 res2;DELNONDEDIEU YVES,GOEURIOT LORRAINE;S4UFA" # Point 1 : Codez ci-après le découpage de la chaine vevent en un tableau tevent # Fin du Point 1 salles = tevent[8] profs = tevent[9] # Point 2 : Codez ci-après le remplacement des ',' par des '|' # Fin du Point 2 print "salles avec des '|' = " salles print "profs avec des '|' = " profs } 3. Ouvrez un terminal. 4. Placez vous dans le répertoire :file:`SAE15` où vous avez normalement créé votre script. 5. Testez votre script avec la commande |:| .. code-block:: bash awk -f ./projet_ics.awk 6. Vous devriez voir s'écrire "Le script commence !" sur votre console. -------------------------------------------------- Préparer la conversion `ics` vers le *pseudo-csv* -------------------------------------------------- * Ecrivez le code demandé dans le script aux points 1 et 2. * Vous êtes prêt à coder les fonctions attendues sur les événements. ----------------------------------------------------- Avancer sur le codage des dates et de la conversion ----------------------------------------------------- * Consultez la documentation des modules :py:mod:`projet_phase1` et :py:mod:`projet_ics2csv`. * Complétez toutes les fonctions vides du module et testez les au fur et à mesure dans la boucle principale du module :py:mod:`projet_ics2csv`. * Commencez le code de la fonction :py:func:`icsEvtToCsv` sans vous soucier dans un premier temps du code ``"Autre"`` pour les événements qui ne sont pas des modules. Pour mettre au point et tester votre code (au fur et à mesure) |:| * travaillez sur le calendrier donné en exemple (téléchargeable :download:`ici <../exports/ics/calendrier_3evts_UFA.ics>`) |;| * le résultat attendu du parsing *ics* est le suivant (téléchargeable :download:`ici <../exports/csv/calendrier_3evts_UFA_expected_sans_autre.csv>`) |:| .. code-block:: python ADE6050726f6a6574535453323032312d323032322d353337372d302d30;05-04-2022;09:00;02:30;M4206;DS;M4206-DS-PartTP-Android;IUT1_T33 res1|IUT1_T32 res2;DELNONDEDIEU YVES|GOEURIOT LORRAINE;S4UFA ADE6050726f6a6574535453323032312d323032322d34313931332d302d30;06-09-2021;09:00;01:00;Réunion de rentrée UFA;;Réunion de rentrée UFA;IUT1_121_GE;CHOLLET REMY|VEDEL FRANCK;S3UFA ADE6050726f6a6574535453323032312d323032322d32333037302d302d30;06-05-2022;08:00;02:00;M4201;TD;M4201-TD-Anglais;IUT1_C007|IUT1_C011;NICOLL NICOLA|ROYER SANDRA;S4UFA * Dans un deuxième temps, réglez le problème du code ``"Autre"`` pour les événements qui ne sont pas des modules. * Le résultat final de la transformation de l'union de tous les fichiers :file:`.ics` (disponible :download:`ici <../exports/ics/all.ics>`) fournis dans le cahier des charges est le fichier disponible :download:`ici <../exports/csv/all_ics_expected.csv>`.