From 1142588abda79d1b3c5a94449cf8074964df9228 Mon Sep 17 00:00:00 2001
From: Gareth Coles <gdude2002@gmail.com>
Date: Sun, 21 Apr 2019 22:28:57 +0100
Subject: A whole bunch of docstrings.

---
 pydis_site/apps/api/models/bot/bot_setting.py              |  1 +
 pydis_site/apps/api/models/bot/deleted_message.py          |  2 ++
 pydis_site/apps/api/models/bot/documentation_link.py       |  1 +
 pydis_site/apps/api/models/bot/infraction.py               |  1 +
 pydis_site/apps/api/models/bot/message.py                  |  3 +++
 pydis_site/apps/api/models/bot/message_deletion_context.py |  7 +++++++
 pydis_site/apps/api/models/bot/off_topic_channel_name.py   |  3 +++
 pydis_site/apps/api/models/bot/reminder.py                 |  1 +
 pydis_site/apps/api/models/bot/role.py                     |  3 ++-
 pydis_site/apps/api/models/bot/snake_fact.py               |  1 +
 pydis_site/apps/api/models/bot/snake_idiom.py              |  1 +
 pydis_site/apps/api/models/bot/snake_name.py               |  1 +
 pydis_site/apps/api/models/bot/special_snake.py            |  1 +
 pydis_site/apps/api/models/bot/tag.py                      | 14 +++++++++++---
 pydis_site/apps/api/models/bot/user.py                     |  1 +
 15 files changed, 37 insertions(+), 4 deletions(-)

(limited to 'pydis_site/apps/api/models/bot')

diff --git a/pydis_site/apps/api/models/bot/bot_setting.py b/pydis_site/apps/api/models/bot/bot_setting.py
index a6eeaa1f..a52f3e34 100644
--- a/pydis_site/apps/api/models/bot/bot_setting.py
+++ b/pydis_site/apps/api/models/bot/bot_setting.py
@@ -6,6 +6,7 @@ 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..f844ae04 100644
--- a/pydis_site/apps/api/models/bot/documentation_link.py
+++ b/pydis_site/apps/api/models/bot/documentation_link.py
@@ -22,4 +22,5 @@ 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..da91d6c2 100644
--- a/pydis_site/apps/api/models/bot/infraction.py
+++ b/pydis_site/apps/api/models/bot/infraction.py
@@ -59,6 +59,7 @@ 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..7332cc8d 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,5 @@ 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..0891f811 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,5 @@ 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..decc9391 100644
--- a/pydis_site/apps/api/models/bot/reminder.py
+++ b/pydis_site/apps/api/models/bot/reminder.py
@@ -41,4 +41,5 @@ 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..34e74009 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,5 @@ 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..e4486d41 100644
--- a/pydis_site/apps/api/models/bot/snake_fact.py
+++ b/pydis_site/apps/api/models/bot/snake_fact.py
@@ -13,4 +13,5 @@ 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..73ce25eb 100644
--- a/pydis_site/apps/api/models/bot/snake_idiom.py
+++ b/pydis_site/apps/api/models/bot/snake_idiom.py
@@ -13,4 +13,5 @@ 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..6d33f872 100644
--- a/pydis_site/apps/api/models/bot/snake_name.py
+++ b/pydis_site/apps/api/models/bot/snake_name.py
@@ -20,4 +20,5 @@ 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..5d38ab6f 100644
--- a/pydis_site/apps/api/models/bot/special_snake.py
+++ b/pydis_site/apps/api/models/bot/special_snake.py
@@ -23,4 +23,5 @@ 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..b75ccec9 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,5 @@ 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..d4deb630 100644
--- a/pydis_site/apps/api/models/bot/user.py
+++ b/pydis_site/apps/api/models/bot/user.py
@@ -49,4 +49,5 @@ 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}"
-- 
cgit v1.2.3


