aboutsummaryrefslogtreecommitdiffstats
path: root/pydis_site
diff options
context:
space:
mode:
Diffstat (limited to 'pydis_site')
-rw-r--r--pydis_site/apps/api/serializers.py67
-rw-r--r--pydis_site/apps/api/viewsets/bot/nomination.py3
2 files changed, 69 insertions, 1 deletions
diff --git a/pydis_site/apps/api/serializers.py b/pydis_site/apps/api/serializers.py
index 1f19a371..905a7f82 100644
--- a/pydis_site/apps/api/serializers.py
+++ b/pydis_site/apps/api/serializers.py
@@ -1,3 +1,5 @@
+"""Converters from Django models to data interchange formats and back."""
+
from rest_framework.serializers import ModelSerializer, PrimaryKeyRelatedField, ValidationError
from rest_framework_bulk import BulkSerializerMixin
@@ -14,6 +16,8 @@ from .models import (
class BotSettingSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `BotSetting` instances."""
+
class Meta:
"""Metadata defined for the Django REST Framework."""
@@ -22,6 +26,14 @@ class BotSettingSerializer(ModelSerializer):
class DeletedMessageSerializer(ModelSerializer):
+ """
+ A class providing (de-)serialization of `DeletedMessage` instances.
+
+ The serializer generally requires a valid `deletion_context` to be
+ given, which should be created beforehand. See the `DeletedMessage`
+ model for more information.
+ """
+
author = PrimaryKeyRelatedField(
queryset=User.objects.all()
)
@@ -44,6 +56,8 @@ class DeletedMessageSerializer(ModelSerializer):
class MessageDeletionContextSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `MessageDeletionContext` instances."""
+
deletedmessage_set = DeletedMessageSerializer(many=True)
class Meta:
@@ -54,6 +68,14 @@ class MessageDeletionContextSerializer(ModelSerializer):
depth = 1
def create(self, validated_data):
+ """
+ Return a `MessageDeletionContext` based on the given data.
+
+ In addition to the normal attributes expected by the `MessageDeletionContext` model
+ itself, this serializer also allows for passing the `deletedmessage_set` element
+ which contains messages that were deleted as part of this context.
+ """
+
messages = validated_data.pop('deletedmessage_set')
deletion_context = MessageDeletionContext.objects.create(**validated_data)
for message in messages:
@@ -66,6 +88,8 @@ class MessageDeletionContextSerializer(ModelSerializer):
class DocumentationLinkSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `DocumentationLink` instances."""
+
class Meta:
"""Metadata defined for the Django REST Framework."""
@@ -74,6 +98,8 @@ class DocumentationLinkSerializer(ModelSerializer):
class InfractionSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `Infraction` instances."""
+
class Meta:
"""Metadata defined for the Django REST Framework."""
@@ -83,6 +109,8 @@ class InfractionSerializer(ModelSerializer):
)
def validate(self, attrs):
+ """Validate data constraints for the given data and abort if it is invalid."""
+
infr_type = attrs.get('type')
expires_at = attrs.get('expires_at')
@@ -97,7 +125,15 @@ class InfractionSerializer(ModelSerializer):
class ExpandedInfractionSerializer(InfractionSerializer):
+ """A class providing expanded (de-)serialization of `Infraction` instances.
+
+ In addition to the fields of `Infraction` objects themselves, this
+ serializer also attaches the `user` and `actor` fields when serializing.
+ """
+
def to_representation(self, instance):
+ """Return the dictionary representation of this infraction."""
+
ret = super().to_representation(instance)
user = User.objects.get(id=ret['user'])
@@ -112,6 +148,8 @@ class ExpandedInfractionSerializer(InfractionSerializer):
class LogEntrySerializer(ModelSerializer):
+ """A class providing (de-)serialization of `LogEntry` instances."""
+
class Meta:
"""Metadata defined for the Django REST Framework."""
@@ -123,6 +161,8 @@ class LogEntrySerializer(ModelSerializer):
class OffTopicChannelNameSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `OffTopicChannelName` instances."""
+
class Meta:
"""Metadata defined for the Django REST Framework."""
@@ -130,10 +170,21 @@ class OffTopicChannelNameSerializer(ModelSerializer):
fields = ('name',)
def to_representation(self, obj):
+ """
+ Return the representation of this `OffTopicChannelName`.
+
+ This only returns the name of the off topic channel name. As the model
+ only has a single attribute, it is unnecessary to create a nested dictionary.
+ Additionally, this allows off topic channel name routes to simply return an
+ array of names instead of objects, saving on bandwidth.
+ """
+
return obj.name
class SnakeFactSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `SnakeFact` instances."""
+
class Meta:
"""Metadata defined for the Django REST Framework."""
@@ -142,6 +193,8 @@ class SnakeFactSerializer(ModelSerializer):
class SnakeIdiomSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `SnakeIdiom` instances."""
+
class Meta:
"""Metadata defined for the Django REST Framework."""
@@ -150,6 +203,8 @@ class SnakeIdiomSerializer(ModelSerializer):
class SnakeNameSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `SnakeName` instances."""
+
class Meta:
"""Metadata defined for the Django REST Framework."""
@@ -158,6 +213,8 @@ class SnakeNameSerializer(ModelSerializer):
class SpecialSnakeSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `SpecialSnake` instances."""
+
class Meta:
"""Metadata defined for the Django REST Framework."""
@@ -166,6 +223,8 @@ class SpecialSnakeSerializer(ModelSerializer):
class ReminderSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `Reminder` instances."""
+
author = PrimaryKeyRelatedField(queryset=User.objects.all())
class Meta:
@@ -176,6 +235,8 @@ class ReminderSerializer(ModelSerializer):
class RoleSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `Role` instances."""
+
class Meta:
"""Metadata defined for the Django REST Framework."""
@@ -184,6 +245,8 @@ class RoleSerializer(ModelSerializer):
class TagSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `Tag` instances."""
+
class Meta:
"""Metadata defined for the Django REST Framework."""
@@ -192,6 +255,8 @@ class TagSerializer(ModelSerializer):
class UserSerializer(BulkSerializerMixin, ModelSerializer):
+ """A class providing (de-)serialization of `User` instances."""
+
roles = PrimaryKeyRelatedField(many=True, queryset=Role.objects.all(), required=False)
class Meta:
@@ -203,6 +268,8 @@ class UserSerializer(BulkSerializerMixin, ModelSerializer):
class NominationSerializer(ModelSerializer):
+ """A class providing (de-)serialization of `Nomination` instances."""
+
author = PrimaryKeyRelatedField(queryset=User.objects.all())
user = PrimaryKeyRelatedField(queryset=User.objects.all())
diff --git a/pydis_site/apps/api/viewsets/bot/nomination.py b/pydis_site/apps/api/viewsets/bot/nomination.py
index 2b75f10b..62f5dd48 100644
--- a/pydis_site/apps/api/viewsets/bot/nomination.py
+++ b/pydis_site/apps/api/viewsets/bot/nomination.py
@@ -7,7 +7,8 @@ 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')