Mozilla Web Things format and structure (#81)

* Converted TD to Mozilla schema

* Move websocket route to /ws

* Half-working newer socket implementation

* Enabled url_for for WebSocket views

* Updated websocket link rel

* Removed debug string

* Improved link between extension view endpoints and TD keys

* Add explicit endpoint to test

* Simplified action and property tagging

* Implemented ActionView for automatic background task management

* Fixed represent_response

* Build using view classes rather than decorators

* Update tests

* Reduced mock Action time

* Fixed Action href

* Removed old debug statement

* FieldSchema subclasses Schema

* Added output schema to action

* Simplified example

* Let schema handle datetime formatting

* Improved get_spec

* Simplified APISpec path builder

* Renamed view_to_apispec_operations

* Fixed operation parameters

* Updated apispec tests

* Removed old unused SocketMiddleware

* Fixed summary builder

* Automatically build 201 Action schemas

* Fixed error in exception

* Removed unused Task argument

* Add output and status properties

* Include "input" in Action schemas

* Send input schema into Action schema generator

* Marshal Action responses with the correct schema

* Compile generated View specs as they're created

* Update view builder tests

* Fixed generated action class name

* Remove tasks from properties

* Fixed generated name

* Improved coverage

Author: jtc42

examples/builder.py

@@ -44,7 +44,6 @@
     my_component.average_data,
     "/average",
     description="Take an averaged measurement",
-    task=True,  # Is the action a long-running task?
     safe=True,  # Is the state of the Thing unchanged by calling the action?
     idempotent=True,  # Can the action be called repeatedly with the same result?
 )

examples/simple_extensions.py

@@ -3,11 +3,19 @@
 import logging
 
 from labthings.server.quick import create_app
-from labthings.server.decorators import ThingProperty, PropertySchema
+from labthings.server.decorators import (
+    ThingProperty,
+    PropertySchema,
+    ThingAction,
+    use_args,
+    marshal_task,
+    doc,
+)
 from labthings.server.view import View
 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
 
@@ -20,6 +28,37 @@
 """
 
 
+@ThingAction
+class ExtensionMeasurementAction(View):
+    # Expect JSON parameters in the request body.
+    # Pass to post function as dictionary argument.
+    @use_args(
+        {
+            "averages": fields.Integer(
+                missing=10,
+                example=10,
+                description="Number of data sets to average over",
+            )
+        }
+    )
+    # Shorthand to say we're always going to return a Task object
+    @marshal_task
+    @doc(title="Averaged Measurement")
+    # Main function to handle POST requests
+    def post(self, args):
+        """Start an averaged measurement"""
+
+        # Find our attached component
+        my_component = find_component("org.labthings.example.mycomponent")
+
+        # 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
+
+
 def ext_on_register():
     logging.info("Extension registered")
 
@@ -34,6 +73,8 @@ def ext_on_my_component(component):
     "org.labthings.examples.extension", static_folder=static_folder
 )
 
+example_extension.add_view(ExtensionMeasurementAction, "/measure", endpoint="measure")
+
 example_extension.on_register(ext_on_register)
 example_extension.on_component("org.labthings.example.mycomponent", ext_on_my_component)
 

examples/simple_thing.py

@@ -14,13 +14,11 @@
 
 from labthings.server.quick import create_app
 from labthings.server.decorators import (
-    ThingAction,
-    ThingProperty,
     PropertySchema,
     use_args,
-    marshal_task,
+    marshal_with,
 )
-from labthings.server.view import View
+from labthings.server.view import View, ActionView, PropertyView
 from labthings.server.find import find_component
 from labthings.server import fields
 from labthings.core.tasks import taskify, update_task_data
@@ -36,9 +34,6 @@
 
 get_ident = get_original("_thread", "get_ident")
 
-print(f"ROOT IDENT")
-print(get_ident())
-
 
 class MyComponent:
     def __init__(self):
@@ -69,8 +64,7 @@ def average_data(self, n: int):
         logging.warning("Starting an averaged measurement. This may take a while...")
         for _ in range(n):
             summed_data = [summed_data[i] + el for i, el in enumerate(self.data)]
-            update_task_data({"data": summed_data})
-            time.sleep(0.25)
+            time.sleep(0.1)
 
         summed_data = [i / n for i in summed_data]
 
@@ -83,8 +77,6 @@ def average_data(self, n: int):
 """
 
 
