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

[#192] Flake8-docstrings

16 files changed, 53 insertions, 9 deletions

diff --git a/pydis_site/apps/api/models/bot/bot_setting.py b/pydis_site/apps/api/models/bot/bot_setting.py
index a6eeaa1f..ee9838b7 100644
--- a/pydis_site/apps/api/models/bot/bot_setting.py
+++ b/pydis_site/apps/api/models/bot/bot_setting.py
@@ -6,6 +6,8 @@ from pydis_site.apps.api.models.utils import ModelReprMixin
 
 
 def validate_bot_setting_name(name):
+    """Raises a ValidationError if the given name is not a known setting."""
+
     known_settings = (
         'defcon',
     )
diff --git a/pydis_site/apps/api/models/bot/deleted_message.py b/pydis_site/apps/api/models/bot/deleted_message.py
index 0f46cd12..eb7f4c89 100644
--- a/pydis_site/apps/api/models/bot/deleted_message.py
+++ b/pydis_site/apps/api/models/bot/deleted_message.py
@@ -5,6 +5,8 @@ from pydis_site.apps.api.models.bot.message_deletion_context import MessageDelet
 
 
 class DeletedMessage(Message):
+    """A deleted message, previously sent somewhere on the Discord server."""
+
     deletion_context = models.ForeignKey(
         MessageDeletionContext,
         help_text="The deletion context this message is part of.",
diff --git a/pydis_site/apps/api/models/bot/documentation_link.py b/pydis_site/apps/api/models/bot/documentation_link.py
index d7df22ad..30379396 100644
--- a/pydis_site/apps/api/models/bot/documentation_link.py
+++ b/pydis_site/apps/api/models/bot/documentation_link.py
@@ -22,4 +22,6 @@ class DocumentationLink(ModelReprMixin, models.Model):
     )
 
     def __str__(self):
+        """Returns the package and URL for the current documentation link, for display purposes."""
+
         return f"{self.package} - {self.base_url}"
diff --git a/pydis_site/apps/api/models/bot/infraction.py b/pydis_site/apps/api/models/bot/infraction.py
index 911ca589..7669352f 100644
--- a/pydis_site/apps/api/models/bot/infraction.py
+++ b/pydis_site/apps/api/models/bot/infraction.py
@@ -59,6 +59,8 @@ class Infraction(ModelReprMixin, models.Model):
     )
 
     def __str__(self):
+        """Returns some info on the current infraction, for display purposes."""
+
         s = f"#{self.id}: {self.type} on {self.user_id}"
         if self.expires_at:
             s += f" until {self.expires_at}"
diff --git a/pydis_site/apps/api/models/bot/message.py b/pydis_site/apps/api/models/bot/message.py
index 2578d5c6..6b566620 100644
--- a/pydis_site/apps/api/models/bot/message.py
+++ b/pydis_site/apps/api/models/bot/message.py
@@ -8,6 +8,8 @@ from pydis_site.apps.api.models.utils import ModelReprMixin
 
 
 class Message(ModelReprMixin, models.Model):
+    """A message, sent somewhere on the Discord server."""
+
     id = models.BigIntegerField(
         primary_key=True,
         help_text="The message ID as taken from Discord.",
@@ -48,4 +50,6 @@ class Message(ModelReprMixin, models.Model):
     )
 
     class Meta:
+        """Metadata provided for Django's ORM."""
+
         abstract = True
diff --git a/pydis_site/apps/api/models/bot/message_deletion_context.py b/pydis_site/apps/api/models/bot/message_deletion_context.py
index 9904ef71..44a0c8ae 100644
--- a/pydis_site/apps/api/models/bot/message_deletion_context.py
+++ b/pydis_site/apps/api/models/bot/message_deletion_context.py
@@ -5,6 +5,13 @@ from pydis_site.apps.api.models.utils import ModelReprMixin
 
 
 class MessageDeletionContext(ModelReprMixin, models.Model):
