Merge pull request #215 from gdude2002/django+192/flake8-docstrings

[#192] Flake8-docstrings

7 files changed, 71 insertions, 13 deletions

diff --git a/pydis_site/apps/api/viewsets/bot/bot_setting.py b/pydis_site/apps/api/viewsets/bot/bot_setting.py
index 5464018a..07f5b170 100644
--- a/pydis_site/apps/api/viewsets/bot/bot_setting.py
+++ b/pydis_site/apps/api/viewsets/bot/bot_setting.py
@@ -6,9 +6,7 @@ from pydis_site.apps.api.serializers import BotSettingSerializer
 
 
 class BotSettingViewSet(RetrieveModelMixin, UpdateModelMixin, GenericViewSet):
-    """
-    View providing update operations on bot setting routes.
-    """
+    """View providing update operations on bot setting routes."""
 
     serializer_class = BotSettingSerializer
     queryset = BotSetting.objects.all()
diff --git a/pydis_site/apps/api/viewsets/bot/infraction.py b/pydis_site/apps/api/viewsets/bot/infraction.py
index 8eacf5c1..4be153e1 100644
--- a/pydis_site/apps/api/viewsets/bot/infraction.py
+++ b/pydis_site/apps/api/viewsets/bot/infraction.py
@@ -122,7 +122,9 @@ class InfractionViewSet(CreateModelMixin, RetrieveModelMixin, ListModelMixin, Ge
     search_fields = ('$reason',)
     frozen_fields = ('id', 'inserted_at', 'type', 'user', 'actor', 'hidden')
 
-    def partial_update(self, request, *args, **kwargs):
+    def partial_update(self, request, *_args, **_kwargs):
+        """Method that handles the nuts and bolts of updating an Infraction."""
+
         for field in request.data:
             if field in self.frozen_fields:
                 raise ValidationError({field: ['This field cannot be updated.']})
@@ -136,20 +138,44 @@ class InfractionViewSet(CreateModelMixin, RetrieveModelMixin, ListModelMixin, Ge
 
     @action(url_path='expanded', detail=False)
     def list_expanded(self, *args, **kwargs):
+        """
+        DRF method for listing Infraction entries.
+
+        Called by the Django Rest Framework in response to the corresponding HTTP request.
+        """
+
         self.serializer_class = ExpandedInfractionSerializer
         return self.list(*args, **kwargs)
 
     @list_expanded.mapping.post
     def create_expanded(self, *args, **kwargs):
+        """
+        DRF method for creating an Infraction.
+
+        Called by the Django Rest Framework in response to the corresponding HTTP request.
+        """
+
         self.serializer_class = ExpandedInfractionSerializer
         return self.create(*args, **kwargs)
 
     @action(url_path='expanded', url_name='detail-expanded', detail=True)
     def retrieve_expanded(self, *args, **kwargs):
+        """
+        DRF method for retrieving a specific Infraction.
+
+        Called by the Django Rest Framework in response to the corresponding HTTP request.
+        """
+
         self.serializer_class = ExpandedInfractionSerializer
         return self.retrieve(*args, **kwargs)
 
     @retrieve_expanded.mapping.patch
     def partial_update_expanded(self, *args, **kwargs):
+        """
+        DRF method for updating an Infraction.
+
+        Called by the Django Rest Framework in response to the corresponding HTTP request.
+        """
+
         self.serializer_class = ExpandedInfractionSerializer
         return self.partial_update(*args, **kwargs)
diff --git a/pydis_site/apps/api/viewsets/bot/nomination.py b/pydis_site/apps/api/viewsets/bot/nomination.py
index 725ae176..62f5dd48 100644
--- a/pydis_site/apps/api/viewsets/bot/nomination.py
+++ b/pydis_site/apps/api/viewsets/bot/nomination.py
@@ -7,12 +7,19 @@ from pydis_site.apps.api.serializers import NominationSerializer
 
 
 class NominationViewSet(ModelViewSet):
-    # TODO: doc me
+    """View providing CRUD operations on helper nominations done through the bot."""
+
     serializer_class = NominationSerializer
     queryset = Nomination.objects.prefetch_related('author', 'user')
     frozen_fields = ('author', 'inserted_at', 'user')
 
     def update(self, request, *args, **kwargs):
+        """
+        DRF method for updating a Nomination.
+
+        Called by the Django Rest Framework in response to the corresponding HTTP request.
+        """
+
         for field in request.data:
             if field in self.frozen_fields:
                 raise ValidationError({field: ['This field cannot be updated.']})
diff --git a/pydis_site/apps/api/viewsets/bot/off_topic_channel_name.py b/pydis_site/apps/api/viewsets/bot/off_topic_channel_name.py
index df51917d..4976c291 100644
--- a/pydis_site/apps/api/viewsets/bot/off_topic_channel_name.py
+++ b/pydis_site/apps/api/viewsets/bot/off_topic_channel_name.py
@@ -11,8 +11,7 @@ from pydis_site.apps.api.serializers import OffTopicChannelNameSerializer
 
 class OffTopicChannelNameViewSet(DestroyModelMixin, ViewSet):
     """
-    View of off-topic channel names used by the bot
-    to rotate our off-topic names on a daily basis.
+    View of off-topic channel names used by the bot to rotate our off-topic names on a daily basis.
 
     ## Routes
     ### GET /bot/off-topic-channel-names
@@ -56,14 +55,28 @@ class OffTopicChannelNameViewSet(DestroyModelMixin, ViewSet):
     serializer_class = OffTopicChannelNameSerializer
 
     def get_object(self):
+        """
+        Returns the OffTopicChannelName entry for this request, if it exists.
+
+        If it doesn't, a HTTP 404 is returned by way of throwing an exception.
+        """
+
         queryset = self.get_queryset()
         name = self.kwargs[self.lookup_field]
         return get_object_or_404(queryset, name=name)
 
     def get_queryset(self):
+        """Returns a queryset that covers the entire OffTopicChannelName table."""
+
         return OffTopicChannelName.objects.all()
 
     def create(self, request):
+        """
+        DRF method for creating a new OffTopicChannelName.
+
+        Called by the Django Rest Framework in response to the corresponding HTTP request.
+        """
+
         if 'name' in request.query_params:
             create_data = {'name': request.query_params['name']}
             serializer = OffTopicChannelNameSerializer(data=create_data)
@@ -76,7 +89,13 @@ class OffTopicChannelNameViewSet(DestroyModelMixin, ViewSet):
                 'name': ["This query parameter is required."]
             })
 
-    def list(self, request):  # noqa
+    def list(self, request):
+        """
+        DRF method for listing OffTopicChannelName entries.
+
+        Called by the Django Rest Framework in response to the corresponding HTTP request.
+        """
+
         if 'random_items' in request.query_params:
             param = request.query_params['random_items']
             try:
diff --git a/pydis_site/apps/api/viewsets/bot/role.py b/pydis_site/apps/api/viewsets/bot/role.py
index 0131b374..213f0a19 100644
--- a/pydis_site/apps/api/viewsets/bot/role.py
+++ b/pydis_site/apps/api/viewsets/bot/role.py
@@ -6,8 +6,9 @@ from pydis_site.apps.api.serializers import RoleSerializer
 
 class RoleViewSet(ModelViewSet):
     """
-    View providing CRUD access to the roles on our server, used
-    by the bot to keep a mirror of our server's roles on the site.
+    View providing CRUD access to the roles on our server.
+
+    This is used by the bot to keep a mirror of our server's roles on the site.
 
     ## Routes
     ### GET /bot/roles
diff --git a/pydis_site/apps/api/viewsets/bot/snake_name.py b/pydis_site/apps/api/viewsets/bot/snake_name.py
index 991706f5..8e63a542 100644
--- a/pydis_site/apps/api/viewsets/bot/snake_name.py
+++ b/pydis_site/apps/api/viewsets/bot/snake_name.py
@@ -41,9 +41,17 @@ class SnakeNameViewSet(ViewSet):
     serializer_class = SnakeNameSerializer
 
     def get_queryset(self):
+        """Returns a queryset that covers the entire SnakeName table."""
+
         return SnakeName.objects.all()
 
-    def list(self, request):  # noqa
+    def list(self, request):
+        """
+        DRF method for listing SnakeName entries.
+
+        Called by the Django Rest Framework in response to the corresponding HTTP request.
+        """
+
         if request.query_params.get('get_all'):
             queryset = self.get_queryset()
             serialized = self.serializer_class(queryset, many=True)
diff --git a/pydis_site/apps/api/viewsets/log_entry.py b/pydis_site/apps/api/viewsets/log_entry.py
index 4aa7dffa..9108a4fa 100644
--- a/pydis_site/apps/api/viewsets/log_entry.py
+++ b/pydis_site/apps/api/viewsets/log_entry.py
@@ -7,8 +7,7 @@ from pydis_site.apps.api.serializers import LogEntrySerializer
 
 class LogEntryViewSet(CreateModelMixin, GenericViewSet):
     """
-    View providing support for creating log entries in the site database
-    for viewing via the log browser.
+    View supporting the creation of log entries in the database for viewing via the log browser.
 
     ## Routes
     ### POST /logs