use google convention for docstrings

This commit is contained in:
thomas girod
2024-07-12 09:34:16 +02:00
parent 07b625d4aa
commit 8c69a94488
72 changed files with 970 additions and 1694 deletions

View File

@ -23,6 +23,7 @@
#
import types
from typing import Any
from django.core.exceptions import (
ImproperlyConfigured,
@ -39,6 +40,7 @@ from django.views.generic.detail import SingleObjectMixin
from django.views.generic.edit import FormView
from sentry_sdk import last_event_id
from core.models import User
from core.views.forms import LoginForm
@ -60,60 +62,63 @@ def internal_servor_error(request):
return HttpResponseServerError(render(request, "core/500.jinja"))
def can_edit_prop(obj, user):
"""
:param obj: Object to test for permission
:param user: core.models.User to test permissions against
:return: if user is authorized to edit object properties
:rtype: bool
def can_edit_prop(obj: Any, user: User) -> bool:
"""Can the user edit the properties of the object.
:Example:
Args:
obj: Object to test for permission
user: core.models.User to test permissions against
.. code-block:: python
Returns:
True if user is authorized to edit object properties else False
Examples:
```python
if not can_edit_prop(self.object ,request.user):
raise PermissionDenied
```
"""
if obj is None or user.is_owner(obj):
return True
return False
def can_edit(obj, user):
"""
:param obj: Object to test for permission
:param user: core.models.User to test permissions against
:return: if user is authorized to edit object
:rtype: bool
def can_edit(obj: Any, user: User):
"""Can the user edit the object.
:Example:
Args:
obj: Object to test for permission
user: core.models.User to test permissions against
.. code-block:: python
Returns:
True if user is authorized to edit object else False
if not can_edit(self.object ,request.user):
Examples:
```python
if not can_edit(self.object, request.user):
raise PermissionDenied
```
"""
if obj is None or user.can_edit(obj):
return True
return can_edit_prop(obj, user)
def can_view(obj, user):
"""
:param obj: Object to test for permission
:param user: core.models.User to test permissions against
:return: if user is authorized to see object
:rtype: bool
def can_view(obj: Any, user: User):
"""Can the user see the object.
:Example:
Args:
obj: Object to test for permission
user: core.models.User to test permissions against
.. code-block:: python
Returns:
True if user is authorized to see object else False
Examples:
```python
if not can_view(self.object ,request.user):
raise PermissionDenied
```
"""
if obj is None or user.can_view(obj):
return True
@ -121,20 +126,22 @@ def can_view(obj, user):
class GenericContentPermissionMixinBuilder(View):
"""
Used to build permission mixins
"""Used to build permission mixins.
This view protect any child view that would be showing an object that is restricted based
on two properties
on two properties.
:prop permission_function: function to test permission with, takes an object and an user an return a bool
:prop raised_error: permission to be raised
:raises: raised_error
Attributes:
raised_error: permission to be raised
"""
permission_function = lambda obj, user: False
raised_error = PermissionDenied
@staticmethod
def permission_function(obj: Any, user: User) -> bool:
"""Function to test permission with."""
return False
@classmethod
def get_permission_function(cls, obj, user):
return cls.permission_function(obj, user)
@ -162,11 +169,12 @@ class GenericContentPermissionMixinBuilder(View):
class CanCreateMixin(View):
"""
This view is made to protect any child view that would create an object, and thus, that can not be protected by any
of the following mixin
"""Protect any child view that would create an object.
:raises: PermissionDenied
Raises:
PermissionDenied:
If the user has not the necessary permission
to create the object of the view.
"""
def dispatch(self, request, *arg, **kwargs):
@ -183,55 +191,54 @@ class CanCreateMixin(View):
class CanEditPropMixin(GenericContentPermissionMixinBuilder):
"""
This view is made to protect any child view that would be showing some properties of an object that are restricted
to only the owner group of the given object.
In other word, you can make a view with this view as parent, and it would be retricted to the users that are in the
object's owner_group
"""Ensure the user has owner permissions on the child view object.
:raises: PermissionDenied
In other word, you can make a view with this view as parent,
and it will be retricted to the users that are in the
object's owner_group or that pass the `obj.can_be_viewed_by` test.
Raises:
PermissionDenied: If the user cannot see the object
"""
permission_function = can_edit_prop
class CanEditMixin(GenericContentPermissionMixinBuilder):
"""
This view makes exactly the same thing as its direct parent, but checks the group on the edit_groups field of the
object
"""Ensure the user has permission to edit this view's object.
:raises: PermissionDenied
Raises:
PermissionDenied: if the user cannot edit this view's object.
"""
permission_function = can_edit
class CanViewMixin(GenericContentPermissionMixinBuilder):
"""
This view still makes exactly the same thing as its direct parent, but checks the group on the view_groups field of
the object
"""Ensure the user has permission to view this view's object.
:raises: PermissionDenied
Raises:
PermissionDenied: if the user cannot edit this view's object.
"""
permission_function = can_view
class UserIsRootMixin(GenericContentPermissionMixinBuilder):
"""
This view check if the user is root
"""Allow only root admins.
:raises: PermissionDenied
Raises:
PermissionDenied: if the user isn't root
"""
permission_function = lambda obj, user: user.is_root
class FormerSubscriberMixin(View):
"""
This view check if the user was at least an old subscriber
"""Check if the user was at least an old subscriber.
:raises: PermissionDenied
Raises:
PermissionDenied: if the user never subscribed.
"""
def dispatch(self, request, *args, **kwargs):
@ -241,10 +248,10 @@ class FormerSubscriberMixin(View):
class UserIsLoggedMixin(View):
"""
This view check if the user is logged
"""Check if the user is logged.
:raises: PermissionDenied
Raises:
PermissionDenied:
"""
def dispatch(self, request, *args, **kwargs):
@ -254,9 +261,7 @@ class UserIsLoggedMixin(View):
class TabedViewMixin(View):
"""
This view provide the basic functions for displaying tabs in the template
"""
"""Basic functions for displaying tabs in the template."""
def get_tabs_title(self):
if hasattr(self, "tabs_title"):
@ -299,7 +304,7 @@ class QuickNotifMixin:
return ret
def get_context_data(self, **kwargs):
"""Add quick notifications to context"""
"""Add quick notifications to context."""
kwargs = super().get_context_data(**kwargs)
kwargs["quick_notifs"] = []
for n in self.quick_notif_list:
@ -312,21 +317,15 @@ class QuickNotifMixin:
class DetailFormView(SingleObjectMixin, FormView):
"""
Class that allow both a detail view and a form view
"""
"""Class that allow both a detail view and a form view."""
def get_object(self):
"""
Get current group from id in url
"""
"""Get current group from id in url."""
return self.cached_object
@cached_property
def cached_object(self):
"""
Optimisation on group retrieval
"""
"""Optimisation on group retrieval."""
return super().get_object()

View File

@ -42,8 +42,7 @@ from counter.models import Counter
def send_file(request, file_id, file_class=SithFile, file_attr="file"):
"""
Send a file through Django without loading the whole file into
"""Send a file through Django without loading the whole file into
memory at once. The FileWrapper will turn the file object into an
iterator for chunks of 8KB.
"""
@ -268,7 +267,7 @@ class FileEditPropView(CanEditPropMixin, UpdateView):
class FileView(CanViewMixin, DetailView, FormMixin):
"""This class handle the upload of new files into a folder"""
"""Handle the upload of new files into a folder."""
model = SithFile
pk_url_kwarg = "file_id"
@ -278,8 +277,8 @@ class FileView(CanViewMixin, DetailView, FormMixin):
@staticmethod
def handle_clipboard(request, obj):
"""
This method handles the clipboard in the view.
"""Handle the clipboard in the view.
This method can fail, since it does not catch the exceptions coming from
below, allowing proper handling in the calling view.
Use this method like this:

View File

@ -196,10 +196,9 @@ class RegisteringForm(UserCreationForm):
class UserProfileForm(forms.ModelForm):
"""
Form handling the user profile, managing the files
"""Form handling the user profile, managing the files
This form is actually pretty bad and was made in the rush before the migration. It should be refactored.
TODO: refactor this form
TODO: refactor this form.
"""
class Meta:

View File

@ -13,9 +13,7 @@
#
#
"""
This module contains views to manage Groups
"""
"""Views to manage Groups."""
from ajax_select.fields import AutoCompleteSelectMultipleField
from django import forms
@ -31,9 +29,7 @@ from core.views import CanCreateMixin, CanEditMixin, DetailFormView
class EditMembersForm(forms.Form):
"""
Add and remove members from a Group
"""
"""Add and remove members from a Group."""
def __init__(self, *args, **kwargs):
self.current_users = kwargs.pop("users", [])
@ -53,9 +49,7 @@ class EditMembersForm(forms.Form):
)
def clean_users_added(self):
"""
Check that the user is not trying to add an user already in the group
"""
"""Check that the user is not trying to add an user already in the group."""
cleaned_data = super().clean()
users_added = cleaned_data.get("users_added", None)
if not users_added:
@ -77,9 +71,7 @@ class EditMembersForm(forms.Form):
class GroupListView(CanEditMixin, ListView):
"""
Displays the Group list
"""
"""Displays the Group list."""
model = RealGroup
ordering = ["name"]
@ -87,9 +79,7 @@ class GroupListView(CanEditMixin, ListView):
class GroupEditView(CanEditMixin, UpdateView):
"""
Edit infos of a Group
"""
"""Edit infos of a Group."""
model = RealGroup
pk_url_kwarg = "group_id"
@ -98,9 +88,7 @@ class GroupEditView(CanEditMixin, UpdateView):
class GroupCreateView(CanCreateMixin, CreateView):
"""
Add a new Group
"""
"""Add a new Group."""
model = RealGroup
template_name = "core/create.jinja"
@ -108,9 +96,8 @@ class GroupCreateView(CanCreateMixin, CreateView):
class GroupTemplateView(CanEditMixin, DetailFormView):
"""
Display all users in a given Group
Allow adding and removing users from it
"""Display all users in a given Group
Allow adding and removing users from it.
"""
model = RealGroup
@ -143,9 +130,7 @@ class GroupTemplateView(CanEditMixin, DetailFormView):
class GroupDeleteView(CanEditMixin, DeleteView):
"""
Delete a Group
"""
"""Delete a Group."""
model = RealGroup
pk_url_kwarg = "group_id"

View File

@ -74,9 +74,7 @@ from trombi.views import UserTrombiForm
@method_decorator(check_honeypot, name="post")
class SithLoginView(views.LoginView):
"""
The login View
"""
"""The login View."""
template_name = "core/login.jinja"
authentication_form = LoginForm
@ -85,33 +83,25 @@ class SithLoginView(views.LoginView):
class SithPasswordChangeView(views.PasswordChangeView):
"""
Allows a user to change its password
"""
"""Allows a user to change its password."""
template_name = "core/password_change.jinja"
success_url = reverse_lazy("core:password_change_done")
class SithPasswordChangeDoneView(views.PasswordChangeDoneView):
"""
Allows a user to change its password
"""
"""Allows a user to change its password."""
template_name = "core/password_change_done.jinja"
def logout(request):
"""
The logout view
"""
"""The logout view."""
return views.logout_then_login(request)
def password_root_change(request, user_id):
"""
Allows a root user to change someone's password
"""
"""Allows a root user to change someone's password."""
if not request.user.is_root:
raise PermissionDenied
user = User.objects.filter(id=user_id).first()
@ -131,9 +121,7 @@ def password_root_change(request, user_id):
@method_decorator(check_honeypot, name="post")
class SithPasswordResetView(views.PasswordResetView):
"""
Allows someone to enter an email address for resetting password
"""
"""Allows someone to enter an email address for resetting password."""
template_name = "core/password_reset.jinja"
email_template_name = "core/password_reset_email.jinja"
@ -141,26 +129,20 @@ class SithPasswordResetView(views.PasswordResetView):
class SithPasswordResetDoneView(views.PasswordResetDoneView):
"""
Confirm that the reset email has been sent
"""
"""Confirm that the reset email has been sent."""
template_name = "core/password_reset_done.jinja"
class SithPasswordResetConfirmView(views.PasswordResetConfirmView):
"""
Provide a reset password form
"""
"""Provide a reset password form."""
template_name = "core/password_reset_confirm.jinja"
success_url = reverse_lazy("core:password_reset_complete")
class SithPasswordResetCompleteView(views.PasswordResetCompleteView):
"""
Confirm the password has successfully been reset
"""
"""Confirm the password has successfully been reset."""
template_name = "core/password_reset_complete.jinja"
@ -302,9 +284,7 @@ class UserTabsMixin(TabedViewMixin):
class UserView(UserTabsMixin, CanViewMixin, DetailView):
"""
Display a user's profile
"""
"""Display a user's profile."""
model = User
pk_url_kwarg = "user_id"
@ -321,9 +301,7 @@ class UserView(UserTabsMixin, CanViewMixin, DetailView):
class UserPicturesView(UserTabsMixin, CanViewMixin, DetailView):
"""
Display a user's pictures
"""
"""Display a user's pictures."""
model = User
pk_url_kwarg = "user_id"
@ -361,9 +339,7 @@ def delete_user_godfather(request, user_id, godfather_id, is_father):
class UserGodfathersView(UserTabsMixin, CanViewMixin, DetailView):
"""
Display a user's godfathers
"""
"""Display a user's godfathers."""
model = User
pk_url_kwarg = "user_id"
@ -394,9 +370,7 @@ class UserGodfathersView(UserTabsMixin, CanViewMixin, DetailView):
class UserGodfathersTreeView(UserTabsMixin, CanViewMixin, DetailView):
"""
Display a user's family tree
"""
"""Display a user's family tree."""
model = User
pk_url_kwarg = "user_id"
@ -415,9 +389,7 @@ class UserGodfathersTreeView(UserTabsMixin, CanViewMixin, DetailView):
class UserGodfathersTreePictureView(CanViewMixin, DetailView):
"""
Display a user's tree as a picture
"""
"""Display a user's tree as a picture."""
model = User
pk_url_kwarg = "user_id"
@ -489,9 +461,7 @@ class UserGodfathersTreePictureView(CanViewMixin, DetailView):
class UserStatsView(UserTabsMixin, CanViewMixin, DetailView):
"""
Display a user's stats
"""
"""Display a user's stats."""
model = User
pk_url_kwarg = "user_id"
@ -591,9 +561,7 @@ class UserStatsView(UserTabsMixin, CanViewMixin, DetailView):
class UserMiniView(CanViewMixin, DetailView):
"""
Display a user's profile
"""
"""Display a user's profile."""
model = User
pk_url_kwarg = "user_id"
@ -602,18 +570,14 @@ class UserMiniView(CanViewMixin, DetailView):
class UserListView(ListView, CanEditPropMixin):
"""
Displays the user list
"""
"""Displays the user list."""
model = User
template_name = "core/user_list.jinja"
class UserUploadProfilePictView(CanEditMixin, DetailView):
"""
Handle the upload of the profile picture taken with webcam in navigator
"""
"""Handle the upload of the profile picture taken with webcam in navigator."""
model = User
pk_url_kwarg = "user_id"
@ -650,9 +614,7 @@ class UserUploadProfilePictView(CanEditMixin, DetailView):
class UserUpdateProfileView(UserTabsMixin, CanEditMixin, UpdateView):
"""
Edit a user's profile
"""
"""Edit a user's profile."""
model = User
pk_url_kwarg = "user_id"
@ -663,9 +625,7 @@ class UserUpdateProfileView(UserTabsMixin, CanEditMixin, UpdateView):
board_only = []
def remove_restricted_fields(self, request):
"""
Removes edit_once and board_only fields
"""
"""Removes edit_once and board_only fields."""
for i in self.edit_once:
if getattr(self.form.instance, i) and not (
request.user.is_board_member or request.user.is_root
@ -703,9 +663,7 @@ class UserUpdateProfileView(UserTabsMixin, CanEditMixin, UpdateView):
class UserClubView(UserTabsMixin, CanViewMixin, DetailView):
"""
Display the user's club(s)
"""
"""Display the user's club(s)."""
model = User
context_object_name = "profile"
@ -715,9 +673,7 @@ class UserClubView(UserTabsMixin, CanViewMixin, DetailView):
class UserPreferencesView(UserTabsMixin, CanEditMixin, UpdateView):
"""
Edit a user's preferences
"""
"""Edit a user's preferences."""
model = User
pk_url_kwarg = "user_id"
@ -752,9 +708,7 @@ class UserPreferencesView(UserTabsMixin, CanEditMixin, UpdateView):
class UserUpdateGroupView(UserTabsMixin, CanEditPropMixin, UpdateView):
"""
Edit a user's groups
"""
"""Edit a user's groups."""
model = User
pk_url_kwarg = "user_id"
@ -767,9 +721,7 @@ class UserUpdateGroupView(UserTabsMixin, CanEditPropMixin, UpdateView):
class UserToolsView(QuickNotifMixin, UserTabsMixin, UserIsLoggedMixin, TemplateView):
"""
Displays the logged user's tools
"""
"""Displays the logged user's tools."""
template_name = "core/user_tools.jinja"
current_tab = "tools"
@ -786,9 +738,7 @@ class UserToolsView(QuickNotifMixin, UserTabsMixin, UserIsLoggedMixin, TemplateV
class UserAccountBase(UserTabsMixin, DetailView):
"""
Base class for UserAccount
"""
"""Base class for UserAccount."""
model = User
pk_url_kwarg = "user_id"
@ -809,9 +759,7 @@ class UserAccountBase(UserTabsMixin, DetailView):
class UserAccountView(UserAccountBase):
"""
Display a user's account
"""
"""Display a user's account."""
template_name = "core/user_account.jinja"
@ -858,9 +806,7 @@ class UserAccountView(UserAccountBase):
class UserAccountDetailView(UserAccountBase, YearMixin, MonthMixin):
"""
Display a user's account for month
"""
"""Display a user's account for month."""
template_name = "core/user_account_detail.jinja"