Merge pull request #117 from labthings/overridable-schemas

More opinionated schema documentation

Author: jtc42

examples/simple_extensions.py

@@ -1,13 +1,17 @@
+from labthings.monkey import patch_all
+
+patch_all()
+
 import random
 import math
+import time
 import logging
 
 from labthings.server.quick import create_app
 from labthings.server.view import ActionView, PropertyView
 from labthings.server.find import find_component
 from labthings.server import fields
 from labthings.core.utilities import path_relative_to
-from labthings.core.tasks import taskify
 
 from labthings.server.extensions import BaseExtension
 
@@ -35,10 +39,7 @@ def post(self, args):
 
         # Get arguments and start a background task
         n_averages = args.get("averages")
-        task = taskify(my_component.average_data)(n_averages)
-
-        # Return the task information
-        return task
+        return my_component.average_data(n_averages)
 
 
 def ext_on_register():
@@ -91,6 +92,18 @@ def data(self):
         """
         return [self.noisy_pdf(x) for x in self.x_range]
 
+    def average_data(self, n: int):
+        """Average n-sets of data. Emulates a measurement that may take a while."""
+        summed_data = self.data
+
+        for _ in range(n):
+            summed_data = [summed_data[i] + el for i, el in enumerate(self.data)]
+            time.sleep(0.25)
+
+        summed_data = [i / n for i in summed_data]
+
+        return summed_data
+
 
 """
 Create a view to view and change our magic_denoise value, and register is as a Thing property

src/labthings/apispec/apispec.py

@@ -4,6 +4,7 @@
 
 from ..utilities import get_docstring, get_summary
 
+from flask.views import http_method_funcs
 from werkzeug.routing import Rule
 from http import HTTPStatus
 
@@ -22,7 +23,7 @@ def rule_to_apispec_path(rule: Rule, view, apispec: APISpec):
 
     params = {
         "path": rule_to_path(rule),
-        "operations": view_to_apispec_operations(view, apispec),
+        "operations": view.get_apispec(),
     }
 
     # Add URL arguments to operations
@@ -32,53 +33,3 @@ def rule_to_apispec_path(rule: Rule, view, apispec: APISpec):
                 params["operations"][op].update({"parameters": rule_to_params(rule)})
 
     return params
-
-
-def view_to_apispec_operations(view, apispec: APISpec):
-    """Generate APISpec `operations` argument from a flask View"""
-
-    # Build dictionary of operations (HTTP methods)
-    ops = {}
-    for op in ("get", "post", "put", "delete"):
-        if hasattr(view, op):
-
-            ops[op] = {
-                "description": getattr(view, "description", None)
-                or get_docstring(view),
-                "summary": getattr(view, "summary", None) or get_summary(view),
-                "tags": list(view.get_tags()),
-            }
-
-            # Add arguments schema
-            if (op in (("post", "put", "delete"))) and hasattr(view, "get_args"):
-                request_schema = convert_to_schema_or_json(view.get_args(), apispec)
-                if request_schema:
-                    ops[op]["requestBody"] = {
-                        "content": {"application/json": {"schema": request_schema}}
-                    }
-
-            # Add response schema
-            if hasattr(view, "get_responses"):
-                ops[op]["responses"] = {}
-
-                for code, response in view.get_responses().items():
-                    ops[op]["responses"][code] = {
-                        "description": response.get("description")
-                        or HTTPStatus(code).phrase,
-                        "content": {
-                            # See if response description specifies a content_type
-                            # If not, assume application/json
-                            response.get("content_type", "application/json"): {
-                                "schema": convert_to_schema_or_json(
-                                    response.get("schema"), apispec
-                                )
-                            }
-                            if response.get("schema")
-                            else {}  # If no schema is defined, don't include one in the APISpec
-                        },
-                    }
-            else:
-                # If no explicit responses are known, populate with defaults
-                ops[op]["responses"] = {200: {HTTPStatus(200).phrase}}
-
-    return ops

src/labthings/apispec/converter.py

@@ -6,9 +6,9 @@ class ExtendedOpenAPIConverter(OpenAPIConverter):
 
     def init_attribute_functions(self, *args, **kwargs):
         OpenAPIConverter.init_attribute_functions(self, *args, **kwargs)
-        self.attribute_functions.append(self.bytes2json)
+        self.attribute_functions.append(self.jsonschema_type_mapping)
 
-    def bytes2json(self, field, **kwargs):
+    def jsonschema_type_mapping(self, field, **kwargs):
         ret = {}
         if hasattr(field, "_jsonschema_type_mapping"):
             schema = field._jsonschema_type_mapping()

src/labthings/default_views/actions.py

@@ -0,0 +1,56 @@
+from flask import abort
+
+from ..view import View
+from ..view.marshalling import marshal_with
+from ..schema import ActionSchema
+from ..find import current_thing
+
+
+class ActionQueue(View):
+    """
+    List of all actions from the session
+    """
+
+    def get(self):
+        return ActionSchema(many=True).dump(current_thing.actions.greenlets)
+
+
+class ActionView(View):
+    """
+    Manage a particular action.
+
+    GET will safely return the current action progress.
+    DELETE will cancel the action, if pending or running.
+    """
+
+    def get(self, task_id):
+        """
+        Show status of a session task
+
+        Includes progress and intermediate data.
+        """
+        task_dict = current_thing.actions.to_dict()
+
+        if task_id not in task_dict:
+            return abort(404)  # 404 Not Found
+
+        task = task_dict.get(task_id)
+
+        return ActionSchema().dump(task)
+
+    def delete(self, task_id):
+        """
+        Terminate a running task.
+
+        If the task is finished, deletes its entry.
+        """
+        task_dict = current_thing.actions.to_dict()
+
+        if task_id not in task_dict:
+            return abort(404)  # 404 Not Found
+
+        task = task_dict.get(task_id)
+
+        task.kill(block=True, timeout=3)
+
+        return ActionSchema().dump(task)

