From 9987d47ec8c74d649de2a7d09ef62beb885949d9 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 27 Jan 2019 21:47:39 +0100 Subject: Documentation: ajout d’une doc sur l’API REST Signed-off-by: Alban Gruin --- Documentation/index.rst | 1 + Documentation/usage/installation.rst | 19 + Documentation/usage/rest.rst | 697 +++++++++++++++++++++++++++++++++++ 3 files changed, 717 insertions(+) create mode 100644 Documentation/usage/rest.rst (limited to 'Documentation') diff --git a/Documentation/index.rst b/Documentation/index.rst index e793dd2..e8dd4f2 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -63,6 +63,7 @@ Utilisation de celcatsanitizer usage/commands/listtimetables usage/commands/reparse usage/commands/timetables + usage/rest usage/versions Développement diff --git a/Documentation/usage/installation.rst b/Documentation/usage/installation.rst index 4dde4f4..75e0be1 100644 --- a/Documentation/usage/installation.rst +++ b/Documentation/usage/installation.rst @@ -8,6 +8,7 @@ celcatsanitizer est écrit en Python 3. Il dépend des bibliothèques suivantes : - `Django 2.0`_ + - `Django REST Framework`_ - requests_, pour récupérer les emplois du temps en HTTP(S) - BeautifulSoup4_ et LXML_, pour parser les emplois du temps en XML - icalendar_, pour générer des fichiers ICS_. @@ -25,6 +26,7 @@ d’installer le module psycopg2_. Pour l’instant, l’installation doit passer par git_. .. _Django 2.0: https://www.djangoproject.com/ +.. _Django REST Framework: https://www.django-rest-framework.org/ .. _requests: http://docs.python-requests.org/en/master/ .. _BeautifulSoup4: https://www.crummy.com/software/BeautifulSoup/bs4/doc/ @@ -155,6 +157,23 @@ Si jamais vous utilisez Django en production, vous **devez impérativement** mettre la valeur de la variable ``DEBUG`` à ``False``. +Configuration de Django REST Framework +`````````````````````````````````````` +Ajoutez la chaîne de caractère ``rest_framework`` à la liste +``INSTALLED_APPS``. + +Libre à vous de configurer DRF de la manière dont vous le souhaitez. +`Les différents paramètres sont accessibles ici`__. Les plus +intéressants sont ``DEFAULT_PERMISSION_CLASSES``, +``DEFAULT_RENDERER_CLASSES``, ``DEFAULT_PAGINATION_CLASS`` et +``PAGE_SIZE``. + +__ https://www.django-rest-framework.org/api-guide/settings/ + +Cette étape est **obligatoire**, mais deviendra optionnelle dans le +futur. Dans le cas ou vous ne souhaiterez pas la faire, l’API REST ne +sera pas activée. + Ajout de celcatsanitizer à la liste des applications Django ``````````````````````````````````````````````````````````` Ajoutez la chaîne de caractère ``edt`` à la liste ``INSTALLED_APPS``. diff --git a/Documentation/usage/rest.rst b/Documentation/usage/rest.rst new file mode 100644 index 0000000..bcaada9 --- /dev/null +++ b/Documentation/usage/rest.rst @@ -0,0 +1,697 @@ +======== +API REST +======== + +celcatsanitizer dispose d’une API REST pour permettre à des outils +tiers d’accéder facilement à ses données, qui sont renvoyées en JSON. +Pour l’instant, il ne permet pas la modification des données. + +Le point d’entrée se trouve à l’adresse ``api/`` de l’instance de +celcatsanitizer. Il retourne la liste des autres points d’accès en +JSON. + +Années +====== + +``api/years/`` +-------------- +Liste les années par ordre alphabétique de nom. :ref:`Le résultat +peut être paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 4, + "next": null, + "previous": null, + "results": [ + { + "id": 3, + "name": "L1", + "slug": "l1" + }, + { + "id": 4, + "name": "L2", + "slug": "l2" + }, + { + "id": 1, + "name": "L3", + "slug": "l3" + }, + { + "id": 2, + "name": "M1", + "slug": "m1" + } + ] + } + +``api/years//`` +------------------- +Retourne seulement une année. + +Exemple : +````````` +.. code:: json + + { + "id": 1, + "name": "L3", + "slug": "l3" + } + +``api/years//timetables`` +----------------------------- +Liste les emplois du temps associés à une année par ordre alphabétique +de nom. :ref:`Le résultat peut être paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": 2, + "name": "1ere année SRI", + "slug": "1ere-annee-sri", + "year": 1, + "source": 2 + }, + { + "id": 1, + "name": "Info", + "slug": "info", + "year": 1, + "source": 1 + } + ] + } + +Emplois du temps +================ + +``api/timetables`` +------------------ +Liste les emplois du temps par ordre d’année (ID associé) puis de nom. +:ref:`Le résultat peut être paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": 1, + "name": "Info", + "slug": "info", + "year": 1, + "source": 1 + } + ] + } + +``api/timetables//`` +------------------------ +Retourne seulement un emploi du temps. + +Exemple : +````````` +.. code:: json + + { + "id": 1, + "name": "Info", + "slug": "info", + "year": 1, + "source": 1 + } + +``api/timetables//groups/`` +------------------------------- +Retourne la liste des groupes associés à un emploi du temps, triés par +ordre alphabétique. :ref:`Le résultat peut être paginé +`. + +Exemple : +````````` +.. code:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": 207, + "name": "L2 Info s1 CMA", + "celcat_name": "L2 Info s1 CMA", + "mention": "L2 Info", + "semester": 1, + "subgroup": "A", + "slug": "l2-info-s1-cma", + "hidden": false, + "source": 1 + }, + { + "id": 208, + "name": "L3 INFO (toutes sections et semestres confondus)", + "celcat_name": "L3 INFO (toutes sections et semestres confondus)", + "mention": "L3 INFO", + "semester": null, + "subgroup": "", + "slug": "l3-info-toutes-sections-et-semestres-confondus", + "hidden": false, + "source": 1 + } + ] + } + +Sources +======= + +``api/sources/`` +---------------- +Retourne la liste des sources par ordre d’ID. :ref:`Le résultat peut +être paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": 1, + "url": "https://edt.univ-tlse3.fr/calendar/default.aspx?View=month&Type=group&ResourceN ame=formation_ELINFE", + "last_update_date": null + }, + { + "id": 2, + "url": "https://edt.univ-tlse3.fr/calendar/default.aspx?View=month&Type=group&ResourceN ame=formation_ELUSR1_s1", + "last_update_date": null + } + ] + } + +``api/sources//`` +--------------------- +Renvoie seulement une source. + +Exemple : +````````` +.. code:: json + + { + "id": 1, + "url": "https://edt.univ-tlse3.fr/calendar/default.aspx?View=month&Type=group&ResourceName=formation_ELINFE", + "last_update_date": null + } + +``api/sources//timetables/`` +-------------------------------- +Renvoie la liste des emplois du temps associé à une source triés par +ordre alphabétique. :ref:`Le résultat peut être paginé +`. + +Exemple : +````````` +.. code:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": 1, + "name": "Info", + "slug": "info", + "year": 1, + "source": 1 + } + ] + } + +Groupes +======= + +``api/groups/`` +--------------- +Liste les groupes par ordre alphabétique. :ref:`Le résultat peut être +paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": 207, + "name": "L2 Info s1 CMA", + "celcat_name": "L2 Info s1 CMA", + "mention": "L2 Info", + "semester": 1, + "subgroup": "A", + "slug": "l2-info-s1-cma", + "hidden": false, + "source": 1 + }, + { + "id": 208, + "name": "L3 INFO (toutes sections et semestres confondus)", + "celcat_name": "L3 INFO (toutes sections et semestres confondus)", + "mention": "L3 INFO", + "semester": null, + "subgroup": "", + "slug": "l3-info-toutes-sections-et-semestres-confondus", + "hidden": false, + "source": 1 + } + ] + } + +``api/groups//`` +-------------------- +Affiche seulement un groupe. + +Exemple : +````````` +.. code:: json + + { + "id": 207, + "name": "L2 Info s1 CMA", + "celcat_name": "L2 Info s1 CMA", + "mention": "L2 Info", + "semester": 1, + "subgroup": "A", + "slug": "l2-info-s1-cma", + "hidden": false, + "source": 1 + } + +.. _ref-groups-courses: + +``api/groups//courses/`` +---------------------------- +Retourne tous les cours d’un groupe et de ses parents triés par ordre +de début. :ref:`Le résultat peut être paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": 34723, + "groups": [ + { + "id": 98, + "name": "L3 INFO s1 CMA", + "celcat_name": "L3 INFO s1 CMA", + "mention": "L3 INFO", + "semester": 1, + "subgroup": "A", + "slug": "l3-info-s1-cma", + "hidden": false, + "source": 1 + }, + { + "id": 207, + "name": "L2 Info s1 CMA", + "celcat_name": "L2 Info s1 CMA", + "mention": "L2 Info", + "semester": 1, + "subgroup": "A", + "slug": "l2-info-s1-cma", + "hidden": false, + "source": 1 + } + ], + "rooms": [], + "name": "REUNION / RENCONTRE", + "type": null, + "notes": "Nuit de l'info", + "begin": "2018-12-06T13:30:00+01:00", + "end": "2018-12-06T23:45:00+01:00", + "last_update": "2018-12-31T13:26:57.122490+01:00", + "source": 1 + }, + { + "id": 34727, + "groups": [ + { + "id": 98, + "name": "L3 INFO s1 CMA", + "celcat_name": "L3 INFO s1 CMA", + "mention": "L3 INFO", + "semester": 1, + "subgroup": "A", + "slug": "l3-info-s1-cma", + "hidden": false, + "source": 1 + }, + { + "id": 207, + "name": "L2 Info s1 CMA", + "celcat_name": "L2 Info s1 CMA", + "mention": "L2 Info", + "semester": 1, + "subgroup": "A", + "slug": "l2-info-s1-cma", + "hidden": false, + "source": 1 + } + ], + "rooms": [], + "name": "REUNION / RENCONTRE", + "type": null, + "notes": "Nuit de l'info", + "begin": "2018-12-07T07:45:00+01:00", + "end": "2018-12-07T23:45:00+01:00", + "last_update": "2018-12-31T13:26:57.136381+01:00", + "source": 1 + } + ] + } + +``api/groups//courses/weeks/`` +---------------------------------- +Retourne la liste des semaines de cours d’un groupe. + +Exemple : +````````` +.. code:: json + + [ + "2018-12-03T00:00:00+01:00" + ] + +``api/groups//courses/weeks/current/`` +------------------------------------------ +Retourne la liste des cours du groupe et de ses parents pendant la +semaine courante (ou prochaine lors du week-end) d’un groupe, par +ordre de début. :ref:`Le résultat peut être paginé `. +Le format du résultat est identique à celui de +:ref:`api/groups/\/courses/ `. + +.. _ref-groups-courses-week-arg: + +``api/groups//courses/weeks///`` +------------------------------------------------ +Retourne la liste des cours du groupe et de ses parents pendant la +semaine spécifiée, par ordre de début. Si l’année et la semaine ne +sont pas des nombres, un code 404 est renvoyé. Si la semaine n’est +pas comprise entre 1 et 53, une erreur 400 est renvoyée, et les +erreurs rencontrées sont renvoyées. :ref:`Le résultat peut être +paginé `. Le format du résultat est identique à celui +de :ref:`api/groups/\/courses/ `. + +Exemple d’erreur (``api/groups//courses/weeks/2018/111/``) : +```````````````````````````````````````````````````````````````` +.. code:: json + + { + "week": "Rentrez une semaine valide" + } + +Salles +====== + +``api/rooms/`` +-------------- +Liste les salles par ordre alphabétique. :ref:`Le résultat peut être +paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 3, + "next": null, + "previous": null, + "results": [ + { + "id": 26, + "name": "1R1-010", + "slug": "1r1-010" + }, + { + "id": 11, + "name": "1TP1-B08", + "slug": "1tp1-b08" + }, + { + "id": 5, + "name": "1TP1-B08bis", + "slug": "1tp1-b08bis" + } + ] + } + +``api/rooms/`` +------------------ +Renvoie une seule salle. + +Exemple : +````````` +.. code:: json + + { + "id": 26, + "name": "1R1-010", + "slug": "1r1-010" + } + +``api/rooms//courses/`` +--------------------------- +Renvoie la liste des cours se déroulant dans une salle par ordre de +début. :ref:`Le résultat peut être paginé `. Le +format du résultat est identique à celui de +:ref:`api/groups/\/courses/ `. + +``api/rooms//courses/weeks/current/`` +----------------------------------------- +Renvoie la liste des cours se déroulant dans une salle pendant la +semaine courante (ou la semaine prochaine le week-end) par ordre de +début. :ref:`Le résultat peut être paginé `. Le +format du résultat est identique à celui de +:ref:`api/groups/\/courses/ `. + +``api/rooms//courses/weeks///`` +----------------------------------------------- +Renvoie la liste des cours se déroulant dans une salle pendant la +semaine spécifiée. Si l’année et la semaine ne sont pas des nombres, +un code 404 est renvoyé. Si la semaine n’est pas comprise entre 1 et +53, une erreur 400 est renvoyée, et les erreurs rencontrées sont +renvoyées. :ref:`Le résultat peut être paginé `. Le +format du résultat est identique à celui de +:ref:`api/groups/\/courses/weeks/\/\ +`. + +``api/rooms/qsjps////`` +---------------------------------------- +Fournit un accès à QSJPS. ```` est une date devant être formatée +de cette manière : ``YYYY-MM-DD``. ```` et ```` sont des +heures qui doivent être formatées de cette manière : ``HH:mm``. La +valeur de ```` doit être inférieure à celle de ````. + +Renvoie la liste des salles vides le début du jour ```` de +```` à ````. + +En cas de mauvais formatage, une erreur 400 est renvoyée, et les +erreurs sont détaillées dans le corps de la réponse. Sinon, la liste +des salles libres est renvoyée. + +Exemple : +````````` +.. code:: json + + [ + { + "id": 26, + "name": "1R1-010", + "slug": "1r1-010" + }, + { + "id": 11, + "name": "1TP1-B08", + "slug": "1tp1-b08" + }, + { + "id": 5, + "name": "1TP1-B08bis", + "slug": "1tp1-b08bis" + } + ] + +Exemple d’erreur (``api/rooms/qsjps/2019-01-35/12:00/10:00/``) : +```````````````````````````````````````````````````````````````` +.. code:: json + + { + "day": [ + "Saisissez une date valide." + ], + "end": [ + "L’heure de début doit être supérieure à celle de fin." + ] + } + +Exemple d’erreur (``api/rooms/qsjps/2019-01-35/12:70/10:70/``) : +```````````````````````````````````````````````````````````````` +.. code:: json + + { + "day": [ + "Saisissez une date valide." + ], + "begin": [ + "Saisissez une heure valide." + ], + "end": [ + "Saisissez une heure valide." + ] + } + +Cours +===== + +``api/courses/`` +---------------- +Renvoie la liste des cours. :ref:`Le résultat peut être paginé +`. + +Exemple : +````````` +.. code:: json + + { + "count": 4766, + "next": "http://localhost:8000/api/courses/?page=2", + "previous": null, + "results": [ + { + "id": 22133, + "groups": [ + { + "id": 98, + "name": "L3 INFO s1 CMA", + "celcat_name": "L3 INFO s1 CMA", + "mention": "L3 INFO", + "semester": 1, + "subgroup": "A", + "slug": "l3-info-s1-cma", + "hidden": false, + "source": 1 + } + ], + "rooms": [ + { + "id": 1, + "name": "Amphi AMPERE (3A)", + "slug": "amphi-ampere-3a" + } + ], + "name": "REUNION / RENCONTRE", + "type": null, + "notes": null, + "begin": "2018-09-04T15:45:00+02:00", + "end": "2018-09-04T16:45:00+02:00", + "last_update": "2018-09-26T19:34:12.924533+02:00", + "source": 1 + }, + … + ] + } + +``api/courses/`` +-------------------- +Renvoie un seul cours. + +Exemple : +````````` +.. code:: json + + { + "id": 22133, + "groups": [ + { + "id": 98, + "name": "L3 INFO s1 CMA", + "celcat_name": "L3 INFO s1 CMA", + "mention": "L3 INFO", + "semester": 1, + "subgroup": "A", + "slug": "l3-info-s1-cma", + "hidden": false, + "source": 1 + } + ], + "rooms": [ + { + "id": 1, + "name": "Amphi AMPERE (3A)", + "slug": "amphi-ampere-3a" + } + ], + "name": "REUNION / RENCONTRE", + "type": null, + "notes": null, + "begin": "2018-09-04T15:45:00+02:00", + "end": "2018-09-04T16:45:00+02:00", + "last_update": "2018-09-26T19:34:12.924533+02:00", + "source": 1 + } + +.. _ref-pagination: + +Pagination +========== +Il est possible que les résultats soient paginés. Cela dépend de la +configuration de l’instance de celcatsanitizer. Dans ce cas, tous les +appels à des points d’accès renvoyant des résultats pouvant être +paginés se trouvent dans ce genre de structure : + +.. code:: json + + { + "count": 4766, + "next": "http://localhost:8000/api/courses/?page=2", + "previous": null, + "results": [ + … + ] + } + + - ``count`` représente le nombre d’éléments au total (et non pas sur + la page). + - ``next`` est le lien de la page de résultats suivants, si il y en a + une. + - ``previous`` est le lien de la page de résultats précédents, si il + y en a une. + - ``results`` est la liste des résultats, si il y en a. -- cgit v1.2.1 From 61eb694cd445fd5f17c4dc6ded0b1d1f5eccdf57 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Tue, 5 Feb 2019 18:00:59 +0100 Subject: Documentation: correction de la doc de l’API Signed-off-by: Alban Gruin --- Documentation/usage/rest.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'Documentation') diff --git a/Documentation/usage/rest.rst b/Documentation/usage/rest.rst index bcaada9..60c8d44 100644 --- a/Documentation/usage/rest.rst +++ b/Documentation/usage/rest.rst @@ -98,8 +98,8 @@ Exemple : Emplois du temps ================ -``api/timetables`` ------------------- +``api/timetables/`` +------------------- Liste les emplois du temps par ordre d’année (ID associé) puis de nom. :ref:`Le résultat peut être paginé `. @@ -688,10 +688,10 @@ paginés se trouvent dans ce genre de structure : ] } - - ``count`` représente le nombre d’éléments au total (et non pas sur - la page). - - ``next`` est le lien de la page de résultats suivants, si il y en a - une. - - ``previous`` est le lien de la page de résultats précédents, si il - y en a une. - - ``results`` est la liste des résultats, si il y en a. +- ``count`` représente le nombre d’éléments au total (et non pas sur + la page). +- ``next`` est le lien de la page de résultats suivants, si il y en a + une. +- ``previous`` est le lien de la page de résultats précédents, si il + y en a une. +- ``results`` est la liste des résultats, si il y en a. -- cgit v1.2.1 From 09a5b8cb97769853ac8a3982bcb340c4c1422498 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Tue, 5 Feb 2019 19:14:48 +0100 Subject: Documentation: ajout des nouvelles routes dans la doc et corrections Signed-off-by: Alban Gruin --- Documentation/usage/rest.rst | 71 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 62 insertions(+), 9 deletions(-) (limited to 'Documentation') diff --git a/Documentation/usage/rest.rst b/Documentation/usage/rest.rst index 60c8d44..4908d8a 100644 --- a/Documentation/usage/rest.rst +++ b/Documentation/usage/rest.rst @@ -64,8 +64,8 @@ Exemple : "slug": "l3" } -``api/years//timetables`` ------------------------------ +``api/years//timetables/`` +------------------------------ Liste les emplois du temps associés à une année par ordre alphabétique de nom. :ref:`Le résultat peut être paginé `. @@ -398,6 +398,41 @@ Exemple : ] } +``api/groups//courses/days/current/`` +----------------------------------------- +Retourne la liste des cours du groupe et de ses parents d’un groupe +pendant le jour courant, par ordre de début. :ref:`Le résultat peut +être paginé `. Le format du résultat est identique à +celui de :ref:`api/groups/\/courses/ `. + +.. _ref-groups-courses-day-arg: + +``api/groups//courses/days////`` +------------------------------------------------------ +Retourne la liste des cours du groupe et de ses parents pendant le +jour spécifié, par ordre de début. Si l’année, le mois ou le jour ne +sont pas des nombres, un code 404 est renvoyé. Si la date est +invalide, une erreur 400 est renvoyée, et les erreurs rencontrées sont +renvoyées. :ref:`Le résultat peut être paginé `. Le +format du résultat est identique à celui de +:ref:`api/groups/\/courses/ `. + +Exemple d’erreur (``api/groups//courses/days/2018/111/22``) : +````````````````````````````````````````````````````````````````` +.. code:: json + + { + "month": "Rentrez un mois valide" + } + +Exemple d’erreur (``api/groups//courses/days/2018/11/33``) : +```````````````````````````````````````````````````````````````` +.. code:: json + + { + "day": "Numéro de jour invalide pour le mois" + } + ``api/groups//courses/weeks/`` ---------------------------------- Retourne la liste des semaines de cours d’un groupe. @@ -423,7 +458,7 @@ Le format du résultat est identique à celui de ``api/groups//courses/weeks///`` ------------------------------------------------ Retourne la liste des cours du groupe et de ses parents pendant la -semaine spécifiée, par ordre de début. Si l’année et la semaine ne +semaine spécifiée, par ordre de début. Si l’année ou la semaine ne sont pas des nombres, un code 404 est renvoyé. Si la semaine n’est pas comprise entre 1 et 53, une erreur 400 est renvoyée, et les erreurs rencontrées sont renvoyées. :ref:`Le résultat peut être @@ -473,8 +508,8 @@ Exemple : ] } -``api/rooms/`` ------------------- +``api/rooms//`` +------------------- Renvoie une seule salle. Exemple : @@ -494,6 +529,24 @@ début. :ref:`Le résultat peut être paginé `. Le format du résultat est identique à celui de :ref:`api/groups/\/courses/ `. +``api/rooms//courses/days/current/`` +---------------------------------------- +Retourne la liste des cours se déroulant dans une salle pendant le +jour courant, par ordre de début. :ref:`Le résultat peut être paginé +`. Le format du résultat est identique à celui de +:ref:`api/groups/\/courses/ `. + +``api/rooms//courses/days////`` +----------------------------------------------------- +Retourne la liste des cours se déroulant dans une salle pendant le +jour spécifié, par ordre de début. Si l’année, le mois ou le jour ne +sont pas des nombres, un code 404 est renvoyé. Si la date est +invalide, une erreur 400 est renvoyée, et les erreurs rencontrées sont +renvoyées. :ref:`Le résultat peut être paginé `. Le +format du résultat est identique à celui de +:ref:`api/groups/\/courses/days/\/\/\/ +`. + ``api/rooms//courses/weeks/current/`` ----------------------------------------- Renvoie la liste des cours se déroulant dans une salle pendant la @@ -505,12 +558,12 @@ format du résultat est identique à celui de ``api/rooms//courses/weeks///`` ----------------------------------------------- Renvoie la liste des cours se déroulant dans une salle pendant la -semaine spécifiée. Si l’année et la semaine ne sont pas des nombres, +semaine spécifiée. Si l’année ou la semaine ne sont pas des nombres, un code 404 est renvoyé. Si la semaine n’est pas comprise entre 1 et 53, une erreur 400 est renvoyée, et les erreurs rencontrées sont renvoyées. :ref:`Le résultat peut être paginé `. Le format du résultat est identique à celui de -:ref:`api/groups/\/courses/weeks/\/\ +:ref:`api/groups/\/courses/weeks/\/\/ `. ``api/rooms/qsjps////`` @@ -629,8 +682,8 @@ Exemple : ] } -``api/courses/`` --------------------- +``api/courses//`` +--------------------- Renvoie un seul cours. Exemple : -- cgit v1.2.1 From d4060a8336554b6f7e154785a1f51f802ee90492 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Wed, 13 Feb 2019 20:04:03 +0100 Subject: commands: ajout d’une commande pour lister les propriétés des cours Pour pouvoir analyser plus facilement les attributs d’un cours, un nouvel outil est rajouté pour lister tous les attributs d’un ou plusieurs cours. Il fait appel au parseur et permet de sélectionner une source, et de limiter le nombre de cours affichés. Signed-off-by: Alban Gruin --- Documentation/index.rst | 1 + Documentation/usage/commands/printvalues.rst | 48 ++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 Documentation/usage/commands/printvalues.rst (limited to 'Documentation') diff --git a/Documentation/index.rst b/Documentation/index.rst index e793dd2..7051b93 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -61,6 +61,7 @@ Utilisation de celcatsanitizer usage/installation usage/commands/cleancourses usage/commands/listtimetables + usage/commands/printvalues usage/commands/reparse usage/commands/timetables usage/versions diff --git a/Documentation/usage/commands/printvalues.rst b/Documentation/usage/commands/printvalues.rst new file mode 100644 index 0000000..7d53d44 --- /dev/null +++ b/Documentation/usage/commands/printvalues.rst @@ -0,0 +1,48 @@ +=============== +``printvalues`` +=============== + +``printvalues`` affiche le contenu brut d’un ou plusieurs cours, sans +chercher à interpréter son contenu ou à l’enregistrer dans la base de +données. + +Utilisation +=========== +.. code:: shell + + $ ./manage.py printvalues --source id [--limit nb] + +``--source`` permet de spécifier la source depuis laquelle les cours +doivent être récupérés. ``id`` correspond à l’ID de la source, +trouvable à l’aide de la commande :doc:`listtimetables`. + +``--limit`` permet de limiter le nombre de cours affichés. ``nb`` +correspond au nombre maximum de cours affichés. + +Format de sortie +================ +:: + + { + "backColor": "#7D4F72", + "clickDisabled": true, + "doubleClickDisabled": true, + "end": "2019-01-28T09:45:00", + "html": "
(07:45-09:45)
COURS/TD
ELINF6Q1 - BIOLOGIE
L3 INFO s2 CMA
U3-307
", + "id": "76330023", + "moveDisabled": true, + "resizeDisabled": true, + "sort": [], + "start": "2019-01-28T07:45:00", + "tag": [ + "celcat", + "sat_notvalid", + "1", + "reg_notmark", + "ELINF6Q1", + "7491453" + ], + "text": "(07:45-09:45)
COURS/TD
ELINF6Q1 - BIOLOGIE
L3 INFO s2 CMA
U3-307", + "toolTip": "(07:45-09:45)
COURS/TD
ELINF6Q1 - BIOLOGIE
L3 INFO s2 CMA
U3-307" + } + Done. -- cgit v1.2.1 From c2a2f5aac817d4255c30c447808ec08faecda036 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 9 Jun 2019 19:41:38 +0200 Subject: api: ajout d’un paramètre pour activer ou non l’API L’API devient optionnelle, et un paramètre, CS_ENABLE_API, est rajouté pour sélectionner son état (activé ou non). Par défaut, il est désactivé. La documentation est mise à jour pour refléter ces changements. Signed-off-by: Alban Gruin --- Documentation/usage/installation.rst | 58 ++++++++++++++++++++++++------------ Documentation/usage/rest.rst | 3 ++ 2 files changed, 42 insertions(+), 19 deletions(-) (limited to 'Documentation') diff --git a/Documentation/usage/installation.rst b/Documentation/usage/installation.rst index 75e0be1..92b3c5d 100644 --- a/Documentation/usage/installation.rst +++ b/Documentation/usage/installation.rst @@ -8,11 +8,14 @@ celcatsanitizer est écrit en Python 3. Il dépend des bibliothèques suivantes : - `Django 2.0`_ - - `Django REST Framework`_ - requests_, pour récupérer les emplois du temps en HTTP(S) - BeautifulSoup4_ et LXML_, pour parser les emplois du temps en XML - icalendar_, pour générer des fichiers ICS_. +Une dépendance est optionnelle : + + - `Django REST Framework`_, pour l’:doc:`API REST `. + celcatsanitizer requiert Python 3.4 au minimum, et marche avec les versions 3.5 et 3.6. Les versions antérieures de Python 3 n’ont pas étés testées, et les versions supérieures devraient fonctionner sans @@ -26,13 +29,13 @@ d’installer le module psycopg2_. Pour l’instant, l’installation doit passer par git_. .. _Django 2.0: https://www.djangoproject.com/ -.. _Django REST Framework: https://www.django-rest-framework.org/ .. _requests: http://docs.python-requests.org/en/master/ .. _BeautifulSoup4: https://www.crummy.com/software/BeautifulSoup/bs4/doc/ .. _LXML: https://lxml.de/ .. _icalendar: https://icalendar.readthedocs.io/en/latest/ .. _ICS: https://fr.wikipedia.org/wiki/ICalendar +.. _Django REST Framework: https://www.django-rest-framework.org/ .. _PostgreSQL: https://www.postgresql.org/ .. _psycopg2: http://initd.org/psycopg/docs/install.html .. _git: https://git-scm.com/ @@ -97,6 +100,13 @@ psycopg2 : $ pip install psycopg2-binary +Si vous souhaitez activer l’API REST, vous devez installer le module +Django Rest Framework : + +.. code:: shell + + $ pip install djangorestframework + Si vous êtes en production, il est recommandé d’utiliser gunicorn_ si vous n’utilisez pas le serveur Apache. Installez-le de la même manière : @@ -157,23 +167,6 @@ Si jamais vous utilisez Django en production, vous **devez impérativement** mettre la valeur de la variable ``DEBUG`` à ``False``. -Configuration de Django REST Framework -`````````````````````````````````````` -Ajoutez la chaîne de caractère ``rest_framework`` à la liste -``INSTALLED_APPS``. - -Libre à vous de configurer DRF de la manière dont vous le souhaitez. -`Les différents paramètres sont accessibles ici`__. Les plus -intéressants sont ``DEFAULT_PERMISSION_CLASSES``, -``DEFAULT_RENDERER_CLASSES``, ``DEFAULT_PAGINATION_CLASS`` et -``PAGE_SIZE``. - -__ https://www.django-rest-framework.org/api-guide/settings/ - -Cette étape est **obligatoire**, mais deviendra optionnelle dans le -futur. Dans le cas ou vous ne souhaiterez pas la faire, l’API REST ne -sera pas activée. - Ajout de celcatsanitizer à la liste des applications Django ``````````````````````````````````````````````````````````` Ajoutez la chaîne de caractère ``edt`` à la liste ``INSTALLED_APPS``. @@ -251,6 +244,33 @@ Ce paramètre est **optionnel**. __ https://docs.djangoproject.com/fr/2.0/topics/i18n/ +Activation de l’API REST et configuration de Django Rest Framework +`````````````````````````````````````````````````````````````````` +L’API REST permet à des outils tiers d’accéder facilement aux données +gérées par celcatsanitizer. Elle est optionnelle, et est basée sur +Django Rest Framework. :doc:`Plus d’informations sur la page de l’API +REST `. + +Si vous souhaitez l’activer, vous devez d’abord avoir installé Django +REST Framework, puis mettre la variable ``CS_ENABLE_API`` à ``True``. + +.. code:: Python + + CS_ENABLE_API = True + +Ajoutez ensuite la chaîne de caractère ``rest_framework`` à la liste +``INSTALLED_APPS``. + +Libre à vous de configurer DRF de la manière dont vous le souhaitez. +`Les différents paramètres sont accessibles ici`__. Les plus +intéressants sont ``DEFAULT_PERMISSION_CLASSES``, +``DEFAULT_RENDERER_CLASSES``, ``DEFAULT_PAGINATION_CLASS`` et +``PAGE_SIZE``. + +__ https://www.django-rest-framework.org/api-guide/settings/ + +Cette étape est **optionnelle**. + ``urls.py`` ----------- Dans le fichier ``celcatsanitizer/urls.py``, importez la fonction diff --git a/Documentation/usage/rest.rst b/Documentation/usage/rest.rst index 4908d8a..d18eaa5 100644 --- a/Documentation/usage/rest.rst +++ b/Documentation/usage/rest.rst @@ -10,6 +10,9 @@ Le point d’entrée se trouve à l’adresse ``api/`` de l’instance de celcatsanitizer. Il retourne la liste des autres points d’accès en JSON. +En fonction de la configuration de celcatsanitizer, l’API ne sera +peut-être pas disponible. + Années ====== -- cgit v1.2.1 From a6eaecf48f63c37cf851386a45cd4b25ac3ed1e0 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 1 Sep 2019 18:51:10 +0200 Subject: doc: mise à jour de la doc pour la future version 0.16 Signed-off-by: Alban Gruin --- Documentation/dev/roadmap.rst | 6 ++---- Documentation/usage/installation.rst | 25 ++++++++++++------------- Documentation/usage/versions.rst | 32 ++++++++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 17 deletions(-) (limited to 'Documentation') diff --git a/Documentation/dev/roadmap.rst b/Documentation/dev/roadmap.rst index 14cad2a..1ae17af 100644 --- a/Documentation/dev/roadmap.rst +++ b/Documentation/dev/roadmap.rst @@ -2,14 +2,12 @@ Feuille de route ================ -.. _ref-ver-0.15: +.. _ref-ver-0.16: -Version 0.15 +Version 0.16 ============ - Optimisation des requêtes en utilisant des fonctionnalités spécifiques à PostgreSQL si nécessaire - - Utilisation de Django 2.1 et de l’aggrégat ``TruncWeek``. - - Amélioration du parseur UPS2018 et de sa documentation. - Remplacement du moteur de templates de Django par Jinja2_ ? - Améliorations de certaines pages ? diff --git a/Documentation/usage/installation.rst b/Documentation/usage/installation.rst index 92b3c5d..b86b257 100644 --- a/Documentation/usage/installation.rst +++ b/Documentation/usage/installation.rst @@ -7,7 +7,7 @@ Dépendances celcatsanitizer est écrit en Python 3. Il dépend des bibliothèques suivantes : - - `Django 2.0`_ + - `Django 2.2`_ - requests_, pour récupérer les emplois du temps en HTTP(S) - BeautifulSoup4_ et LXML_, pour parser les emplois du temps en XML - icalendar_, pour générer des fichiers ICS_. @@ -16,10 +16,9 @@ Une dépendance est optionnelle : - `Django REST Framework`_, pour l’:doc:`API REST `. -celcatsanitizer requiert Python 3.4 au minimum, et marche avec les -versions 3.5 et 3.6. Les versions antérieures de Python 3 n’ont pas -étés testées, et les versions supérieures devraient fonctionner sans -problèmes. +celcatsanitizer requiert Python 3.6 au minimum. Les versions +supérieures devraient fonctionner sans problèmes, mais pas les +versions antérieures. *A priori*, il est possible d’utiliser n’importe quel SGBD supporté par Django avec celcatsanitizer. Cependant, l’utilisation de @@ -28,7 +27,7 @@ d’installer le module psycopg2_. Pour l’instant, l’installation doit passer par git_. -.. _Django 2.0: https://www.djangoproject.com/ +.. _Django 2.2: https://www.djangoproject.com/ .. _requests: http://docs.python-requests.org/en/master/ .. _BeautifulSoup4: https://www.crummy.com/software/BeautifulSoup/bs4/doc/ @@ -46,12 +45,9 @@ celcatsanitizer utilise des versions assez récentes de Django, notamment en ce qui concerne son ORM. Le passage de Django 1.10 à Django 1.11 s’est fait pour utiliser l’annotation ``ExtractWeek``, le passage de Django 1.11 à Django 2.0 pour utiliser l’attribut -``distinct`` de l’aggrégat ``ArrayAgg``. - -celcatsanitizer passera à Django 2.1 lorsqu’il sortira pour utiliser -l’annotation ``TruncWeek``, pour l’instant implémenté avec une requête -SQL brute. Cette fonctionnalité ne sera nécessaire que pour les -utilisateurs de PostgreSQL. +``distinct`` de l’aggrégat ``ArrayAgg``. Il utilise l’aggrégat +``TruncWeek`` apparu dans Django 2.1, et se base officiellement sur +Django 2.2 pour bénéficier du support à long terme. Installation ============ @@ -191,7 +187,7 @@ __ Sélection du parseur ```````````````````` celcatsanitizer dispose d’un système de parseurs modulaires depuis la -:ref:`version 0.14 `, et embarque par défaut deux +:ref:`version 0.14 `, et embarque par défaut trois parseurs : - ``edt.management.parsers.ups2017``, pour le format utilisé par @@ -201,6 +197,9 @@ parseurs : - ``edt.management.parsers.ups2018``, pour le format utilisé par l’Université Paul Sabatier en 2018. Ce parseur utilise LXML_ et exploite l’IO asynchrone de Python. + - ``edt.management.parsers.ups2019``, pour le format utilisé par + l’Université Paul Sabatier en 2019. Ce parseur utilise le module + JSON standard. Pour spécifier le parseur à utiliser, il faut rajouter une variable ``CS_PARSER``, contenant le parseur à utiliser sous forme de chaîne de diff --git a/Documentation/usage/versions.rst b/Documentation/usage/versions.rst index ed76ce5..d4e6d1f 100644 --- a/Documentation/usage/versions.rst +++ b/Documentation/usage/versions.rst @@ -118,3 +118,35 @@ Version 0.14.4 -------------- - Ajout d’une liste de logiciels lisant les calendriers au format ICS et déconseillant l’usage de Google Calendar. + +.. _ref-ver-0.15: + +Version 0.15 +============ +Changements externes +-------------------- + - Utilisation du nouveau nom de ICSdroid (maintenant ICSx⁵) dans la + page des calendriers. + - Copyright 2019. + +Changements internes +-------------------- + - Ajout de tests pour le parseur UPS2018. + - Ajout du parseur UPS2019. + - Ajout d’une table « modules ». + - Mise à jour de Python. La version minimale supportée est la 3.6. + - Mise à jour de Django et utilisation de TruncWeek. + +Autres remarques +---------------- +Les objectifs originaux de celcatsanitizer consistaient en ceux de la +:ref:`version 0.16 `, à savoir : + + - Optimisation des requêtes en utilisant des fonctionnalités + spécifiques à PostgreSQL si nécessaire + - Remplacement du moteur de templates de Django par Jinja2_. + +.. _Jinja2: http://jinja.pocoo.org/ + +Ils n’ont pas pu être suivis à cause d’un manque de temps et de tests +et ont étés reportés à la version 0.16. -- cgit v1.2.1