From 341e12e66f56928cebf29be3137ec7f4558cd421 Mon Sep 17 00:00:00 2001
From: Gareth Coles <gdude2002@gmail.com>
Date: Mon, 22 Apr 2019 19:24:58 +0100
Subject: Address the latest review. ✈
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pydis_site/apps/api/models/bot/bot_setting.py            | 1 +
 pydis_site/apps/api/models/bot/documentation_link.py     | 1 +
 pydis_site/apps/api/models/bot/infraction.py             | 1 +
 pydis_site/apps/api/models/bot/message.py                | 1 +
 pydis_site/apps/api/models/bot/off_topic_channel_name.py | 1 +
 pydis_site/apps/api/models/bot/reminder.py               | 1 +
 pydis_site/apps/api/models/bot/role.py                   | 1 +
 pydis_site/apps/api/models/bot/snake_fact.py             | 1 +
 pydis_site/apps/api/models/bot/snake_idiom.py            | 1 +
 pydis_site/apps/api/models/bot/snake_name.py             | 1 +
 pydis_site/apps/api/models/bot/special_snake.py          | 1 +
 pydis_site/apps/api/models/bot/tag.py                    | 1 +
 pydis_site/apps/api/models/bot/user.py                   | 1 +
 pydis_site/apps/api/viewsets/bot/snake_name.py           | 8 +++++++-
 14 files changed, 20 insertions(+), 1 deletion(-)

(limited to 'pydis_site/apps/api/models/bot')

diff --git a/pydis_site/apps/api/models/bot/bot_setting.py b/pydis_site/apps/api/models/bot/bot_setting.py
index a52f3e34..ee9838b7 100644
--- a/pydis_site/apps/api/models/bot/bot_setting.py
+++ b/pydis_site/apps/api/models/bot/bot_setting.py
@@ -7,6 +7,7 @@ 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/documentation_link.py b/pydis_site/apps/api/models/bot/documentation_link.py
index f844ae04..30379396 100644
--- a/pydis_site/apps/api/models/bot/documentation_link.py
+++ b/pydis_site/apps/api/models/bot/documentation_link.py
@@ -23,4 +23,5 @@ 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 da91d6c2..7669352f 100644
--- a/pydis_site/apps/api/models/bot/infraction.py
+++ b/pydis_site/apps/api/models/bot/infraction.py
@@ -60,6 +60,7 @@ 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 7332cc8d..6b566620 100644
--- a/pydis_site/apps/api/models/bot/message.py
+++ b/pydis_site/apps/api/models/bot/message.py
@@ -51,4 +51,5 @@ class Message(ModelReprMixin, models.Model):
 
     class Meta:
         """Metadata provided for Django's ORM."""
+
         abstract = True
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 0891f811..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
@@ -16,4 +16,5 @@ 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 decc9391..ae45b5de 100644
--- a/pydis_site/apps/api/models/bot/reminder.py
+++ b/pydis_site/apps/api/models/bot/reminder.py
@@ -42,4 +42,5 @@ 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 34e74009..ad043bd6 100644
--- a/pydis_site/apps/api/models/bot/role.py
+++ b/pydis_site/apps/api/models/bot/role.py
@@ -46,4 +46,5 @@ 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 e4486d41..c960cbc4 100644
--- a/pydis_site/apps/api/models/bot/snake_fact.py
+++ b/pydis_site/apps/api/models/bot/snake_fact.py
@@ -14,4 +14,5 @@ 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 73ce25eb..0e8f5e94 100644
--- a/pydis_site/apps/api/models/bot/snake_idiom.py
+++ b/pydis_site/apps/api/models/bot/snake_idiom.py
@@ -14,4 +14,5 @@ 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 6d33f872..b6ea6202 100644
--- a/pydis_site/apps/api/models/bot/snake_name.py
+++ b/pydis_site/apps/api/models/bot/snake_name.py
@@ -21,4 +21,5 @@ 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 5d38ab6f..662ff8e3 100644
--- a/pydis_site/apps/api/models/bot/special_snake.py
+++ b/pydis_site/apps/api/models/bot/special_snake.py
@@ -24,4 +24,5 @@ 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 b75ccec9..99819e42 100644
--- a/pydis_site/apps/api/models/bot/tag.py
+++ b/pydis_site/apps/api/models/bot/tag.py
@@ -184,4 +184,5 @@ 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 d4deb630..8b995b59 100644
--- a/pydis_site/apps/api/models/bot/user.py
+++ b/pydis_site/apps/api/models/bot/user.py
@@ -50,4 +50,5 @@ 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/viewsets/bot/snake_name.py b/pydis_site/apps/api/viewsets/bot/snake_name.py
index 91adae00..8e63a542 100644
--- a/pydis_site/apps/api/viewsets/bot/snake_name.py
+++ b/pydis_site/apps/api/viewsets/bot/snake_name.py
@@ -45,7 +45,13 @@ class SnakeNameViewSet(ViewSet):
 
         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)
-- 
cgit v1.2.3