src/labthings/default_views/docs/__init__.py

@@ -1,15 +1,15 @@
 from flask import render_template, Blueprint, make_response
 
 from ...view import View
-from ...find import current_labthing
+from ...find import current_thing
 
 
 class APISpecView(View):
     """OpenAPI v3 documentation"""
 
     def get(self):
         """OpenAPI v3 documentation"""
-        return current_labthing().spec.to_dict()
+        return current_thing.spec.to_dict()
 
 
 class SwaggerUIView(View):

src/labthings/default_views/extensions.py

@@ -7,7 +7,6 @@
 class ExtensionList(View):
     """List and basic documentation for all enabled Extensions"""
 
-    schema = ExtensionSchema(many=True)
     tags = ["extensions"]
 
     def get(self):
@@ -17,4 +16,4 @@ def get(self):
         Returns a list of Extension representations, including basic documentation.
         Describes server methods, web views, and other relevant Lab Things metadata.
         """
-        return registered_extensions().values() or []
+        return ExtensionSchema(many=True).dump(registered_extensions().values() or [])

src/labthings/default_views/root.py

@@ -1,9 +1,9 @@
-from ..find import current_labthing
+from ..find import current_thing
 from ..view import View
 
 
 class RootView(View):
     """W3C Thing Description"""
 
     def get(self):
-        return current_labthing().thing_description.to_dict()
+        return current_thing.thing_description.to_dict()

src/labthings/default_views/sockets.py

@@ -1,5 +1,5 @@
 from ..sockets import SocketSubscriber
-from ..find import current_labthing
+from ..find import current_thing
 
 import gevent
 import logging
@@ -11,7 +11,7 @@
 def socket_handler(ws):
     # Create a socket subscriber
     wssub = SocketSubscriber(ws)
-    current_labthing().subscribers.add(wssub)
+    current_thing.subscribers.add(wssub)
     logging.info(f"Added subscriber {wssub}")
     # Start the socket connection handler loop
     while not ws.closed:
@@ -23,7 +23,7 @@ def socket_handler(ws):
             ws.send(response)
         gevent.sleep(0.1)
     # Remove the subscriber once the loop returns
-    current_labthing().subscribers.remove(wssub)
+    current_thing.subscribers.remove(wssub)
     logging.info(f"Removed subscriber {wssub}")
 
 

src/labthings/default_views/tasks.py

@@ -1,18 +1,24 @@
 from flask import abort
+import logging
 
 from ..view import View
+from ..view.marshalling import marshal_with
 from ..schema import TaskSchema
-
-from .. import tasks
+from ..find import current_thing
 
 
 class TaskList(View):
+    """
+    List of all background tasks from the session
+    """
+
     tags = ["tasks"]
-    schema = TaskSchema(many=True)
 
     def get(self):
-        """List of all session tasks"""
-        return tasks.tasks()
+        logging.warning(
+            "TaskList is deprecated and will be removed in a future version. Use the Actions list instead."
+        )
+        return TaskSchema(many=True).dump(current_thing.actions.greenlets)
 
 
 class TaskView(View):
@@ -24,32 +30,35 @@ class TaskView(View):
     """
 
     tags = ["tasks"]
-    schema = TaskSchema()
-
-    marshal_methods = ("GET", "DELETE")
 
     def get(self, task_id):
         """
         Show status of a session task
 
         Includes progress and intermediate data.
         """
-        task_dict = tasks.to_dict()
+        logging.warning(
+            "TaskView is deprecated and will be removed in a future version. Use the Action view instead."
+        )
+        task_dict = current_thing.actions.to_dict()
 
         if task_id not in task_dict:
             return abort(404)  # 404 Not Found
 
         task = task_dict.get(task_id)
 
-        return task
+        return TaskSchema().dump(task)
 
     def delete(self, task_id):
         """
         Terminate a running task.
 
         If the task is finished, deletes its entry.
         """
-        task_dict = tasks.to_dict()
+        logging.warning(
+            "TaskView is deprecated and will be removed in a future version. Use the Action view instead."
+        )
+        task_dict = current_thing.actions.to_dict()
 
         if task_id not in task_dict:
             return abort(404)  # 404 Not Found
@@ -58,4 +67,4 @@ def delete(self, task_id):
 
         task.kill(block=True, timeout=3)
 
-        return task
+        return TaskSchema().dump(task)

src/labthings/deque.py

@@ -0,0 +1,10 @@
+from collections import deque as _deque
+
+
+class Deque(_deque):
+    def __init__(self, iterable=None, maxlen=100):
+        _deque.__init__(self, iterable or [], maxlen)
+
+
+def resize_deque(iterable: _deque, newsize: int):
+    return deque(iterable, newsize)