Merge branch 'django' into django+add-role-viewset

1 files changed, 188 insertions, 41 deletions

diff --git a/api/viewsets.py b/api/viewsets.py
index 67e89ea6..ab62f8a7 100644
--- a/api/viewsets.py
+++ b/api/viewsets.py
@@ -1,5 +1,8 @@
 from django.shortcuts import get_object_or_404
-from rest_framework.exceptions import ParseError
+from django_filters.rest_framework import DjangoFilterBackend
+from rest_framework.decorators import action
+from rest_framework.exceptions import ParseError, ValidationError
+from rest_framework.filters import SearchFilter
 from rest_framework.mixins import (
     CreateModelMixin, DestroyModelMixin,
     ListModelMixin, RetrieveModelMixin
@@ -10,18 +13,19 @@ from rest_framework.viewsets import GenericViewSet, ModelViewSet, ViewSet
 from rest_framework_bulk import BulkCreateModelMixin
 
 from .models import (
-    DocumentationLink, Member,
-    OffTopicChannelName,
-    Role, SnakeFact,
-    SnakeIdiom, SnakeName,
-    SpecialSnake, Tag
+    DocumentationLink, Infraction,
+    OffTopicChannelName, Role,
+    SnakeFact, SnakeIdiom,
+    SnakeName, SpecialSnake,
+    Tag, User
 )
 from .serializers import (
-    DocumentationLinkSerializer, MemberSerializer,
-    OffTopicChannelNameSerializer,
+    DocumentationLinkSerializer, ExpandedInfractionSerializer,
+    InfractionSerializer, OffTopicChannelNameSerializer,
     RoleSerializer, SnakeFactSerializer,
     SnakeIdiomSerializer, SnakeNameSerializer,
-    SpecialSnakeSerializer, TagSerializer
+    SpecialSnakeSerializer, TagSerializer,
+    UserSerializer
 )
 
 
@@ -89,6 +93,144 @@ class DocumentationLinkViewSet(
     lookup_field = 'package'
 
 
+class InfractionViewSet(CreateModelMixin, RetrieveModelMixin, ListModelMixin, GenericViewSet):
+    """
+    View providing CRUD operations on infractions for Discord users.
+
+    ## Routes
+    ### GET /bot/infractions
+    Retrieve all infractions.
+    May be filtered by the query parameters.
+
+    #### Query parameters
+    - **active** `bool`: whether the infraction is still active
+    - **actor** `int`: snowflake of the user which applied the infraction
+    - **hidden** `bool`: whether the infraction is a shadow infraction
+    - **search** `str`: regular expression applied to the infraction's reason
+    - **type** `str`: the type of the infraction
+    - **user** `int`: snowflake of the user to which the infraction was applied
+
+    Invalid query parameters are ignored.
+
+    #### Response format
+    >>> [
+    ...     {
+    ...         'id': 5,
+    ...         'inserted_at': '2018-11-22T07:24:06.132307Z',
+    ...         'expires_at': '5018-11-20T15:52:00Z',
+    ...         'active': False,
+    ...         'user': 172395097705414656,
+    ...         'actor': 125435062127820800,
+    ...         'type': 'ban',
+    ...         'reason': 'He terk my jerb!',
+    ...         'hidden': True
+    ...     }
+    ... ]
+
+    #### Status codes
+    - 200: returned on success
+
+    ### GET /bot/infractions/<id:int>
+    Retrieve a single infraction by ID.
+
+    #### Response format
+    See `GET /bot/infractions`.
+
+    #### Status codes
+    - 200: returned on success
+    - 404: if an infraction with the given `id` could not be found
+
+    ### POST /bot/infractions
+    Create a new infraction and return the created infraction.
+    Only `actor`, `type`, and `user` are required.
+    The `actor` and `user` must be users known by the site.
+
+    #### Request body
+    >>> {
+    ...     'active': False,
+    ...     'actor': 125435062127820800,
+    ...     'expires_at': '5018-11-20T15:52:00+00:00',
+    ...     'hidden': True,
+    ...     'type': 'ban',
+    ...     'reason': 'He terk my jerb!',
+    ...     'user': 172395097705414656
+    ... }
+
+    #### Response format
+    See `GET /bot/infractions`.
+
+    #### Status codes
+    - 201: returned on success
+    - 400: if a given user is unknown or a field in the request body is invalid
+
+    ### PATCH /bot/infractions/<id:int>
+    Update the infraction with the given `id` and return the updated infraction.
+    Only `active`, `reason`, and `expires_at` may be updated.
+
+    #### Request body
+    >>> {
+    ...     'active': True,
+    ...     'expires_at': '4143-02-15T21:04:31+00:00',
+    ...     'reason': 'durka derr'
+    ... }
+
+    #### Response format
+    See `GET /bot/infractions`.
+
+    #### Status codes
+    - 200: returned on success
+    - 400: if a field in the request body is invalid or disallowed
+    - 404: if an infraction with the given `id` could not be found
+
+    ### Expanded routes
+    All routes support expansion of `user` and `actor` in responses. To use an expanded route,
+    append `/expanded` to the end of the route e.g. `GET /bot/infractions/expanded`.
+
+    #### Response format
+    See `GET /bot/users/<snowflake:int>` for the expanded formats of `user` and `actor`. Responses
+    are otherwise identical to their non-expanded counterparts.
+    """
+
+    serializer_class = InfractionSerializer
+    queryset = Infraction.objects.all()
+    filter_backends = (DjangoFilterBackend, SearchFilter)
+    filter_fields = ('user__id', 'actor__id', 'active', 'hidden', 'type')
+    search_fields = ('$reason',)
+    frozen_fields = ('id', 'inserted_at', 'type', 'user', 'actor', 'hidden')
+
+    def partial_update(self, request, *args, **kwargs):
+        for field in request.data:
+            if field in self.frozen_fields:
+                raise ValidationError({field: ['This field cannot be updated.']})
+
+        instance = self.get_object()
+        serializer = self.get_serializer(instance, data=request.data, partial=True)
+        serializer.is_valid(raise_exception=True)
+        serializer.save()
+
+        return Response(serializer.data)
+
+    @action(url_path='expanded', detail=False)
+    def list_expanded(self, *args, **kwargs):
+        self.serializer_class = ExpandedInfractionSerializer
+        return self.list(*args, **kwargs)
+
+    @list_expanded.mapping.post
+    def create_expanded(self, *args, **kwargs):
+        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):
+        self.serializer_class = ExpandedInfractionSerializer
+        return self.retrieve(*args, **kwargs)
+
+    @retrieve_expanded.mapping.patch
+    def partial_update_expanded(self, *args, **kwargs):
+        self.serializer_class = ExpandedInfractionSerializer
+        return self.partial_update(*args, **kwargs)
+
+
 class OffTopicChannelNameViewSet(DestroyModelMixin, ViewSet):
     """
     View of off-topic channel names used by the bot
@@ -266,7 +408,7 @@ class RoleViewSet(ModelViewSet):
     """
 
     queryset = Role.objects.all()
-    serializer = RoleSerializer
+    serializer_class = RoleSerializer
 
 
 class SnakeFactViewSet(ListModelMixin, GenericViewSet):
@@ -456,7 +598,7 @@ class TagViewSet(ModelViewSet):
     - 201: returned on success
     - 400: if one of the given fields is invalid
 
-    ### PUT /bot/members/<title:str>
+    ### PUT /bot/tags/<title:str>
     Update the tag with the given `title`.
 
     #### Request body
@@ -474,7 +616,7 @@ class TagViewSet(ModelViewSet):
     - 400: if the request body was invalid, see response body for details
     - 404: if the tag with the given `title` could not be found
 
-    ### PATCH /bot/members/<title:str>
+    ### PATCH /bot/tags/<title:str>
     Update the tag with the given `title`.
 
     #### Request body
@@ -492,7 +634,7 @@ class TagViewSet(ModelViewSet):
     - 400: if the request body was invalid, see response body for details
     - 404: if the tag with the given `title` could not be found
 
-    ### DELETE /bot/members/<title:str>
+    ### DELETE /bot/tags/<title:str>
     Deletes the tag with the given `title`.
 
     #### Status codes
@@ -504,13 +646,13 @@ class TagViewSet(ModelViewSet):
     queryset = Tag.objects.all()
 
 
-class MemberViewSet(BulkCreateModelMixin, ModelViewSet):
+class UserViewSet(BulkCreateModelMixin, ModelViewSet):
     """
-    View providing CRUD operations on our Discord server's members through the bot.
+    View providing CRUD operations on Discord users through the bot.
 
     ## Routes
-    ### GET /bot/members
-    Returns all members currently known.
+    ### GET /bot/users
+    Returns all users currently known.
 
     #### Response format
     >>> [
@@ -524,15 +666,16 @@ class MemberViewSet(BulkCreateModelMixin, ModelViewSet):
     ...             270988689419665409,
     ...             277546923144249364,
     ...             458226699344019457
-    ...         ]
+    ...         ],
+    ...         'in_guild': True
     ...     }
     ... ]
 
     #### Status codes
     - 200: returned on success
 
-    ### GET /bot/members/<snowflake:int>
-    Gets a single member by ID.
+    ### GET /bot/users/<snowflake:int>
+    Gets a single user by ID.
 
     #### Response format
     >>> {
@@ -545,16 +688,17 @@ class MemberViewSet(BulkCreateModelMixin, ModelViewSet):
     ...         270988689419665409,
     ...         277546923144249364,
     ...         458226699344019457
-    ...     ]
+    ...     ],
+    ...     'in_guild': True
     ... }
 
     #### Status codes
     - 200: returned on success
-    - 404: if a member with the given `snowflake` could not be found
+    - 404: if a user with the given `snowflake` could not be found
 
-    ### POST /bot/members
-    Adds a single or multiple new members.
-    The roles attached to the member(s) must be roles known by the site.
+    ### POST /bot/users
+    Adds a single or multiple new users.
+    The roles attached to the user(s) must be roles known by the site.
 
     #### Request body
     >>> {
@@ -562,18 +706,19 @@ class MemberViewSet(BulkCreateModelMixin, ModelViewSet):
     ...     'avatar': str,
     ...     'name': str,
     ...     'discriminator': int,
-    ...     'roles': List[int]
+    ...     'roles': List[int],
+    ...     'in_guild': bool
     ... }
 
-    Alternatively, request members can be POSTed as a list of above objects,
-    in which case multiple members will be created at once.
+    Alternatively, request users can be POSTed as a list of above objects,
+    in which case multiple users will be created at once.
 
     #### Status codes
     - 201: returned on success
     - 400: if one of the given roles does not exist, or one of the given fields is invalid
 
-    ### PUT /bot/members/<snowflake:int>
-    Update the member with the given `snowflake`.
+    ### PUT /bot/users/<snowflake:int>
+    Update the user with the given `snowflake`.
     All fields in the request body are required.
 
     #### Request body
@@ -582,16 +727,17 @@ class MemberViewSet(BulkCreateModelMixin, ModelViewSet):
     ...     'avatar': str,
     ...     'name': str,
     ...     'discriminator': int,
-    ...     'roles': List[int]
+    ...     'roles': List[int],
+    ...     'in_guild': bool
     ... }
 
     #### Status codes
     - 200: returned on success
     - 400: if the request body was invalid, see response body for details
-    - 404: if the member with the given `snowflake` could not be found
+    - 404: if the user with the given `snowflake` could not be found
 
-    ### PATCH /bot/members/<snowflake:int>
-    Update the member with the given `snowflake`.
+    ### PATCH /bot/users/<snowflake:int>
+    Update the user with the given `snowflake`.
     All fields in the request body are optional.
 
     #### Request body
@@ -600,21 +746,22 @@ class MemberViewSet(BulkCreateModelMixin, ModelViewSet):
     ...     'avatar': str,
     ...     'name': str,
     ...     'discriminator': int,
-    ...     'roles': List[int]
+    ...     'roles': List[int],
+    ...     'in_guild': bool
     ... }
 
     #### Status codes
     - 200: returned on success
     - 400: if the request body was invalid, see response body for details
-    - 404: if the member with the given `snowflake` could not be found
+    - 404: if the user with the given `snowflake` could not be found
 
-    ### DELETE /bot/members/<snowflake:int>
-    Deletes the member with the given `snowflake`.
+    ### DELETE /bot/users/<snowflake:int>
+    Deletes the user with the given `snowflake`.
 
     #### Status codes
     - 204: returned on success
-    - 404: if a member with the given `snowflake` does not exist
+    - 404: if a user with the given `snowflake` does not exist
     """
 
-    serializer_class = MemberSerializer
-    queryset = Member.objects.all()
+    serializer_class = UserSerializer
+    queryset = User.objects.all()