Switched to ActionView and PropertyView from decorators (1819ca6a) · Commits · OpenFlexure / openflexure-microscope-server

docs/source/extensions/actions.rst

+2 −5

Original line number	Diff line number	Diff line
		@@ -9,12 +9,11 @@ Thing Actions "invoke a function of the Thing, which manipulates state (e.g., to

		Actions should be triggered with POST requests only. Ideally, a view corresponding to an action should only support POST requests.

		Like properties, we use a class decorator to identify a view as an action: ``@ThingAction``. For example, a view to perform a "quick-capture" action may look like:
		Like properties, we use a special view class to identify a view as an action: ``ActionView``. For example, a view to perform a "quick-capture" action may look like:

		.. code-block:: python

		@ThingAction
		class QuickCaptureAPI(View):
		class QuickCaptureAPI(ActionView):
		"""
		Take an image capture and return it without saving
		"""
		@@ -44,8 +43,6 @@ Like properties, we use a class decorator to identify a view as an action: ``@Th

		In this example, we are also making use of the ``@doc_response`` decorator, to document that our successful response (HTTP code 200) will return data with a mimetype ``image/jpeg``, as well as ``@use_args`` to accept optional parameters with POST requests.

		Again like properties, the ``@ThingAction`` decorator serves only to add documentation.

		Complete example
		----------------

+3 −5

Original line number	Diff line number	Diff line
		from labthings.server.extensions import BaseExtension
		from labthings.server.find import find_component
		from labthings.server.view import View
		from labthings.server.view import View, PropertyView

		from labthings.server.decorators import (
		use_args,
		@@ -36,8 +36,7 @@ def rename(microscope, new_name):
		## Extension views

		# Since we only have a GET method here, it'll register as a read-only property
		@ThingProperty
		class ExampleIdentifyView(View):
		class ExampleIdentifyView(PropertyView):
		# Format our returned object using MicroscopeIdentifySchema
		@marshal_with(MicroscopeIdentifySchema())
		def get(self):
		@@ -52,11 +51,10 @@ class ExampleIdentifyView(View):
		return microscope


		@ThingProperty
		# We can use a single schema for all methods if the input and output will be formatted identically
		# Eg. Here, we will always expect a "name" string argument, and always return a "name" string attribute
		@PropertySchema({"name": fields.String(required=True, example="My Example Microscope")})
		class ExampleRenameView(View):
		class ExampleRenameView(PropertyView):
		def get(self):
		"""
		Show the current microscope name

+4 −7

Original line number	Diff line number	Diff line
		from labthings.server.extensions import BaseExtension
		from labthings.server.find import find_component
		from labthings.server.view import View
		from labthings.server.view import View, ActionView, PropertyView

		from labthings.server.decorators import (
		use_args,
		@@ -41,8 +41,7 @@ def rename(microscope, new_name):
		## Extension views

		# Since we only have a GET method here, it'll register as a read-only property
		@ThingProperty
		class ExampleIdentifyView(View):
		class ExampleIdentifyView(PropertyView):
		# Format our returned object using MicroscopeIdentifySchema
		@marshal_with(MicroscopeIdentifySchema())
		def get(self):
		@@ -57,11 +56,10 @@ class ExampleIdentifyView(View):
		return microscope


		@ThingProperty
		# We can use a single schema for all methods if the input and output will be formatted identically
		# Eg. Here, we will always expect a "name" string argument, and always return a "name" string attribute
		@PropertySchema({"name": fields.String(required=True, example="My Example Microscope")})
		class ExampleRenameView(View):
		class ExampleRenameView(PropertyView):
		def get(self):
		"""
		Show the current microscope name
		@@ -89,8 +87,7 @@ class ExampleRenameView(View):
		return microscope


		@ThingAction
		class QuickCaptureAPI(View):
		class QuickCaptureAPI(ActionView):
		"""
		Take an image capture and return it without saving
		"""

+2 −3

Original line number	Diff line number	Diff line
		from labthings.server.extensions import BaseExtension
		from labthings.server.find import find_component
		from labthings.server.view import View
		from labthings.server.view import View, ActionView

		from labthings.server.decorators import (
		use_args,
		@@ -66,8 +66,7 @@ def timelapse(microscope, n_images, t_between):
		## Extension views


		@ThingAction
		class TimelapseAPI(View):
		class TimelapseAPI(ActionView):
		"""
		Take a series of images in a timelapse
		"""

+2 −3

Original line number	Diff line number	Diff line
		from labthings.server.extensions import BaseExtension
		from labthings.server.find import find_component
		from labthings.server.view import View
		from labthings.server.view import View, ActionView

		from labthings.server.decorators import (
		use_args,
		@@ -68,8 +68,7 @@ def timelapse(microscope, n_images, t_between):
		## Extension views


		@ThingAction
		class TimelapseAPI(View):
		class TimelapseAPI(ActionView):
		"""
		Take a series of images in a timelapse, running as a background task
		"""