:fr: Un clone en Python 3 de Parcoursup, écrit à but didactique¶

Écrit par deux doctorants de l’équipe SCEE de CentraleSupélec, campus de Rennes, Lilian Besson (@Naereen) et Bastien Trotobas (@BastienTr), et d”autres collaborateur-trice-s.

Présentation¶

Ce dépôt contient un clone (presque complet) des algorithmes régissant la plateforme Parcoursup, qui gère depuis 2018 les affectations des élèves de classe de Terminale (🇫🇷 dans les lycées en France) dans leurs formations dans l’enseignement supérieur.

Les algorithmes et l’implémentation officielle (en Java) ont été distribués en accès libre, et sous licence libre (GPL), en mai 2018. En 2018, ils étaient hébergés sur ce site (framagit.org/parcoursup/algorithmes-de-parcoursup).

Nous proposons ici une implémentation complète des différents algorithmes de Parcoursup, écrite en Python 3, dans un style très clair, avec des commentaires, et une documentation.
Nous avons pour objectif de comprendre et d’expliquer ces algorithmes, en utilisant au maximum des notions et des modules Python qui soient abordables et compréhensibles par des élèves de classes préparatoires scientifiques (typiquement des MPSI).
Note : Vous pouvez contribuer si vous le souhaiter ! Une erreur à signaler ?, ou une contribution possible ? 👏 Merci d’avance !

Plan de bataille ¶

Pour le développement en cours, cf. ce fichier TODO.md !

/ : /

Explications¶

Pour l’instant, nous avons implémenté dans le dossier parcoursup/ un clone complet du code Java initial, écrit en Python 3.
Et dans le dossier notebooks/ nous proposons des implémentations simplifiées des principaux algorithmes, écrites sans dépendances et dans un style très didactique, avec des visualisations interactives afin de permettre à tout le monde d’expérimenter un peu et de visualiser le comportement des algorithmes. L’accent est mis sur la compréhension rapide de l’influence des différents paramètres numériques.
TODO expliquer l’algorithme dans les grandes lignes, avec notre propre vocabulaire, ici.

Organisation de ce dépôt¶

Des visualisations sont dans le dossier notebooks/. TODO encore à travailler !
Le code des algorithmes est dans le dossier parcoursup/, comme le code Java initial, c’est découpé en deux modules, ordreappel et propositions,
Les (exemples de) données synthétiques générées sont dans le dossier donnees/,
Des tests (plusieurs centaines) sont présents dans le dossier tests/, inspirés par ce projet,
Une documentation de notre implémentation complète est disponible en ligne, sur la page suivante, construite avec Sphinx à partir des fichiers présents dans le dossier docs/,
Des utilitaires sont dans le dossier utils/,

Démonstration dans un notebook Jupyter ¶

Des visualisations sont dans le dossier notebooks/.

Documentation officielle et ressources¶

La page officielle de présentation de Parcoursup est ici (en 2018).

Communications journalistiques, entre le 23 mai 2018 et le 15 juillet 2018 :

Les indicateurs quotidiennement publiés par le ministère sont sur cette page là (en juin 2018).
Cette carte qui montre jour après jour les résultats donnés par Parcoursup : statistiques.parcoursup.fr.

Nous voulons proposer notre propre carte de visualisation, c’est en cours…

Des détails sur les algorithmes :

Ce document texte et cet autre document PDF donnent plein d’explications.
Ce texte du Journal Officiel montre l’autorisation donnée par la CNIL pour la création de la base de données pour Parcoursup, et détaille un peu toutes les informations stockées pour le service. Il est important de garder en tête que ces données ne sont pas utilisées par les algorithmes de Parcoursup, qui n’utilisent qu’un identifiant unique et anonyme pour identifier chaque candidat-e.

Autres ressources, moins techniques mais plus pédagogiques :

Le dossier de presse du ministère pour Parcoursup
Ces articles sur des blogs du Monde: sur ingenuingenieur.blog.lemonde.fr, sur enseigner.blog.lemonde.fr ou sur binaire.blog.lemonde.fr.
Cet autre article par Clémence Réda est instructif.

Exemples¶

Installation¶

Ces lignes de Bash (à exécuter sur une machine type GNU/Linux ou un Mac avec les outils standards) clone ce dépôt, et installent un virtualenv Python et installent les dépendances dans cet environnement virtuel :

cd /tmp/
git clone https://GitHub.com/Naereen/ParcourSup.py
cd Parcoursup.py/
make install

Note : Il n’est pas nécessaire d’utiliser un virtualenv, mais c’est recommandé. Vous pouvez simplement installer les modules requis avec sudo pip install -r requirements.txt.

Note : notre code n’est pas spécifiquement écrit pour une machine utilisant GNU/Linux, et il devrait fonctionner sur n’importe quelle plateforme qui supporte Python 3.6 (Microsoft Windows et Mac OS X notamment). Il est testé sous GNU/Linux (XUbuntu) et sous Microsoft Windows 7. N’hésitez pas à signaler un problème, si besoin. 👏 Merci d’avance !

Tests ¶

Les tests qui reproduisent (presque) parfaitement les données d’exemples peuvent être exécutés avec les deux commandes suivantes :

Ordres d’appel :

$ . env/bin/activate ; python3 ./parcoursup/ordreappel/__init__.py
...

Proposition de vœux :

$ . env/bin/activate ; python3 ./parcoursup/propositions/__init__.py
...

Ces deux tests prennent environ 30 secondes chacun.

Note : Il n’est pas nécessaire d’utiliser un virtualenv, mais c’est recommandé. Vous pouvez simplement faire les tests avec python3 ./parcoursup/ordreappel/__init__.py et python3 ./parcoursup/propositions/__init__.py.

Des tests supplémentaires ont été récemment ajoutés (voir #3).

Construire la documentation ? ¶

Demande d’avoir le module sphinx installé. (sudo pip3 install sphinx si besoin).
Puis, dans le dossier principal, il suffit de faire :

$ make docs

Sous Windows ou si GNU Make n’est pas disponible, vous pouvez construire la documentation manuellement avec les deux commandes suivantes :

$ sphinx-apidoc -f -o ./docs -e -M ./parcoursup/
$ sphinx-build -M html ./docs ./_build
$ ./docs/.fixes_html_in_doc.sh

À propos¶

Language et versions ?¶

Python v3.6+. Avec les modules suivants :

Numpy pour les tableaux,
La bibliothèque standard pour tout le reste.
ipython, Jupyter pour les notebooks.
tqdm sont optionnels.