-# Register this view as a Thing Property
-@ThingProperty
 # Define the data we're going to output (get), and what to expect in (post)
 @PropertySchema(
     fields.Integer(
@@ -95,7 +87,7 @@ def average_data(self, n: int):
         description="Value of magic_denoise",
     )
 )
-class DenoiseProperty(View):
+class DenoiseProperty(PropertyView):
 
     # Main function to handle GET requests (read)
     def get(self):
@@ -123,9 +115,8 @@ def post(self, new_property_value):
 """
 
 
-@ThingProperty
 @PropertySchema(fields.List(fields.Float()))
-class QuickDataProperty(View):
+class QuickDataProperty(PropertyView):
     # Main function to handle GET requests
     def get(self):
         """Show the current data value"""
@@ -140,21 +131,20 @@ def get(self):
 """
 
 
-@ThingAction
-class MeasurementAction(View):
+class MeasurementAction(ActionView):
     # Expect JSON parameters in the request body.
     # Pass to post function as dictionary argument.
     @use_args(
         {
             "averages": fields.Integer(
-                missing=10,
-                example=10,
+                missing=20,
+                example=20,
                 description="Number of data sets to average over",
             )
         }
     )
-    # Shorthand to say we're always going to return a Task object
-    @marshal_task
+    # Output schema
+    @marshal_with(fields.List(fields.Number))
     # Main function to handle POST requests
     def post(self, args):
         """Start an averaged measurement"""
@@ -164,10 +154,9 @@ 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)
 
 
 # Handle exit cleanup

src/labthings/core/tasks/thread.py

@@ -44,8 +44,9 @@ def __init__(self, target, *args, **kwargs):
             logging.debug("No request context to copy")
 
         # Private state properties
-        self._status: str = "idle"  # Task status
+        self._status: str = "pending"  # Task status
         self._return_value = None  # Return value
+        self._request_time = datetime.datetime.now()
         self._start_time = None  # Task start time
         self._end_time = None  # Task end time
 
@@ -65,17 +66,12 @@ def ident(self):
         return get_ident(self)
 
     @property
-    def state(self):
-        return {
-            "function": self.target_string,
-            "id": self._ID,
-            "status": self._status,
-            "progress": self.progress,
-            "data": self.data,
-            "return": self._return_value,
-            "start_time": self._start_time,
-            "end_time": self._end_time,
-        }
+    def output(self):
+        return self._return_value
+
+    @property
+    def status(self):
+        return self._status
 
     def update_progress(self, progress: int):
         # Update progress of the task
@@ -102,7 +98,7 @@ def wrapped(*args, **kwargs):
             logging.getLogger().addHandler(handler)
 
             self._status = "running"
-            self._start_time = datetime.datetime.now().strftime("%Y-%m-%d %H-%M-%S")
+            self._start_time = datetime.datetime.now()
             self.started_event.set()
             try:
                 self._return_value = f(*args, **kwargs)
@@ -117,8 +113,9 @@ def wrapped(*args, **kwargs):
                 logging.error(traceback.format_exc())
                 self._return_value = str(e)
                 self._status = "error"
+                raise e
             finally:
-                self._end_time = datetime.datetime.now().strftime("%Y-%m-%d %H-%M-%S")
+                self._end_time = datetime.datetime.now()
                 logging.getLogger().removeHandler(handler)  # Stop logging this thread
                 # If we don't remove the handler, it's a memory leak.
 

src/labthings/server/decorators.py

@@ -11,7 +11,7 @@
 from .spec.utilities import update_spec, tag_spec
 from .schema import TaskSchema, Schema, FieldSchema
 from .fields import Field
