Commented component API

server/app/apis/components.py

+"""
+All API calls concerning competitions.
+Default route: /api/competitions/<competition_id>/slides/<slide_id>/components
+"""
+
 import app.core.http_codes as codes
 import app.database.controller as dbc
 from app.apis import item_response, list_response, protect_route
 from app.core.dto import ComponentDTO
-from flask_restx import Resource
-from flask_restx import reqparse
 from app.core.parsers import sentinel
+from flask_restx import Resource, reqparse
 
 api = ComponentDTO.api
 schema = ComponentDTO.schema
@@ -31,16 +35,39 @@ component_parser_edit.add_argument("media_id", type=int, default=sentinel, locat
 component_parser_edit.add_argument("question_id", type=int, default=sentinel, location="json")
 
 
+@api.route("")
+@api.param("competition_id, slide_id")
+class ComponentList(Resource):
+    @protect_route(allowed_roles=["*"], allowed_views=["*"])
+    def get(self, competition_id, slide_id):
+        """ Gets all components in the specified slide and competition. """
+
+        items = dbc.get.component_list(competition_id, slide_id)
+        return list_response(list_schema.dump(items))
+
+    @protect_route(allowed_roles=["*"])
+    def post(self, competition_id, slide_id):
+        """ Posts a new component to the specified slide. """
+
+        args = component_parser_add.parse_args()
+        item = dbc.add.component(slide_id=slide_id, **args)
+        return item_response(schema.dump(item))
+
+
 @api.route("/<component_id>")
 @api.param("competition_id, slide_id, component_id")
 class ComponentByID(Resource):
     @protect_route(allowed_roles=["*"], allowed_views=["*"])
     def get(self, competition_id, slide_id, component_id):
+        """ Gets the specified component. """
+
         item = dbc.get.component(competition_id, slide_id, component_id)
         return item_response(schema.dump(item))
 
     @protect_route(allowed_roles=["*"])
     def put(self, competition_id, slide_id, component_id):
+        """ Edits the specified component with the provided arguments. """
+
         args = component_parser_edit.parse_args(strict=True)
         item = dbc.get.component(competition_id, slide_id, component_id)
         args_without_sentinel = {key: value for key, value in args.items() if value is not sentinel}
@@ -49,6 +76,8 @@ class ComponentByID(Resource):
 
     @protect_route(allowed_roles=["*"])
     def delete(self, competition_id, slide_id, component_id):
+        """ Deletes the specified component. """
+
         item = dbc.get.component(competition_id, slide_id, component_id)
         dbc.delete.component(item)
         return {}, codes.NO_CONTENT
@@ -59,21 +88,12 @@ class ComponentByID(Resource):
 class ComponentList(Resource):
     @protect_route(allowed_roles=["*"])
     def post(self, competition_id, slide_id, component_id, view_type_id):
-        item_component = dbc.get.component(competition_id, slide_id, component_id)
-        item = dbc.copy.component(item_component, slide_id, view_type_id)
-        return item_response(schema.dump(item))
-
-
-@api.route("")
-@api.param("competition_id, slide_id")
-class ComponentList(Resource):
-    @protect_route(allowed_roles=["*"], allowed_views=["*"])
-    def get(self, competition_id, slide_id):
-        items = dbc.get.component_list(competition_id, slide_id)
-        return list_response(list_schema.dump(items))
+        """ Creates a deep copy of the specified component. """
 
-    @protect_route(allowed_roles=["*"])
-    def post(self, competition_id, slide_id):
-        args = component_parser_add.parse_args()
-        item = dbc.add.component(slide_id=slide_id, **args)
+        item_component = dbc.get.component(
+            competition_id,
+            slide_id,
+            component_id,
+        )
+        item = dbc.copy.component(item_component, slide_id, view_type_id)
         return item_response(schema.dump(item))