PapillonApp/papillon-python

API REST pour Pronote/Papillon en utilisant hug.rest et https://github.com/bain3/pronotepy/

Pourquoi faire ?

Auparavant, Papillon utilisait @Litarvan/pronote-api, mais cette API non maintenue depuis Avril 2021 commence à poser de plus en plus de problèmes à cause de son retard, et en plus est compliquée à héberger. Voila pourquoi je transitionne vers @bain3/pronotepy, qui est encore maintenu et bien plus complet en fonctionnalités.

Cela permet aussi à vous, utilisateurs et utilisatrices de Papillon, d'utiliser votre propre serveur afin de faire fonctionner notre application et ainsi ne plus être dépendant de notre infrastructure.

⚠️ Attention : Si vous décidez d'utiliser votre propre instance de notre API nous ne seront pas en mesure de vous aider et nous ne proposerons aucun support concernant l'utilisation de l'API et les problèmes qui pourrait vous arriver suite à votre propre gestion de cette dernière.

Déploiement

Pré-requis

Vous devez installer Python 3.10 minimum et PiP.
Ensuite installer les dépendances avec les commandes suivantes :

pip3 install hug -U
pip3 install pronotepy -U
pip3 install lxml

Installation

Bare-metal

Une fois les pré-requis en place vous pouvez executer le serveur avec la commande suivante : Veuillez noter que le serveur est prévu pour fonctionner sur notre infrastructure, il est donc possible que vous deviez modifier le code pour qu'il fonctionne sur votre propre serveur. De plus, il est nécessaire de modifier le fichier server.py et de supprimer les fonctions get_client_on_instances() et token_get_client() ainsi que les appels à ces fonctions (si présent dans la branche téléchargée).

git clone -b main https://github.com/PapillonApp/papillon-python
cd papillon-python
python -m hug -f server.py

Cela va lancer le serveur sur le port 8000.

Docker

Une fois docker installé sur votre machine, vous pouvez pull l'image docker :

docker pull justtryon/papillonserver:latest

Une fois cela fait, vous pouvez déployer l'api avec cette commande :

docker run -d -p 8000:8000 -e CRON="*/15 * * * *" justtryon/papillonserver:latest

Vous pouvez changer le temps de redémarrage automatique du serveur en changeant la variable d'environnement CRON

Cela va lancer le serveur sur le port 8000.

Documentation

Requêtes

Un client doit faire la requête initiale POST /generatetoken avec le body suivant :

Paramètre	Utilité	Exemple
url: str(url)	URL vers l'instance pronote (avec le eleve.html)	https://0152054e.index-education.net/pronote/eleve.html
username: str	Nom d'utilisateur PRONOTE	l.martin
password: str	Mot de passe en clair	azertyuiop12345
ent: str(ent)	Nom de l'ENT tel que listé ici	ac_rennes

Le client doit ensuite garder le token généré. Si il ya eu un délai d'au moins 5 minutes entre deux interactions, le client doit regénérer un nouveau token.

Ensuite chaque appel à une fonction de l'API doit avoir le paramètre token défini. Voici la liste des URLs pour obtenir des données :

URL	Utilité	Paramètres
/user	Obtient les infos sur l'utilisateur (nom, classe...) + les périodes de l'année
/timetable	Affiche l'emploi du temps sur une date donnée	dateString: str : date au format année-mois-jour
/homework	Affiche les devoirs entre deux dates données	dateFrom: str : date de début au format année-mois-jour, et dateTo: str : date de fin au même format
/grades	Affiche les notes
/evaluations	Affiche les évaluations par compétences
/absences	Affiche les absences
/punishments	Affiche les punitions
/news	Affiche les actualités
/discussions	Affiche les messages
/menu	Affiche les menus entre deux dates données	dateFrom: str : date de début au format année-mois-jour, et dateTo: str : date de fin au même format
/recipients	Liste toutes les personnes que l'utilisateur peut contacter par message

Voici la liste des URL qui éffectuent une simple fonction :

URL	Utilité	Paramètres	Réponse
/info	Envoie des informations sur l'API comme les ENTs et la version
/export/ical	Exporte le calendrier en iCal		(l'url du fichier iCal)
/homework/changeState	Change l'état d'un devoir (fait/non fait)	dateFrom: str : date de début au format année-mois-jour, et dateTo: str date de fin au même format, et homeworkId: str l'id du devoir à changer	(état du devoir changé)
/discussion/delete	Supprime la discussion	discussionId: str : Id de la discussion	ok si aucun problème
/discussion/readState	Change l'état de lecture d'une discussion	discussionId: str : Id de la discussion	ok si aucun problème
/discussion/reply	Répond à une discussion	discussionId: str : Id de la discussion, et content: str : Contenu du message	ok si aucun problème
/discussion/create	Crée une discussion	recipientId: str : Id du destinataire, content: str : Contenu du message et recipients: list : La liste de destinataire avec leurs ID (obtenu avec /recipients)	ok si aucun problème