+    """
+    Represents the context for a deleted message.
+
+    The context includes its creation date, as well as the actor associated with the deletion.
+    This helps to keep track of message deletions on the server.
+    """
+
     actor = models.ForeignKey(
         User,
         on_delete=models.CASCADE,
diff --git a/pydis_site/apps/api/models/bot/off_topic_channel_name.py b/pydis_site/apps/api/models/bot/off_topic_channel_name.py
index dff7eaf8..2f55a131 100644
--- a/pydis_site/apps/api/models/bot/off_topic_channel_name.py
+++ b/pydis_site/apps/api/models/bot/off_topic_channel_name.py
@@ -5,6 +5,8 @@ from pydis_site.apps.api.models.utils import ModelReprMixin
 
 
 class OffTopicChannelName(ModelReprMixin, models.Model):
+    """An off-topic channel name, used during the daily channel name shuffle."""
+
     name = models.CharField(
         primary_key=True,
         max_length=96,
@@ -13,4 +15,6 @@ class OffTopicChannelName(ModelReprMixin, models.Model):
     )
 
     def __str__(self):
+        """Returns the current off-topic name, for display purposes."""
+
         return self.name
diff --git a/pydis_site/apps/api/models/bot/reminder.py b/pydis_site/apps/api/models/bot/reminder.py
index abccdf82..ae45b5de 100644
--- a/pydis_site/apps/api/models/bot/reminder.py
+++ b/pydis_site/apps/api/models/bot/reminder.py
@@ -41,4 +41,6 @@ class Reminder(ModelReprMixin, models.Model):
     )
 
     def __str__(self):
+        """Returns some info on the current reminder, for display purposes."""
+
         return f"{self.content} on {self.expiration} by {self.author}"
diff --git a/pydis_site/apps/api/models/bot/role.py b/pydis_site/apps/api/models/bot/role.py
index 8106394f..ad043bd6 100644
--- a/pydis_site/apps/api/models/bot/role.py
+++ b/pydis_site/apps/api/models/bot/role.py
@@ -7,7 +7,7 @@ from pydis_site.apps.api.models.utils import ModelReprMixin
 class Role(ModelReprMixin, models.Model):
     """A role on our Discord server."""
 
-    id = models.BigIntegerField(  # noqa
+    id = models.BigIntegerField(
         primary_key=True,
         validators=(
             MinValueValidator(
@@ -45,4 +45,6 @@ class Role(ModelReprMixin, models.Model):
     )
 
     def __str__(self):
+        """Returns the name of the current role, for display purposes."""
+
         return self.name
diff --git a/pydis_site/apps/api/models/bot/snake_fact.py b/pydis_site/apps/api/models/bot/snake_fact.py
index 4398620a..c960cbc4 100644
--- a/pydis_site/apps/api/models/bot/snake_fact.py
+++ b/pydis_site/apps/api/models/bot/snake_fact.py
@@ -13,4 +13,6 @@ class SnakeFact(ModelReprMixin, models.Model):
     )
 
     def __str__(self):
+        """Returns the current snake fact, for display purposes."""
+
         return self.fact
diff --git a/pydis_site/apps/api/models/bot/snake_idiom.py b/pydis_site/apps/api/models/bot/snake_idiom.py
index e4db00e0..0e8f5e94 100644
--- a/pydis_site/apps/api/models/bot/snake_idiom.py
+++ b/pydis_site/apps/api/models/bot/snake_idiom.py
@@ -13,4 +13,6 @@ class SnakeIdiom(ModelReprMixin, models.Model):
     )
 
     def __str__(self):
+        """Returns the current idiom, for display purposes."""
+
         return self.idiom
diff --git a/pydis_site/apps/api/models/bot/snake_name.py b/pydis_site/apps/api/models/bot/snake_name.py
index 045a7faa..b6ea6202 100644
--- a/pydis_site/apps/api/models/bot/snake_name.py
+++ b/pydis_site/apps/api/models/bot/snake_name.py
@@ -20,4 +20,6 @@ class SnakeName(ModelReprMixin, models.Model):
     )
 
     def __str__(self):
+        """Returns the regular and scientific name of the current snake, for display purposes."""
+
         return f"{self.name} ({self.scientific})"
