aboutsummaryrefslogtreecommitdiffstats
path: root/pydis_site
diff options
context:
space:
mode:
authorGravatar Gareth Coles <[email protected]>2019-04-21 22:28:57 +0100
committerGravatar Gareth Coles <[email protected]>2019-04-21 22:28:57 +0100
commit1142588abda79d1b3c5a94449cf8074964df9228 (patch)
treeb499b79f0961fa15ceb8bced00559b223d5047b3 /pydis_site
parentFinish linting non-API modules (diff)
A whole bunch of docstrings.
Diffstat (limited to 'pydis_site')
-rw-r--r--pydis_site/apps/api/apps.py2
-rw-r--r--pydis_site/apps/api/models/bot/bot_setting.py1
-rw-r--r--pydis_site/apps/api/models/bot/deleted_message.py2
-rw-r--r--pydis_site/apps/api/models/bot/documentation_link.py1
-rw-r--r--pydis_site/apps/api/models/bot/infraction.py1
-rw-r--r--pydis_site/apps/api/models/bot/message.py3
-rw-r--r--pydis_site/apps/api/models/bot/message_deletion_context.py7
-rw-r--r--pydis_site/apps/api/models/bot/off_topic_channel_name.py3
-rw-r--r--pydis_site/apps/api/models/bot/reminder.py1
-rw-r--r--pydis_site/apps/api/models/bot/role.py3
-rw-r--r--pydis_site/apps/api/models/bot/snake_fact.py1
-rw-r--r--pydis_site/apps/api/models/bot/snake_idiom.py1
-rw-r--r--pydis_site/apps/api/models/bot/snake_name.py1
-rw-r--r--pydis_site/apps/api/models/bot/special_snake.py1
-rw-r--r--pydis_site/apps/api/models/bot/tag.py14
-rw-r--r--pydis_site/apps/api/models/bot/user.py1
-rw-r--r--pydis_site/apps/api/models/utils.py8
-rw-r--r--pydis_site/apps/api/serializers.py34
-rw-r--r--pydis_site/apps/api/tests/base.py6
-rw-r--r--pydis_site/apps/api/views.py6
-rw-r--r--pydis_site/apps/api/viewsets/bot/bot_setting.py4
-rw-r--r--pydis_site/apps/api/viewsets/bot/infraction.py28
-rw-r--r--pydis_site/apps/api/viewsets/bot/nomination.py6
-rw-r--r--pydis_site/apps/api/viewsets/bot/off_topic_channel_name.py25
-rw-r--r--pydis_site/apps/api/viewsets/bot/role.py5
-rw-r--r--pydis_site/apps/api/viewsets/bot/snake_name.py2
-rw-r--r--pydis_site/apps/api/viewsets/log_entry.py3
-rw-r--r--pydis_site/apps/home/apps.py1
28 files changed, 146 insertions, 25 deletions
diff --git a/pydis_site/apps/api/apps.py b/pydis_site/apps/api/apps.py
index d87006dd..76810b2e 100644
--- a/pydis_site/apps/api/apps.py
+++ b/pydis_site/apps/api/apps.py
@@ -2,4 +2,6 @@ from django.apps import AppConfig
class ApiConfig(AppConfig):
+ """Django AppConfig for the API app."""
+
name = 'api'
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}"
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(
diff --git a/pydis_site/apps/api/serializers.py b/pydis_site/apps/api/serializers.py
index 8f045044..1f19a371 100644
--- a/pydis_site/apps/api/serializers.py
+++ b/pydis_site/apps/api/serializers.py
@@ -15,6 +15,8 @@ from .models import (
class BotSettingSerializer(ModelSerializer):
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = BotSetting
fields = ('name', 'data')
@@ -25,12 +27,14 @@ class DeletedMessageSerializer(ModelSerializer):
)
deletion_context = PrimaryKeyRelatedField(
queryset=MessageDeletionContext.objects.all(),
- # This will be overriden in the `create` function
+ # This will be overridden in the `create` function
# of the deletion context serializer.
required=False
)
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = DeletedMessage
fields = (
'id', 'author',
@@ -43,6 +47,8 @@ class MessageDeletionContextSerializer(ModelSerializer):
deletedmessage_set = DeletedMessageSerializer(many=True)
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = MessageDeletionContext
fields = ('actor', 'creation', 'id', 'deletedmessage_set')
depth = 1
@@ -61,12 +67,16 @@ class MessageDeletionContextSerializer(ModelSerializer):
class DocumentationLinkSerializer(ModelSerializer):
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = DocumentationLink
fields = ('package', 'base_url', 'inventory_url')
class InfractionSerializer(ModelSerializer):
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = Infraction
fields = (
'id', 'inserted_at', 'expires_at', 'active', 'user', 'actor', 'type', 'reason', 'hidden'
@@ -103,6 +113,8 @@ class ExpandedInfractionSerializer(InfractionSerializer):
class LogEntrySerializer(ModelSerializer):
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = LogEntry
fields = (
'application', 'logger_name', 'timestamp',
@@ -112,6 +124,8 @@ class LogEntrySerializer(ModelSerializer):
class OffTopicChannelNameSerializer(ModelSerializer):
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = OffTopicChannelName
fields = ('name',)
@@ -121,24 +135,32 @@ class OffTopicChannelNameSerializer(ModelSerializer):
class SnakeFactSerializer(ModelSerializer):
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = SnakeFact
fields = ('fact',)
class SnakeIdiomSerializer(ModelSerializer):
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = SnakeIdiom
fields = ('idiom',)
class SnakeNameSerializer(ModelSerializer):
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = SnakeName
fields = ('name', 'scientific')
class SpecialSnakeSerializer(ModelSerializer):
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = SpecialSnake
fields = ('name', 'images', 'info')
@@ -147,18 +169,24 @@ class ReminderSerializer(ModelSerializer):
author = PrimaryKeyRelatedField(queryset=User.objects.all())
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = Reminder
fields = ('active', 'author', 'channel_id', 'content', 'expiration', 'id')
class RoleSerializer(ModelSerializer):
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = Role
fields = ('id', 'name', 'colour', 'permissions')
class TagSerializer(ModelSerializer):
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = Tag
fields = ('title', 'embed')
@@ -167,6 +195,8 @@ class UserSerializer(BulkSerializerMixin, ModelSerializer):
roles = PrimaryKeyRelatedField(many=True, queryset=Role.objects.all(), required=False)
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = User
fields = ('id', 'avatar_hash', 'name', 'discriminator', 'roles', 'in_guild')
depth = 1
@@ -177,6 +207,8 @@ class NominationSerializer(ModelSerializer):
user = PrimaryKeyRelatedField(queryset=User.objects.all())
class Meta:
+ """Metadata defined for the Django REST Framework."""
+
model = Nomination
fields = ('active', 'author', 'reason', 'user', 'inserted_at')
depth = 1
diff --git a/pydis_site/apps/api/tests/base.py b/pydis_site/apps/api/tests/base.py
index 8f8ace56..37459f70 100644
--- a/pydis_site/apps/api/tests/base.py
+++ b/pydis_site/apps/api/tests/base.py
@@ -13,8 +13,10 @@ test_user, _created = User.objects.get_or_create(
class APISubdomainTestCase(APITestCase):
"""
- Configures the test client to use the proper subdomain
- for requests and forces authentication for the test user.
+ Configures the test client.
+
+ This ensures that it uses the proper subdomain for requests, and forces authentication
+ for the test user.
The test user is considered staff and superuser.
If you want to test for a custom user (for example, to test model permissions),
diff --git a/pydis_site/apps/api/views.py b/pydis_site/apps/api/views.py
index c529da0f..c7dbf5c8 100644
--- a/pydis_site/apps/api/views.py
+++ b/pydis_site/apps/api/views.py
@@ -58,8 +58,10 @@ class RulesView(APIView):
@staticmethod
def _format_link(description, link, target):
"""
- Build the markup necessary to render `link` with `description`
- as its description in the given `target` language.
+ Build the markup for rendering the link.
+
+ This will render `link` with `description` as its description in the given
+ `target` language.
Arguments:
description (str):
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..2b75f10b 100644
--- a/pydis_site/apps/api/viewsets/bot/nomination.py
+++ b/pydis_site/apps/api/viewsets/bot/nomination.py
@@ -13,6 +13,12 @@ class NominationViewSet(ModelViewSet):
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..91adae00 100644
--- a/pydis_site/apps/api/viewsets/bot/snake_name.py
+++ b/pydis_site/apps/api/viewsets/bot/snake_name.py
@@ -41,6 +41,8 @@ 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
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
diff --git a/pydis_site/apps/home/apps.py b/pydis_site/apps/home/apps.py
index 2a2d362a..9a3d213c 100644
--- a/pydis_site/apps/home/apps.py
+++ b/pydis_site/apps/home/apps.py
@@ -3,4 +3,5 @@ from django.apps import AppConfig
class HomeConfig(AppConfig):
"""Django AppConfig for the home app."""
+
name = 'home'