diff options
Diffstat (limited to 'pydis_site/apps/api/serializers.py')
| -rw-r--r-- | pydis_site/apps/api/serializers.py | 101 |
1 files changed, 100 insertions, 1 deletions
diff --git a/pydis_site/apps/api/serializers.py b/pydis_site/apps/api/serializers.py index 6fb9d826..d58f1fa7 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,23 +16,37 @@ from .models import ( class BotSettingSerializer(ModelSerializer): + """A class providing (de-)serialization of `BotSetting` instances.""" + class Meta: + """Metadata defined for the Django REST Framework.""" + model = BotSetting fields = ('name', 'data') 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() ) 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', @@ -40,14 +56,26 @@ class DeletedMessageSerializer(ModelSerializer): class MessageDeletionContextSerializer(ModelSerializer): + """A class providing (de-)serialization of `MessageDeletionContext` instances.""" + deletedmessage_set = DeletedMessageSerializer(many=True) class Meta: + """Metadata defined for the Django REST Framework.""" + model = MessageDeletionContext fields = ('actor', 'creation', 'id', 'deletedmessage_set') 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: @@ -60,19 +88,29 @@ class MessageDeletionContextSerializer(ModelSerializer): class DocumentationLinkSerializer(ModelSerializer): + """A class providing (de-)serialization of `DocumentationLink` instances.""" + class Meta: + """Metadata defined for the Django REST Framework.""" + model = DocumentationLink fields = ('package', 'base_url', 'inventory_url') class InfractionSerializer(ModelSerializer): + """A class providing (de-)serialization of `Infraction` instances.""" + class Meta: + """Metadata defined for the Django REST Framework.""" + model = Infraction fields = ( 'id', 'inserted_at', 'expires_at', 'active', 'user', 'actor', 'type', 'reason', 'hidden' ) 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') @@ -87,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']) @@ -102,7 +148,11 @@ class ExpandedInfractionSerializer(InfractionSerializer): class LogEntrySerializer(ModelSerializer): + """A class providing (de-)serialization of `LogEntry` instances.""" + class Meta: + """Metadata defined for the Django REST Framework.""" + model = LogEntry fields = ( 'application', 'logger_name', 'timestamp', @@ -111,72 +161,121 @@ class LogEntrySerializer(ModelSerializer): class OffTopicChannelNameSerializer(ModelSerializer): + """A class providing (de-)serialization of `OffTopicChannelName` instances.""" + class Meta: + """Metadata defined for the Django REST Framework.""" + model = OffTopicChannelName 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.""" + model = SnakeFact fields = ('fact',) class SnakeIdiomSerializer(ModelSerializer): + """A class providing (de-)serialization of `SnakeIdiom` instances.""" + class Meta: + """Metadata defined for the Django REST Framework.""" + model = SnakeIdiom fields = ('idiom',) class SnakeNameSerializer(ModelSerializer): + """A class providing (de-)serialization of `SnakeName` instances.""" + class Meta: + """Metadata defined for the Django REST Framework.""" + model = SnakeName fields = ('name', 'scientific') class SpecialSnakeSerializer(ModelSerializer): + """A class providing (de-)serialization of `SpecialSnake` instances.""" + class Meta: + """Metadata defined for the Django REST Framework.""" + model = SpecialSnake fields = ('name', 'images', 'info') class ReminderSerializer(ModelSerializer): + """A class providing (de-)serialization of `Reminder` instances.""" + 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): + """A class providing (de-)serialization of `Role` instances.""" + class Meta: + """Metadata defined for the Django REST Framework.""" + model = Role fields = ('id', 'name', 'colour', 'permissions') class TagSerializer(ModelSerializer): + """A class providing (de-)serialization of `Tag` instances.""" + class Meta: + """Metadata defined for the Django REST Framework.""" + model = Tag fields = ('title', 'embed') class UserSerializer(BulkSerializerMixin, ModelSerializer): + """A class providing (de-)serialization of `User` instances.""" + 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 class NominationSerializer(ModelSerializer): + """A class providing (de-)serialization of `Nomination` instances.""" + actor = PrimaryKeyRelatedField(queryset=User.objects.all()) user = PrimaryKeyRelatedField(queryset=User.objects.all()) class Meta: + """Metadata defined for the Django REST Framework.""" + model = Nomination fields = ( 'id', 'active', 'actor', 'reason', 'user', |