diff --git a/core/api.py b/core/api.py index f7f6a044..2f203680 100644 --- a/core/api.py +++ b/core/api.py @@ -1,6 +1,5 @@ from django.conf import settings from django.http import HttpResponse -from ninja import Form from ninja_extra import ControllerBase, api_controller, route from ninja_extra.exceptions import PermissionDenied diff --git a/core/api_permissions.py b/core/api_permissions.py index 2213d164..f23fc970 100644 --- a/core/api_permissions.py +++ b/core/api_permissions.py @@ -4,7 +4,7 @@ Some permissions are global (like `IsInGroup` or `IsRoot`), and some others are per-object (like `CanView` or `CanEdit`). Examples: - ```python + # restrict all the routes of this controller # to subscribed users @api_controller("/foo", permissions=[IsSubscriber]) @@ -44,6 +44,8 @@ from ninja_extra.permissions import BasePermission class IsInGroup(BasePermission): + """Check that the user is in the group whose primary key is given.""" + def __init__(self, group_pk: int): self._group_pk = group_pk @@ -52,21 +54,33 @@ class IsInGroup(BasePermission): class IsRoot(BasePermission): + """Check that the user is root.""" + def has_permission(self, request: HttpRequest, controller: ControllerBase) -> bool: return request.user.is_root class IsSubscriber(BasePermission): + """Check that the user is currently subscribed.""" + def has_permission(self, request: HttpRequest, controller: ControllerBase) -> bool: return request.user.is_subscribed class IsOldSubscriber(BasePermission): + """Check that the user has at least one subscription in its history.""" + def has_permission(self, request: HttpRequest, controller: ControllerBase) -> bool: return request.user.was_subscribed class CanView(BasePermission): + """Check that this user has the permission to view the object of this route. + + Wrap the `user.can_view(obj)` method. + To see an example, look at the exemple in the module docstring. + """ + def has_permission(self, request: HttpRequest, controller: ControllerBase) -> bool: return True @@ -77,6 +91,12 @@ class CanView(BasePermission): class CanEdit(BasePermission): + """Check that this user has the permission to edit the object of this route. + + Wrap the `user.can_edit(obj)` method. + To see an example, look at the exemple in the module docstring. + """ + def has_permission(self, request: HttpRequest, controller: ControllerBase) -> bool: return True @@ -87,6 +107,12 @@ class CanEdit(BasePermission): class IsOwner(BasePermission): + """Check that this user owns the object of this route. + + Wrap the `user.is_owner(obj)` method. + To see an example, look at the exemple in the module docstring. + """ + def has_permission(self, request: HttpRequest, controller: ControllerBase) -> bool: return True diff --git a/docs/reference/core/api_permissions.md b/docs/reference/core/api_permissions.md new file mode 100644 index 00000000..2d693fca --- /dev/null +++ b/docs/reference/core/api_permissions.md @@ -0,0 +1 @@ +::: core.api_permissions \ No newline at end of file diff --git a/docs/reference/core/schemas.md b/docs/reference/core/schemas.md new file mode 100644 index 00000000..610f13ba --- /dev/null +++ b/docs/reference/core/schemas.md @@ -0,0 +1 @@ +::: core.schemas \ No newline at end of file diff --git a/docs/reference/counter/schemas.md b/docs/reference/counter/schemas.md new file mode 100644 index 00000000..4a626d43 --- /dev/null +++ b/docs/reference/counter/schemas.md @@ -0,0 +1 @@ +::: counter.schemas \ No newline at end of file diff --git a/docs/reference/pedagogy/schemas.md b/docs/reference/pedagogy/schemas.md new file mode 100644 index 00000000..ff069acf --- /dev/null +++ b/docs/reference/pedagogy/schemas.md @@ -0,0 +1 @@ +::: pedagogy.schemas \ No newline at end of file diff --git a/docs/reference/sas/schemas.md b/docs/reference/sas/schemas.md new file mode 100644 index 00000000..7dcd8d64 --- /dev/null +++ b/docs/reference/sas/schemas.md @@ -0,0 +1 @@ +::: sas.schemas \ No newline at end of file diff --git a/docs/tutorial/install.md b/docs/tutorial/install.md index d6ee5f5e..9434aec6 100644 --- a/docs/tutorial/install.md +++ b/docs/tutorial/install.md @@ -170,7 +170,14 @@ python manage.py runserver !!!note Le serveur est alors accessible à l'adresse - [http://localhost:8000](http://localhost:8000) ou bien [http://127.0.0.1:8000/](http://127.0.0.1:8000/). + [http://localhost:8000](http://localhost:8000) + ou bien [http://127.0.0.1:8000/](http://127.0.0.1:8000/). + +!!!tip + + Vous trouverez également, à l'adresse + [http://localhost:8000/api/docs](http://localhost:8000/api/docs), + une interface swagger, avec toutes les routes de l'API. ## Générer la documentation diff --git a/docs/tutorial/perms.md b/docs/tutorial/perms.md index a3f210d4..3377b808 100644 --- a/docs/tutorial/perms.md +++ b/docs/tutorial/perms.md @@ -197,3 +197,22 @@ Les mixins suivants sont implémentés : Mais sur les `ListView`, on peut arriver à des temps de réponse extrêmement élevés. +## API + +L'API utilise son propre système de permissions. +Ce n'est pas encore un autre système en parallèle, mais un wrapper +autour de notre système de permissions, afin de l'adapter aux besoins +de l'API. + +En effet, l'interface attendue pour manipuler le plus aisément +possible les permissions des routes d'API avec la librairie que nous +utilisons est différente de notre système, tout en restant adaptable. +(Pour plus de détail, +[voir la doc de la lib](https://eadwincode.github.io/django-ninja-extra/api_controller/api_controller_permission/)). + +Si vous avez bien suivi ce qui a été dit plus haut, +vous ne devriez pas être perdu, étant donné +que le système de permissions de l'API utilise +des noms assez similaires : `IsInGroup`, `IsRoot`, `IsSubscriber`... +Vous pouvez trouver des exemples d'utilisation de ce système +dans [cette partie](../reference/core/api_permissions.md). diff --git a/docs/tutorial/structure.md b/docs/tutorial/structure.md index 1f6b351f..9f96663f 100644 --- a/docs/tutorial/structure.md +++ b/docs/tutorial/structure.md @@ -26,57 +26,55 @@ sith3/ │ └── workflows/ (2) ├── accounting/ (3) │ └── ... -├── api/ (4) +├── club/ (4) │ └── ... -├── club/ (5) +├── com/ (5) │ └── ... -├── com/ (6) +├── core/ (6) │ └── ... -├── core/ (7) +├── counter/ (7) │ └── ... -├── counter/ (8) +├── docs/ (8) │ └── ... -├── docs/ (9) +├── eboutic/ (9) │ └── ... -├── eboutic/ (10) +├── election/ (10) │ └── ... -├── election/ (11) +├── forum/ (11) │ └── ... -├── forum/ (12) +├── galaxy/ (12) │ └── ... -├── galaxy/ (13) +├── launderette/ (13) │ └── ... -├── launderette/ (14) +├── locale/ (14) │ └── ... -├── locale/ (15) +├── matmat/ (15) │ └── ... -├── matmat/ (16) +├── pedagogy/ (16) │ └── ... -├── pedagogy/ (17) +├── rootplace/ (17) │ └── ... -├── rootplace/ (18) +├── sas/ (18) │ └── ... -├── sas/ (19) +├── sith/ (19) │ └── ... -├── sith/ (20) +├── stock/ (20) │ └── ... -├── stock/ (21) +├── subscription/ (21) │ └── ... -├── subscription/ (22) -│ └── ... -├── trombi/ (23) +├── trombi/ (22) │ └── ... │ -├── .coveragerc (24) -├── .envrc (25) +├── .coveragerc (23) +├── .envrc (24) ├── .gitattributes ├── .gitignore ├── .mailmap ├── .env.exemple -├── manage.py (26) -├── mkdocs.yml (27) +├── manage.py (25) +├── mkdocs.yml (26) ├── poetry.lock -├── pyproject.toml (28) +├── pyproject.toml (27) └── README.md ``` @@ -90,40 +88,39 @@ sith3/ Par exemple, le workflow `docs.yml` compile et publie la documentation à chaque push sur la branche `master`. 3. Application de gestion de la comptabilité. -4. Application contenant des routes d'API. -5. Application de gestion des clubs et de leurs membres. -6. Application contenant les fonctionnalités +4. Application de gestion des clubs et de leurs membres. +5. Application contenant les fonctionnalités destinées aux responsables communication de l'AE. -7. Application contenant la modélisation centrale du site. +6. Application contenant la modélisation centrale du site. On en reparle plus loin sur cette page. -8. Application de gestion des comptoirs, des permanences +7. Application de gestion des comptoirs, des permanences sur ces comptoirs et des transactions qui y sont effectuées. -9. Dossier contenant la documentation. -10. Application de gestion de la boutique en ligne. -11. Application de gestion des élections. -12. Application de gestion du forum -13. Application de gestion de la galaxie ; la galaxie +8. Dossier contenant la documentation. +9. Application de gestion de la boutique en ligne. +10. Application de gestion des élections. +11. Application de gestion du forum +12. Application de gestion de la galaxie ; la galaxie est un graphe des niveaux de proximité entre les différents étudiants. -14. Gestion des machines à laver de l'AE -15. Dossier contenant les fichiers de traduction. -16. Fonctionnalités de recherche d'utilisateurs. -17. Le guide des UEs du site, sur lequel les utilisateurs +13. Gestion des machines à laver de l'AE +14. Dossier contenant les fichiers de traduction. +15. Fonctionnalités de recherche d'utilisateurs. +16. Le guide des UEs du site, sur lequel les utilisateurs peuvent également laisser leurs avis. -18. Fonctionnalités utiles aux utilisateurs root. -19. Le SAS, où l'on trouve toutes les photos de l'AE. -20. Application principale du projet, contenant sa configuration. -21. Gestion des stocks des comptoirs. -22. Gestion des cotisations des utilisateurs du site. -23. Gestion des trombinoscopes. -24. Fichier de configuration de coverage. -25. Fichier de configuration de direnv. -26. Fichier généré automatiquement par Django. C'est lui +17. Fonctionnalités utiles aux utilisateurs root. +18. Le SAS, où l'on trouve toutes les photos de l'AE. +19. Application principale du projet, contenant sa configuration. +20. Gestion des stocks des comptoirs. +21. Gestion des cotisations des utilisateurs du site. +22. Gestion des trombinoscopes. +23. Fichier de configuration de coverage. +24. Fichier de configuration de direnv. +25. Fichier généré automatiquement par Django. C'est lui qui permet d'appeler des commandes de gestion du projet avec la syntaxe `python ./manage.py ` -27. Le fichier de configuration de la documentation, +26. Le fichier de configuration de la documentation, avec ses plugins et sa table des matières. -28. Le fichier où sont déclarés les dépendances et la configuration +27. Le fichier où sont déclarés les dépendances et la configuration de certaines d'entre elles. @@ -175,11 +172,13 @@ comme suit : │ └── ... ├── templates/ (2) │ └── ... -├── admin.py (3) -├── models.py (4) -├── tests.py (5) -├── urls.py (6) -└── views.py (7) +├── api.py (3) +├── admin.py (4) +├── models.py (5) +├── tests.py (6) +├── schemas.py (7) +├── urls.py (8) +└── views.py (9) ``` @@ -188,15 +187,17 @@ comme suit : de mettre à jour la base de données. cf. [Gestion des migrations](../howto/migrations.md) 2. Dossier contenant les templates jinja utilisés par cette application. -3. Fichier de configuration de l'interface d'administration. +3. Fichier contenant les routes d'API liées à cette application +4. Fichier de configuration de l'interface d'administration. Ce fichier permet de déclarer les modèles de l'application dans l'interface d'administration. -4. Fichier contenant les modèles de l'application. +5. Fichier contenant les modèles de l'application. Les modèles sont des classes Python qui représentent les tables de la base de données. -5. Fichier contenant les tests de l'application. -6. Configuration des urls de l'application. -7. Fichier contenant les vues de l'application. +6. Fichier contenant les tests de l'application. +7. Schémas de validation de données utilisés principalement dans l'API. +8. Configuration des urls de l'application. +9. Fichier contenant les vues de l'application. Dans les plus grosses applications, ce fichier peut être remplacé par un package `views` dans lequel les vues sont réparties entre diff --git a/mkdocs.yml b/mkdocs.yml index dae8e30c..41a0f144 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -89,9 +89,12 @@ nav: - core: - reference/core/models.md - reference/core/views.md + - reference/core/schemas.md + - reference/core/api_permissions.md - counter: - reference/counter/models.md - reference/counter/views.md + - reference/counter/schemas.md - eboutic: - reference/eboutic/models.md - reference/eboutic/views.md @@ -113,12 +116,14 @@ nav: - pedagogy: - reference/pedagogy/models.md - reference/pedagogy/views.md + - reference/pedagogy/schemas.md - rootplace: - reference/rootplace/models.md - reference/rootplace/views.md - sas: - reference/sas/models.md - reference/sas/views.md + - reference/sas/schemas.md - stock: - reference/stock/models.md - reference/stock/views.md @@ -159,4 +164,4 @@ markdown_extensions: toc_depth: 3 extra_css: - - stylesheets/extra.css \ No newline at end of file + - stylesheets/extra.css