diff --git a/pydis_site/apps/api/models/bot/special_snake.py b/pydis_site/apps/api/models/bot/special_snake.py
index 1406b9e0..662ff8e3 100644
--- a/pydis_site/apps/api/models/bot/special_snake.py
+++ b/pydis_site/apps/api/models/bot/special_snake.py
@@ -23,4 +23,6 @@ class SpecialSnake(ModelReprMixin, models.Model):
     )
 
     def __str__(self):
+        """Returns the name of the current snake, for display purposes."""
+
         return self.name
diff --git a/pydis_site/apps/api/models/bot/tag.py b/pydis_site/apps/api/models/bot/tag.py
index 62881ca2..99819e42 100644
--- a/pydis_site/apps/api/models/bot/tag.py
+++ b/pydis_site/apps/api/models/bot/tag.py
@@ -9,6 +9,8 @@ from pydis_site.apps.api.models.utils import ModelReprMixin
 
 
 def validate_tag_embed_fields(fields):
+    """Raises a ValidationError if any of the given embed fields is invalid."""
+
     field_validators = {
         'name': (MaxLengthValidator(limit_value=256),),
         'value': (MaxLengthValidator(limit_value=1024),)
@@ -27,6 +29,8 @@ def validate_tag_embed_fields(fields):
 
 
 def validate_tag_embed_footer(footer):
+    """Raises a ValidationError if the given footer is invalid."""
+
     field_validators = {
         'text': (
             MinLengthValidator(
@@ -51,6 +55,8 @@ def validate_tag_embed_footer(footer):
 
 
 def validate_tag_embed_author(author):
+    """Raises a ValidationError if the given author is invalid."""
+
     field_validators = {
         'name': (
             MinLengthValidator(
@@ -77,8 +83,9 @@ def validate_tag_embed_author(author):
 
 def validate_tag_embed(embed):
     """
-    Validate a JSON document containing an embed as possible to send
-    on Discord. This attempts to rebuild the validation used by Discord
+    Validate a JSON document containing an embed as possible to send on Discord.
+
+    This attempts to rebuild the validation used by Discord
     as well as possible by checking for various embed limits so we can
     ensure that any embed we store here will also be accepted as a
     valid embed by the Discord API.
@@ -90,7 +97,7 @@ def validate_tag_embed(embed):
 
         >>> from django.contrib.postgres import fields as pgfields
         >>> from django.db import models
-        >>> from pydis_site.apps.api.validators import validate_tag_embed
+        >>> from pydis_site.apps.api.models.bot.tag import validate_tag_embed
         >>> class MyMessage(models.Model):
         ...     embed = pgfields.JSONField(
         ...         validators=(
@@ -176,4 +183,6 @@ class Tag(ModelReprMixin, models.Model):
     )
 
     def __str__(self):
+        """Returns the title of this tag, for display purposes."""
+
         return self.title
diff --git a/pydis_site/apps/api/models/bot/user.py b/pydis_site/apps/api/models/bot/user.py
index f5365ed1..8b995b59 100644
--- a/pydis_site/apps/api/models/bot/user.py
+++ b/pydis_site/apps/api/models/bot/user.py
@@ -49,4 +49,6 @@ class User(ModelReprMixin, models.Model):
     )
 
     def __str__(self):
+        """Returns the name and discriminator for the current user, for display purposes."""
+
         return f"{self.name}#{self.discriminator}"
diff --git a/pydis_site/apps/api/models/utils.py b/pydis_site/apps/api/models/utils.py
index 731486e7..8f590392 100644
--- a/pydis_site/apps/api/models/utils.py
+++ b/pydis_site/apps/api/models/utils.py
@@ -2,13 +2,11 @@ from operator import itemgetter
 
 
 class ModelReprMixin:
-    """
-    Adds a `__repr__` method to the model subclassing this
-    mixin which will display the model's class name along
-    with all parameters used to construct the object.
-    """
+    """Mixin providing a `__repr__()` to display model class name and initialisation parameters."""
 
     def __repr__(self):
+        """Returns the current model class name and initialisation parameters."""
+
         attributes = ' '.join(
             f'{attribute}={value!r}'
             for attribute, value in sorted(