-from .view import View
+from .view import View, ActionView, PropertyView
 from .find import current_labthing
 from .utilities import unpack
 from .event import PropertyStatusEvent, ActionStatusEvent
@@ -59,10 +59,13 @@ def __init__(self, schema, code=200):
         self.schema = schema
         self.code = code
 
+        # Case of schema as a dictionary
         if isinstance(self.schema, Mapping):
             self.converter = Schema.from_dict(self.schema)().dump
+        # Case of schema as a single Field
         elif isinstance(self.schema, Field):
             self.converter = FieldSchema(self.schema).dump
+        # Case of schema as a Schema
         elif isinstance(self.schema, _Schema):
             self.converter = self.schema.dump
         else:
@@ -83,33 +86,30 @@ def wrapper(*args, **kwargs):
             elif isinstance(resp, tuple):
                 resp, code, headers = unpack(resp)
                 return (self.converter(resp), code, headers)
-            else:
-                resp, code, headers = resp, 200, {}
-            return (self.converter(resp), code, headers)
+            return self.converter(resp)
 
         return wrapper
 
 
 def marshal_task(f):
     """Decorator to format the response of a View with the standard Task schema"""
 
+    logging.warning(
+        "marshal_task is deprecated. Please use @ThingAction or the ActionView class"
+    )
+
     # Pass params to call function attribute for external access
     update_spec(f, {"responses": {201: {"description": "Task started successfully"}}})
     update_spec(f, {"_schema": {201: TaskSchema()}})
     # Wrapper function
     @wraps(f)
     def wrapper(*args, **kwargs):
         resp = f(*args, **kwargs)
-        if isinstance(resp, tuple):
-            resp, code, headers = unpack(resp)
-        else:
-            resp, code, headers = resp, 201, {}
-
         if not isinstance(resp, TaskThread):
             raise TypeError(
                 f"Function {f.__name__} expected to return a TaskThread object, but instead returned a {type(resp).__name__}. If it does not return a task, remove the @marshall_task decorator from {f.__name__}."
             )
-        return (TaskSchema().dump(resp), code, headers)
+        return TaskSchema().dump(resp)
 
     return wrapper
 
@@ -123,7 +123,8 @@ def ThingAction(viewcls: View):
     Returns:
         View: View class with Action spec tags
     """
-    # TODO: Handle actionStatus messages
+    # Set to PropertyView.dispatch_request
+    viewcls.dispatch_request = ActionView.dispatch_request
     # Update Views API spec
     tag_spec(viewcls, "actions")
     return viewcls
@@ -175,37 +176,8 @@ def ThingProperty(viewcls):
     Returns:
         View: View class with Property spec tags
     """
-
-    def property_notify(func):
-        @wraps(func)
-        def wrapped(*args, **kwargs):
-            # Call the update function first to update property value
-            original_response = func(*args, **kwargs)
-
-            if hasattr(viewcls, "get_value") and callable(viewcls.get_value):
-                property_value = viewcls().get_value()
-            else:
-                property_value = None
-
-            property_name = getattr(viewcls, "endpoint", None) or getattr(
-                viewcls, "__name__", "unknown"
-            )
-
-            if current_labthing():
-                current_labthing().message(
-                    PropertyStatusEvent(property_name), property_value,
-                )
-
-            return original_response
-
-        return wrapped
-
-    if hasattr(viewcls, "post") and callable(viewcls.post):
-        viewcls.post = property_notify(viewcls.post)
-
-    if hasattr(viewcls, "put") and callable(viewcls.put):
-        viewcls.put = property_notify(viewcls.put)
-
+    # Set to PropertyView.dispatch_request
+    viewcls.dispatch_request = PropertyView.dispatch_request
     # Update Views API spec
     tag_spec(viewcls, "properties")
     return viewcls

src/labthings/server/default_views/tasks.py

@@ -15,7 +15,7 @@ def get(self):
         return tasks.tasks()
 
 
-@Tag(["properties", "tasks"])
+@Tag(["tasks"])
 class TaskView(View):
     """
     Manage a particular background task.