From b66a9230a07ebc4fb5e0f56c8969b103c29e2898 Mon Sep 17 00:00:00 2001 From: Laouen Fernet Date: Tue, 28 Apr 2020 11:59:13 +0200 Subject: [PATCH] Add some docstrings in tickets/ --- tickets/forms.py | 6 ++-- tickets/models.py | 64 ++++++++++++++++++++++++++--------- tickets/preferences/forms.py | 2 +- tickets/preferences/models.py | 2 +- tickets/preferences/views.py | 2 +- tickets/views.py | 29 +++++++++------- 6 files changed, 70 insertions(+), 35 deletions(-) diff --git a/tickets/forms.py b/tickets/forms.py index 3001de8a..86f1a953 100644 --- a/tickets/forms.py +++ b/tickets/forms.py @@ -35,7 +35,7 @@ from .models import Ticket, CommentTicket class NewTicketForm(FormRevMixin, ModelForm): - """ Creation of a ticket""" + """Form used to create tickets.""" class Meta: model = Ticket @@ -53,7 +53,7 @@ class NewTicketForm(FormRevMixin, ModelForm): class EditTicketForm(FormRevMixin, ModelForm): - """ Creation of a ticket""" + """Form used to edit tickets.""" class Meta: model = Ticket @@ -65,7 +65,7 @@ class EditTicketForm(FormRevMixin, ModelForm): class CommentTicketForm(FormRevMixin, ModelForm): - """Edit and create comment to a ticket""" + """Form used to create and edit comments of a ticket.""" class Meta: model = CommentTicket diff --git a/tickets/models.py b/tickets/models.py index 470d9375..c36fa6e0 100644 --- a/tickets/models.py +++ b/tickets/models.py @@ -46,7 +46,23 @@ from .preferences.models import TicketOption class Ticket(AclMixin, models.Model): - """Model of a ticket""" + """Model of a ticket. + + Attributes: + user: User, the user creating the ticket. + title: the title of the ticket, chosen by the user. + description: the main content of the ticket, written by the user to + explain their problem. + date: datetime, the date of creation of the ticket. + email: the email address used to reply to the ticket. + solved: boolean, True if the problem explained in the ticket has been + solved, False otherwise. It is used to see easily which tickets + still require attention. + language: the language of the ticket, used to select the appropriate + template when sending automatic emails, e.g. ticket creation. + request: the request displayed if there is an error when sending emails + related to the ticket. + """ user = models.ForeignKey( "users.User", @@ -86,7 +102,7 @@ class Ticket(AclMixin, models.Model): @cached_property def opened_by(self): - """Return full name of this ticket opener""" + """Get the full name of the user who opened the ticket.""" if self.user: return self.user.get_full_name() else: @@ -94,10 +110,13 @@ class Ticket(AclMixin, models.Model): @cached_property def get_mail(self): - """Return the mail of the owner of this ticket""" + """Get the email address of the user who opened the ticket.""" return self.email or self.user.get_mail def publish_mail(self): + """Send an email for a newly opened ticket to the address set in the + preferences. + """ site_url = GeneralOption.get_cached_value("main_site_url") to_addr = TicketOption.get_cached_value("publish_address") context = {"ticket": self, "site_url": site_url} @@ -120,8 +139,8 @@ class Ticket(AclMixin, models.Model): def can_view(self, user_request, *_args, **_kwargs): - """ Check that the user has the right to view the ticket - or that it is the author""" + """Check that the user has the right to view the ticket + or that it is the author.""" if ( not user_request.has_perm("tickets.view_ticket") and self.user != user_request @@ -136,7 +155,7 @@ class Ticket(AclMixin, models.Model): @staticmethod def can_view_all(user_request, *_args, **_kwargs): - """ Check that the user has access to the list of all tickets""" + """Check that the user has access to the list of all tickets.""" can = user_request.has_perm("tickets.view_ticket") return ( can, @@ -147,12 +166,23 @@ class Ticket(AclMixin, models.Model): ) def can_create(user_request, *_args, **_kwargs): - """ Authorise all users to open tickets """ + """Authorise all users to open tickets.""" return True, None, None class CommentTicket(AclMixin, models.Model): - """A comment of a ticket""" + """A comment of a ticket. + + Attributes: + date: datetime, the date of creation of the comment. + comment: the text written as a comment to a ticket. + parent_ticket: the ticket which is commented. + created_at: datetime, the date of creation of the comment. + created_by: the user who wrote the comment. + request: the request used if there is an error when sending emails + related to the comment. + """ + date = models.DateTimeField(auto_now_add=True) comment = models.TextField( max_length=4095, @@ -180,8 +210,8 @@ class CommentTicket(AclMixin, models.Model): return CommentTicket.objects.filter(parent_ticket=self.parent_ticket, pk__lt=self.pk).count() + 1 def can_view(self, user_request, *_args, **_kwargs): - """ Check that the user has the right to view the ticket comment - or that it is the author""" + """Check that the user has the right to view the ticket comment + or that it is the author.""" if ( not user_request.has_perm("tickets.view_commentticket") and self.parent_ticket.user != user_request @@ -195,8 +225,8 @@ class CommentTicket(AclMixin, models.Model): return True, None, None def can_edit(self, user_request, *_args, **_kwargs): - """ Check that the user has the right to edit the ticket comment - or that it is the author""" + """Check that the user has the right to edit the ticket comment + or that it is the author.""" if ( not user_request.has_perm("tickets.change_commentticket") and (self.parent_ticket.user != user_request or self.parent_ticket.user != self.created_by) @@ -211,7 +241,7 @@ class CommentTicket(AclMixin, models.Model): @staticmethod def can_view_all(user_request, *_args, **_kwargs): - """ Check that the user has access to the list of all tickets comments""" + """Check that the user has access to the list of all tickets comments.""" can = user_request.has_perm("tickets.view_commentticket") return ( can, @@ -225,7 +255,9 @@ class CommentTicket(AclMixin, models.Model): return "Comment " + str(self.comment_id) + " on " + str(self.parent_ticket) def publish_mail(self): - """Send mail to user and admin after new comment""" + """Send an email for a newly written comment to the ticket's author and + to the address set in the preferences. + """ site_url = GeneralOption.get_cached_value("main_site_url") to_addr = TicketOption.get_cached_value("publish_address") context = {"comment": self, "site_url": site_url} @@ -246,7 +278,7 @@ class CommentTicket(AclMixin, models.Model): @receiver(post_save, sender=Ticket) def ticket_post_save(**kwargs): - """ Send the mail to publish the new ticket """ + """Call the method to publish an email when a ticket is created.""" if kwargs["created"]: if TicketOption.get_cached_value("publish_address"): ticket = kwargs["instance"] @@ -255,7 +287,7 @@ def ticket_post_save(**kwargs): @receiver(post_save, sender=CommentTicket) def comment_post_save(**kwargs): - """ Send the mail to publish the new comment """ + """Call the method to publish an email when a comment is created.""" if kwargs["created"]: if TicketOption.get_cached_value("publish_address"): comment = kwargs["instance"] diff --git a/tickets/preferences/forms.py b/tickets/preferences/forms.py index 04845ab8..4d3f16d3 100644 --- a/tickets/preferences/forms.py +++ b/tickets/preferences/forms.py @@ -32,7 +32,7 @@ from .models import TicketOption class EditTicketOptionForm(FormRevMixin, ModelForm): - """ Edit the ticket's settings""" + """Form used to edit the settings of tickets.""" class Meta: model = TicketOption diff --git a/tickets/preferences/models.py b/tickets/preferences/models.py index d02202f3..221c04a6 100644 --- a/tickets/preferences/models.py +++ b/tickets/preferences/models.py @@ -32,7 +32,7 @@ from preferences.models import PreferencesModel class TicketOption(AclMixin, PreferencesModel): - """ Definition of the ticket's settings""" + """Definition of the settings of tickets.""" publish_address = models.EmailField( help_text=_( diff --git a/tickets/preferences/views.py b/tickets/preferences/views.py index 70637db8..732a7cbe 100644 --- a/tickets/preferences/views.py +++ b/tickets/preferences/views.py @@ -42,7 +42,7 @@ from . import models def aff_preferences(request): - """ View to display the settings of the tickets in the preferences page""" + """View used to display the settings of tickets in the preferences page.""" pref, created = models.TicketOption.objects.get_or_create() context = { "preferences": pref, diff --git a/tickets/views.py b/tickets/views.py index aab6aeae..3d3a8bfa 100644 --- a/tickets/views.py +++ b/tickets/views.py @@ -52,7 +52,7 @@ from .forms import NewTicketForm, EditTicketForm, CommentTicketForm def new_ticket(request): - """ Ticket creation view""" + """View used to display the creation form of tickets.""" ticketform = NewTicketForm(request.POST or None, request=request) if ticketform.is_valid(): ticketform.save() @@ -76,7 +76,7 @@ def new_ticket(request): @login_required @can_view(Ticket) def aff_ticket(request, ticket, ticketid): - """View to display only one ticket""" + """View used to display a single ticket.""" comments = CommentTicket.objects.filter(parent_ticket=ticket) return render( request, @@ -88,7 +88,7 @@ def aff_ticket(request, ticket, ticketid): @login_required @can_edit(Ticket) def change_ticket_status(request, ticket, ticketid): - """View to edit ticket state""" + """View used to change a ticket's status.""" ticket.solved = not ticket.solved ticket.save() return redirect( @@ -99,7 +99,7 @@ def change_ticket_status(request, ticket, ticketid): @login_required @can_edit(Ticket) def edit_ticket(request, ticket, ticketid): - """ Ticket creation view""" + """View used to display the edit form of tickets.""" ticketform = EditTicketForm(request.POST or None, instance=ticket) if ticketform.is_valid(): ticketform.save() @@ -120,7 +120,7 @@ def edit_ticket(request, ticket, ticketid): @login_required @can_view(Ticket) def add_comment(request, ticket, ticketid): - """ Add a comment to a ticket""" + """View used to add a comment to a ticket.""" commentticket = CommentTicketForm(request.POST or None, request=request) if commentticket.is_valid(): commentticket = commentticket.save(commit=False) @@ -139,7 +139,7 @@ def add_comment(request, ticket, ticketid): @login_required @can_edit(CommentTicket) def edit_comment(request, commentticket_instance, **_kwargs): - """ Edit a comment of a ticket""" + """View used to edit a comment of a ticket.""" commentticket = CommentTicketForm(request.POST or None, instance=commentticket_instance) if commentticket.is_valid(): ticketid = commentticket_instance.parent_ticket.id @@ -157,7 +157,7 @@ def edit_comment(request, commentticket_instance, **_kwargs): @login_required @can_delete(CommentTicket) def del_comment(request, commentticket, **_kwargs): - """Delete a comment of a ticket""" + """View used to delete a comment of a ticket.""" if request.method == "POST": ticketid = commentticket.parent_ticket.id commentticket.delete() @@ -173,7 +173,7 @@ def del_comment(request, commentticket, **_kwargs): @login_required @can_view_all(Ticket) def aff_tickets(request): - """ View to display all the tickets """ + """View used to display all tickets.""" tickets_list = Ticket.objects.all().order_by("-date") nbr_tickets = tickets_list.count() nbr_tickets_unsolved = tickets_list.filter(solved=False).count() @@ -198,7 +198,7 @@ def aff_tickets(request): # views cannoniques des apps optionnels def profil(request, user): - """ View to display the ticket's module on the profil""" + """View used to display the tickets on a user's profile.""" tickets_list = Ticket.objects.filter(user=user).all().order_by("-date") nbr_tickets = tickets_list.count() nbr_tickets_unsolved = tickets_list.filter(solved=False).count() @@ -223,16 +223,19 @@ def profil(request, user): def contact(request): - """View to display a contact address on the contact page - used here to display a link to open a ticket""" + """View used to display contact addresses to be used for tickets on the + contact page. + """ return render_to_string("tickets/contact.html") def navbar_user(): - """View to display the ticket link in thet user's dropdown in the navbar""" + """View used to display a link to tickets in the navbar (in the dropdown + menu Users). + """ return ("users", render_to_string("tickets/navbar.html")) def navbar_logout(): - """View to display the ticket link to log out users""" + """View used to display a link to open tickets for logged out users.""" return render_to_string("tickets/navbar_logout.html")