==================================
Format des emplois du temps Celcat
==================================

Avant de pouvoir afficher les emplois du temps, il est nécessaire de
parser les fichiers XML générés par Celcat.

On a besoin de plusieurs informations concernant le cours :

 - son nom ;
 - son type ;
 - sa semaine et son jour ;
 - son début et sa fin ;
 - son commentaire ;
 - ses salles ;
 - ses groupes.

Certaines de ces informations sont triviales à récupérer (comme son
nom, son type, son commentaire…), mais d’autres (telles que son jour
précis) est un peu plus délicat.

Parser facilement le XML
========================
Pour récupérer les fichiers à distance, celcatsanitizer utilise la
bibliothèque requests_, et se sert de BeautifulSoup4_ pour parser les
fichiers XML.

.. _BeautifulSoup4:
  https://www.crummy.com/software/BeautifulSoup/bs4/doc/
.. _requests: http://docs.python-requests.org/en/master/

Les semaines
============
La première chose à faire après avoir téléchargé le fichier est de
récupérer la liste des semaines présentes. Les dates sont encodées
d’une manière assez exotique :

.. code:: xml

    <span id="1" date="16/10/2017" rawix="9" rawlen="1">
    <description>Semaine 42, Semaine commençant le 16/10/2017</description>
    <title>42</title>
    <alleventweeks>NNNNNNNNYNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN</alleventweeks>
    <day id="0">
    <name>lundi</name>
    <row id="0" />
    <row id="1" />
    <row id="2" />
    <row id="3" />
    <row id="4" />
    <row id="5" />
    <row id="6" /></day>
    <day id="1">
    <name>mardi</name>
    <row id="0" />
    <row id="1" />
    <row id="2" />
    <row id="3" />
    <row id="4" />
    <row id="5" /></day>
    <day id="2">
    <name>mercredi</name>
    <row id="0" />
    <row id="1" />
    <row id="2" />
    <row id="3" />
    <row id="4" />
    <row id="5" />
    <row id="6" /></day>
    <day id="3">
    <name>jeudi</name>
    <row id="0" />
    <row id="1" />
    <row id="2" />
    <row id="3" />
    <row id="4" />
    <row id="5" /></day>
    <day id="4">
    <name>vendredi</name>
    <row id="0" />
    <row id="1" />
    <row id="2" />
    <row id="3" />
    <row id="4" />
    <row id="5" /></day></span>

Vous voyez donc la date de début, le numéro de semaine, et la
mystérieuse valeur ``<alleventweeks>``. Il s’agit d’un identifiant de
semaine. La propriété ``id`` du ``<span>`` ne semble pas être
nécessaire pour comprendre le reste du fichier.

.. _ref-week-dict:

On va donc créer un tableau des semaines en se servant des
``<alleventweeks>`` comme clé, et le premier jour de la semaine comme
valeur.

Les cours
=========
Voici un exemple de cours :

.. code:: xml

    <event id="351687" timesort="07450945" colour="BEA7B8" ecs="4" ecc="11" er="0" scb="1">
    <day>1</day>
    <prettytimes>07:45-09:45 COURS/TD</prettytimes>
    <starttime>07:45</starttime>
    <endtime>09:45</endtime>
    <category>COURS/TD</category>
    <prettyweeks></prettyweeks>
    <rawweeks>NNNNNNNNYNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN</rawweeks>
    <resources>
    <module title="Matière">
    <item>EDINF3F1 - Algorithmique et programmation</item></module>
    <group title="Groupe">
    <item>L2 Info s1 TDA4</item></group>
    <room title="Salle">
    <item>1TP1-B08bis</item></room></resources></event>

Les différents éléments sont :

================= ===================== =============================
Donnée indiquée   Balise correspondante Plusieurs valeurs possibles ?
================= ===================== =============================
Nom du cours      ``<module>``          Oui
Groupes concernés ``<group>``           Oui
Salles            ``<room>``            Oui
Type de cours     ``<category>``        Non
Heure de début    ``<starttime>``       Non
Heure de fin      ``<endtime>``         Non
Jour              ``<day>``             Non
Semaine           ``<rawweeks>``        Non
Remarque          ``<notes>``           Non
================= ===================== =============================

Quand une donnée peut prendre plusieurs valeurs à la fois, les
différentes valeurs se trouvent dans des balises
``<item>``. celcatsanitizer traîte tous les groupes et toutes les
salles, mais ne lis qu’un seul nom de cours.

Dans l’exemple donné plus haut, il n’y a pas de champ remarque.

Pour trouver le jours du cours, on prend la semaine référencée par la
balise ``<rawweeks>``, on retrouve le début de la semaine
correspondante à l’aide du :ref:`dictionnaire des semaines
<ref-week-dict>`, et on ajoute autant de jours qu’indiqué par la
balise ``<day>``.