From 9272f53beaca5e37a1901c6b3c4c9d7f8cc25ba4 Mon Sep 17 00:00:00 2001 From: imperosol Date: Tue, 14 Jan 2025 17:14:59 +0100 Subject: [PATCH] fix doc display --- core/auth/api_permissions.py | 4 ++- core/auth/mixins.py | 11 +++---- docs/reference/core/api_permissions.md | 1 - docs/reference/core/auth.md | 32 ++++++++++++++++++++ docs/tutorial/perms.md | 41 +++++++++++++------------- mkdocs.yml | 2 +- 6 files changed, 63 insertions(+), 28 deletions(-) delete mode 100644 docs/reference/core/api_permissions.md create mode 100644 docs/reference/core/auth.md diff --git a/core/auth/api_permissions.py b/core/auth/api_permissions.py index f4da67af..4d83143e 100644 --- a/core/auth/api_permissions.py +++ b/core/auth/api_permissions.py @@ -3,7 +3,8 @@ Some permissions are global (like `IsInGroup` or `IsRoot`), and some others are per-object (like `CanView` or `CanEdit`). -Examples: +Example: + ```python # restrict all the routes of this controller # to subscribed users @api_controller("/foo", permissions=[IsSubscriber]) @@ -33,6 +34,7 @@ Examples: ] def bar_delete(self, bar_id: int): # ... + ``` """ from typing import Any diff --git a/core/auth/mixins.py b/core/auth/mixins.py index c25ecb57..974e9bd1 100644 --- a/core/auth/mixins.py +++ b/core/auth/mixins.py @@ -21,6 +21,7 @@ # Place - Suite 330, Boston, MA 02111-1307, USA. # # +from __future__ import annotations import types import warnings @@ -30,11 +31,11 @@ from django.contrib.auth.mixins import AccessMixin, PermissionRequiredMixin from django.core.exceptions import ImproperlyConfigured, PermissionDenied from django.views.generic.base import View -from core.models import User - if TYPE_CHECKING: from django.db.models import Model + from core.models import User + def can_edit_prop(obj: Any, user: User) -> bool: """Can the user edit the properties of the object. @@ -46,7 +47,7 @@ def can_edit_prop(obj: Any, user: User) -> bool: Returns: True if user is authorized to edit object properties else False - Examples: + Example: ```python if not can_edit_prop(self.object ,request.user): raise PermissionDenied @@ -65,7 +66,7 @@ def can_edit(obj: Any, user: User) -> bool: Returns: True if user is authorized to edit object else False - Examples: + Example: ```python if not can_edit(self.object, request.user): raise PermissionDenied @@ -86,7 +87,7 @@ def can_view(obj: Any, user: User) -> bool: Returns: True if user is authorized to see object else False - Examples: + Example: ```python if not can_view(self.object ,request.user): raise PermissionDenied diff --git a/docs/reference/core/api_permissions.md b/docs/reference/core/api_permissions.md deleted file mode 100644 index 4ab3a2e0..00000000 --- a/docs/reference/core/api_permissions.md +++ /dev/null @@ -1 +0,0 @@ -::: core.auth.api_permissions \ No newline at end of file diff --git a/docs/reference/core/auth.md b/docs/reference/core/auth.md new file mode 100644 index 00000000..ade23f49 --- /dev/null +++ b/docs/reference/core/auth.md @@ -0,0 +1,32 @@ +## Backend + +::: core.auth.backends + handler: python + options: + heading_level: 3 + members: + - SithModelBackend + +## Mixins + +::: core.auth.mixins + handler: python + options: + heading_level: 3 + members: + - can_edit_prop + - can_edit + - can_view + - CanCreateMixin + - CanEditMixin + - CanViewMixin + - FormerSubscriberMixin + - PermissionOrAuthorRequiredMixin + + +## API Permissions + +::: core.auth.api_permissions + handler: python + options: + heading_level: 3 \ No newline at end of file diff --git a/docs/tutorial/perms.md b/docs/tutorial/perms.md index 680c8ad3..c23ca25f 100644 --- a/docs/tutorial/perms.md +++ b/docs/tutorial/perms.md @@ -412,9 +412,9 @@ reposent les vérifications de permission. Elles sont disponibles dans le contexte par défaut du moteur de template et peuvent être utilisées à tout moment. -- [can_edit_prop(obj, user)][core.views.can_edit_prop] : équivalent de `obj.is_owned_by(user)` -- [can_edit(obj, user)][core.views.can_edit] : équivalent de `obj.can_be_edited_by(user)` -- [can_view(obj, user)][core.views.can_view] : équivalent de `obj.can_be_viewed_by(user)` +- [can_edit_prop(obj, user)][core.auth.mixins.can_edit_prop] : équivalent de `obj.is_owned_by(user)` +- [can_edit(obj, user)][core.auth.mixins.can_edit] : équivalent de `obj.can_be_edited_by(user)` +- [can_view(obj, user)][core.auth.mixins.can_view] : équivalent de `obj.can_be_viewed_by(user)` Voici un exemple d'utilisation dans un template : @@ -483,23 +483,24 @@ Les mixins suivants sont implémentés : de création et crée l'objet sans le persister en base de données, puis vérifie les droits sur cet objet non-persisté. Le danger de ce système vient de multiples raisons : - - Les vérifications se faisant sur un objet non persisté, - l'utilisation de mécanismes nécessitant une persistance préalable - peut mener à des comportements indésirés, voire à des erreurs. - - Les développeurs de django ayant tendance à restreindre progressivement - les actions qui peuvent être faites sur des objets non-persistés, - les mises-à-jour de django deviennent plus compliquées. - - La vérification des droits ne se fait que dans les requêtes POST, - à la toute fin de la requête. - Tout ce qui arrive avant n'est absolument pas protégé. - Toute opération (même les suppressions et les créations) qui ont - lieu avant la persistance de l'objet seront appliquées, - même sans permission. - - Si un développeur du site fait l'erreur de surcharger - la méthode `form_valid` (ce qui est plutôt courant, - lorsqu'on veut accomplir certaines actions - quand un formulaire est valide), on peut se retrouver - dans une situation où l'objet est persisté sans aucune protection. + + - Les vérifications se faisant sur un objet non persisté, + l'utilisation de mécanismes nécessitant une persistance préalable + peut mener à des comportements indésirés, voire à des erreurs. + - Les développeurs de django ayant tendance à restreindre progressivement + les actions qui peuvent être faites sur des objets non-persistés, + les mises-à-jour de django deviennent plus compliquées. + - La vérification des droits ne se fait que dans les requêtes POST, + à la toute fin de la requête. + Tout ce qui arrive avant n'est absolument pas protégé. + Toute opération (même les suppressions et les créations) qui ont + lieu avant la persistance de l'objet seront appliquées, + même sans permission. + - Si un développeur du site fait l'erreur de surcharger + la méthode `form_valid` (ce qui est plutôt courant, + lorsqu'on veut accomplir certaines actions + quand un formulaire est valide), on peut se retrouver + dans une situation où l'objet est persisté sans aucune protection. !!!danger "Performance" diff --git a/mkdocs.yml b/mkdocs.yml index 70075794..f307cb8a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -98,7 +98,7 @@ nav: - Champs de modèle: reference/core/model_fields.md - reference/core/views.md - reference/core/schemas.md - - reference/core/api_permissions.md + - reference/core/auth.md - counter: - reference/counter/models.md - reference/counter/views.md