diff --git a/docs/source/extensions/example_extension/02_adding_views.py b/docs/source/extensions/example_extension/02_adding_views.py index be2bb820..77b49aee 100644 --- a/docs/source/extensions/example_extension/02_adding_views.py +++ b/docs/source/extensions/example_extension/02_adding_views.py @@ -46,7 +46,7 @@ class ExampleIdentifyView(View): class ExampleRenameView(View): # Expect a request parameter called "name", which is a string. # Passed to the argument "args". - args = fields.String(required=True, example="My Example Microscope") + args = fields.String(required=True, metadata={"example": "My Example Microscope"}) def post(self, args): # Look for our new name in the request body diff --git a/docs/source/extensions/example_extension/03_marshaling_data.py b/docs/source/extensions/example_extension/03_marshaling_data.py index 2bf270fe..cca86fd6 100644 --- a/docs/source/extensions/example_extension/03_marshaling_data.py +++ b/docs/source/extensions/example_extension/03_marshaling_data.py @@ -49,7 +49,7 @@ class ExampleRenameView(View): # Format our returned object using MicroscopeIdentifySchema schema = MicroscopeIdentifySchema() # Expect a request parameter called "name", which is a string. Pass to argument "args". - args = {"name": fields.String(required=True, example="My Example Microscope")} + args = {"name": fields.String(required=True, metadata={"example": "My Example Microscope"})} def post(self, args): # Look for our "name" parameter in the request arguments diff --git a/docs/source/extensions/example_extension/04_properties.py b/docs/source/extensions/example_extension/04_properties.py index 6df7069d..7d7a4cc9 100644 --- a/docs/source/extensions/example_extension/04_properties.py +++ b/docs/source/extensions/example_extension/04_properties.py @@ -53,7 +53,7 @@ class ExampleIdentifyView(PropertyView): # We can use a single schema as the input and output will be formatted identically # Eg. We always expect a "name" string argument, and always return a "name" string attribute class ExampleRenameView(PropertyView): - schema = {"name": fields.String(required=True, example="My Example Microscope")} + schema = {"name": fields.String(required=True, metadata={"example": "My Example Microscope"})} def get(self): """ diff --git a/docs/source/extensions/example_extension/05_actions.py b/docs/source/extensions/example_extension/05_actions.py index b260b92c..ca5d6980 100644 --- a/docs/source/extensions/example_extension/05_actions.py +++ b/docs/source/extensions/example_extension/05_actions.py @@ -56,7 +56,7 @@ class ExampleIdentifyView(PropertyView): # We can use a single schema as the input and output will be formatted identically # Eg. We always expect a "name" string argument, and always return a "name" string attribute class ExampleRenameView(PropertyView): - schema = {"name": fields.String(required=True, example="My Example Microscope")} + schema = {"name": fields.String(required=True, metadata={"example": "My Example Microscope"})} def get(self): """ diff --git a/docs/source/extensions/example_extension/06_tasks_locks.py b/docs/source/extensions/example_extension/06_tasks_locks.py index 8412ad65..6c23e8ab 100644 --- a/docs/source/extensions/example_extension/06_tasks_locks.py +++ b/docs/source/extensions/example_extension/06_tasks_locks.py @@ -66,10 +66,10 @@ class TimelapseAPIView(ActionView): args = { "n_images": fields.Integer( - required=True, example=5, description="Number of images" + required=True, metadata={"example": 5, "description": "Number of images"} ), "t_between": fields.Number( - load_default=1, example=1, description="Time (seconds) between images" + load_default=1, metadata={"example": 1, "description": "Time (seconds) between images"} ), } diff --git a/docs/source/extensions/example_extension/07_ev_gui.py b/docs/source/extensions/example_extension/07_ev_gui.py index 0541a533..12b2ce09 100644 --- a/docs/source/extensions/example_extension/07_ev_gui.py +++ b/docs/source/extensions/example_extension/07_ev_gui.py @@ -99,10 +99,10 @@ class TimelapseAPIView(ActionView): args = { "n_images": fields.Integer( - required=True, example=5, description="Number of images" + required=True, metadata={"example": 5, "description": "Number of images"} ), "t_between": fields.Number( - load_default=1, example=1, description="Time (seconds) between images" + load_default=1, metadata={"example": 1, "description": "Time (seconds) between images"} ), } diff --git a/docs/source/extensions/marshaling.rst b/docs/source/extensions/marshaling.rst index 54310486..2ed5e93a 100644 --- a/docs/source/extensions/marshaling.rst +++ b/docs/source/extensions/marshaling.rst @@ -23,7 +23,7 @@ A **field** describes the data type of a single parameter, as well as any other .. code-block:: python - fields.String(required=False, load_default="Default value", example="Example value") + fields.String(required=False, load_default="Default value", metadata={"example: "Example value"}) A **schema** is a collection of keys and fields describing how an object should be serialized/deserialized. Schemas can be created in several ways, either by creating a ``Schema`` class, or by passing a dictionary of key-field pairs. Both methods will be discussed in the following examples. @@ -146,7 +146,7 @@ Our ``rename`` view class may now look like: # Format our returned object using MicroscopeIdentifySchema schema = MicroscopeIdentifySchema() # Expect a request parameter called "name", which is a string. Pass to argument "args". - args = {"name": fields.String(required=True, example="My Example Microscope")} + args = {"name": fields.String(required=True, metadata={"example": "My Example Microscope"})} def post(self, args): # Look for our "name" parameter in the request arguments diff --git a/docs/source/extensions/properties.rst b/docs/source/extensions/properties.rst index 3a86e2d5..fedc5055 100644 --- a/docs/source/extensions/properties.rst +++ b/docs/source/extensions/properties.rst @@ -78,7 +78,7 @@ We will implement the ``schema`` attribute in our ``ExampleRenameView`` view fro # We can use a single schema as the input and output will be formatted identically # Eg. We always expect a "name" string argument, and always return a "name" string attribute class ExampleRenameView(PropertyView): - schema = {"name": fields.String(required=True, example="My Example Microscope")} + schema = {"name": fields.String(required=True, metadata={"example": "My Example Microscope"})} def get(self): """ diff --git a/openflexure_microscope/api/default_extensions/autofocus.py b/openflexure_microscope/api/default_extensions/autofocus.py index c3ad4baf..f7eeb394 100644 --- a/openflexure_microscope/api/default_extensions/autofocus.py +++ b/openflexure_microscope/api/default_extensions/autofocus.py @@ -349,8 +349,10 @@ class AutofocusExtension(BaseExtension): args={ "dz": fields.List( fields.Int(), - metadata={"description": "An ascending list of relative z positions"}, - example=[int(x) for x in np.linspace(-300, 300, 7)], + metadata={ + "description": "An ascending list of relative z positions", + "example": [int(x) for x in np.linspace(-300, 300, 7)], + } ) } ) @@ -433,8 +435,10 @@ class AutofocusExtension(BaseExtension): args={ "dz": fields.Int( load_default=2000, - example=2000, - metadata={"description": "Total Z range to search over (in stage steps)"}, + metadata={ + "description": "Total Z range to search over (in stage steps)", + "example": 2000, + }, ) } ) @@ -529,13 +533,17 @@ class AutofocusExtension(BaseExtension): args={ "dz": fields.Int( load_default=500, - example=500, - metadata={"description": "Total Z range to move down, then up (in stage steps)"}, + metadata={ + "description": "Total Z range to move down, then up (in stage steps)", + "example": 500, + }, ), "delay": fields.Int( load_default=5, - example=5, - metadata={"description": "How long to measure sharpness for after the move"}, + metadata={ + "description": "How long to measure sharpness for after the move", + "example": 5, + }, ), } ) @@ -557,13 +565,17 @@ class AutofocusExtension(BaseExtension): args={ "dz": fields.Int( load_default=2000, - example=2000, - metadata={"description": "Total Z range to search over (in stage steps)"}, + metadata={ + "description": "Total Z range to search over (in stage steps)", + "example": 2000, + }, ), "target_z": fields.Int( load_default=0, - example=-100, - metadata={"description": "Target finishing position, relative to the focus."}, + metadata={ + "description": "Target finishing position, relative to the focus.", + "example": -100, + }, ), "initial_move_up": fields.Bool( load_default=True, @@ -571,8 +583,10 @@ class AutofocusExtension(BaseExtension): ), "backlash": fields.Int( load_default=25, - minimum=0, - metadata={"description": "Distance to undershoot, before correction move."}, + metadata={ + "description": "Distance to undershoot, before correction move.", + "minimum": 0, + }, ), } ) diff --git a/openflexure_microscope/api/default_extensions/autostorage.py b/openflexure_microscope/api/default_extensions/autostorage.py index ab32bf44..aa67875d 100644 --- a/openflexure_microscope/api/default_extensions/autostorage.py +++ b/openflexure_microscope/api/default_extensions/autostorage.py @@ -242,7 +242,7 @@ class GetLocationsView(PropertyView): class PreferredLocationView(PropertyView): - schema = fields.String(required=True, example="Default") + schema = fields.String(required=True, metadata={"example": "Default"}) def get(self): self.extension.check_location() diff --git a/openflexure_microscope/api/default_extensions/camera_stage_mapping.py b/openflexure_microscope/api/default_extensions/camera_stage_mapping.py index 398069c8..53b3789d 100644 --- a/openflexure_microscope/api/default_extensions/camera_stage_mapping.py +++ b/openflexure_microscope/api/default_extensions/camera_stage_mapping.py @@ -279,7 +279,7 @@ class CSMExtension(BaseExtension): class Calibrate1DView(ActionView): - args = {"direction": fields.List(fields.Float(), required=True, example=[1, 0, 0])} + args = {"direction": fields.List(fields.Float(), required=True, metadata={"example": [1, 0, 0]})} def post(self, args): """Calibrate one axis of the microscope stage against the camera.""" @@ -298,10 +298,10 @@ class CalibrateXYView(ActionView): class MoveInImageCoordinatesView(ActionView): args = { "x": fields.Float( - metadata={"description": "The number of pixels to move in X"}, required=True, example=100 + metadata={"description": "The number of pixels to move in X", "example": 100,}, required=True, ), "y": fields.Float( - metadata={"description": "The number of pixels to move in Y"}, required=True, example=100 + metadata={"description": "The number of pixels to move in Y", "example": 100,}, required=True, ), } @@ -316,10 +316,10 @@ class MoveInImageCoordinatesView(ActionView): class ClosedLoopMoveInImageCoordinatesView(ActionView): args = { "x": fields.Float( - metadata={"description": "The number of pixels to move in X"}, required=True, example=100 + metadata={"description": "The number of pixels to move in X", "example": 100,}, required=True, ), "y": fields.Float( - metadata={"description": "The number of pixels to move in Y"}, required=True, example=100 + metadata={"description": "The number of pixels to move in Y", "example": 100,}, required=True, ), } @@ -336,15 +336,14 @@ class ClosedLoopMoveInImageCoordinatesView(ActionView): class TestClosedLoopSpiralScanView(ActionView): args = { "x_step": fields.Float( - metadata={"description": "The number of pixels to move in X"}, required=True, example=100 + metadata={"description": "The number of pixels to move in X", "example": 100,}, required=True, ), "y_step": fields.Float( - metadata={"description": "The number of pixels to move in Y"}, required=True, example=100 + metadata={"description": "The number of pixels to move in Y", "example": 100,}, required=True, ), "N": fields.Int( - metadata={"description": "The number of rings in the spiral scan"}, + metadata={"description": "The number of rings in the spiral scan", "example": 100,}, required=True, - example=3, ), } diff --git a/openflexure_microscope/api/default_extensions/picamera_autocalibrate/extension.py b/openflexure_microscope/api/default_extensions/picamera_autocalibrate/extension.py index 7c2f3cba..642c5a60 100644 --- a/openflexure_microscope/api/default_extensions/picamera_autocalibrate/extension.py +++ b/openflexure_microscope/api/default_extensions/picamera_autocalibrate/extension.py @@ -169,39 +169,49 @@ class DeleteLSTView(ActionView): microscope.save_settings() +percentile_field = fields.Float( + load_default=99.9, + metadata={ + "example": 99.9, + "description": ( + "A float between 0 and 100 setting the centile to use " + "to measure the white point of the image. A value " + "of 99.9 allows 0.1% of the pixels to be erroneously " + "bright - this helps stability in low light." + ), + }, +) + + class AutoExposureFromRawView(ActionView): args = { "target_white_level": fields.Int( load_default=700, - example=700, - description=( - "The pixel value (10-bit format) that we aim for when adjusting shutter/gain." - ), + metadata={ + "example": 700, + "description": ( + "The pixel value (10-bit format) that we aim for when adjusting shutter/gain." + ), + }, ), "max_iterations": fields.Int( - load_default=20, - description=( - "The number of adjustments to the camera's settings to make before giving up." - ), + load_default=20,metadata={ + "description": ( + "The number of adjustments to the camera's settings to make before giving up." + ), + }, ), "tolerance": fields.Float( load_default=0.05, - example=0.05, - description=( - "We stop adjusting when we get within this fraction of the target " - "value. It is a number between 0 and 1, usually 0.01--0.1." - ), - ), - "percentile": fields.Float( - load_default=99.9, - example=99.9, - description=( - "A float between 0 and 100 setting the centile to use " - "to measure the white point of the image. A value " - "of 99.9 allows 0.1% of the pixels to be erroneously " - "bright - this helps stability in low light." - ), + metadata={ + "example": 0.05, + "description": ( + "We stop adjusting when we get within this fraction of the target " + "value. It is a number between 0 and 1, usually 0.01--0.1." + ), + }, ), + "percentile": percentile_field, } def post(self, args): @@ -211,16 +221,7 @@ class AutoExposureFromRawView(ActionView): class AutoWhiteBalanceFromRawView(ActionView): args = { - "percentile": fields.Float( - load_default=99.9, - example=99.9, - description=( - "A float between 0 and 100 setting the centile to use " - "to measure the white point of the image. A value " - "of 99.9 allows 0.1% of the pixels to be erroneously " - "bright - this helps stability in low light." - ), - ) + "percentile": percentile_field, } def post(self, args): @@ -231,8 +232,10 @@ class AutoWhiteBalanceFromRawView(ActionView): class GetRawChannelPercentilesView(ActionView): args = { "percentile": fields.Float( - example=99.9, - metadata={"description": "A float between 0 and 100 setting the centile to calculate"}, + metadata={ + "description": "A float between 0 and 100 setting the centile to calculate", + "example": 99.9, + }, ) } schema = fields.List(fields.Integer) diff --git a/openflexure_microscope/api/default_extensions/scan.py b/openflexure_microscope/api/default_extensions/scan.py index 8f2ff80a..794230ac 100644 --- a/openflexure_microscope/api/default_extensions/scan.py +++ b/openflexure_microscope/api/default_extensions/scan.py @@ -578,17 +578,17 @@ class ScanExtension(BaseExtension): class TileScanArgs(FullCaptureArgs): - namemode = fields.String(load_default="coordinates", example="coordinates") + namemode = fields.String(load_default="coordinates", metadata={"example": "coordinates"}) grid = fields.List( fields.Integer(validate=marshmallow.validate.Range(min=1)), load_default=[3, 3, 3], - example=[3, 3, 3], + metadata={"example": [3, 3, 3]}, ) style = fields.String(load_default="raster") autofocus_dz = fields.Integer(load_default=50) fast_autofocus = fields.Boolean(load_default=False) stride_size = fields.List( - fields.Integer, load_default=[2000, 1500, 100], example=[2000, 1500, 100] + fields.Integer, load_default=[2000, 1500, 100], metadata={"example":[2000, 1500, 100]} ) detect_empty_fields_and_skip_autofocus = fields.Boolean(load_default=False) diff --git a/openflexure_microscope/api/dev_extensions/tools.py b/openflexure_microscope/api/dev_extensions/tools.py index b7959d2b..a19cdc71 100644 --- a/openflexure_microscope/api/dev_extensions/tools.py +++ b/openflexure_microscope/api/dev_extensions/tools.py @@ -24,7 +24,7 @@ class RaiseException(ActionView): class SleepFor(ActionView): schema = {"TimeAsleep": fields.Float()} - args = {"time": fields.Float(metadata={"description": "Time to sleep, in seconds"}, example=0.5)} + args = {"time": fields.Float(metadata={"description": "Time to sleep, in seconds", "example": 0.5})} def post(self, args): sleep_time: int = args.get("time", 0) diff --git a/openflexure_microscope/api/v2/views/actions/camera.py b/openflexure_microscope/api/v2/views/actions/camera.py index 10f1286d..c73cbac1 100644 --- a/openflexure_microscope/api/v2/views/actions/camera.py +++ b/openflexure_microscope/api/v2/views/actions/camera.py @@ -10,8 +10,8 @@ from openflexure_microscope.api.v2.views.captures import CaptureSchema class CaptureResizeSchema(Schema): - width = fields.Integer(example=640, required=True) - height = fields.Integer(example=480, required=True) + width = fields.Integer(metadata={"example":640}, required=True) + height = fields.Integer(metadata={"example": 480}, required=True) class BasicCaptureArgs(Schema): @@ -23,10 +23,10 @@ class BasicCaptureArgs(Schema): class FullCaptureArgs(BasicCaptureArgs): - filename = fields.String(example="MyFileName") + filename = fields.String(metadata={"example": "MyFileName"}) temporary = fields.Boolean(load_default=False, metadata={"description": "Delete capture on shutdown"}) - annotations = fields.Dict(load_default={}, example={"Client": "SwaggerUI"}) - tags = fields.List(fields.String, load_default=[], example=["docs"]) + annotations = fields.Dict(load_default={}, metadata={"example": {"Client": "SwaggerUI"}}) + tags = fields.List(fields.String, load_default=[], metadata={"example": ["docs"]}) class CaptureAPI(ActionView): @@ -113,7 +113,7 @@ class GPUPreviewStartAPI(ActionView): in the format ``[x, y, width, height]``. """ - args = {"window": fields.List(fields.Integer, load_default=[], example=[0, 0, 640, 480])} + args = {"window": fields.List(fields.Integer, load_default=[], metadata={"example": [0, 0, 640, 480]})} def post(self, args): """ diff --git a/openflexure_microscope/api/v2/views/actions/stage.py b/openflexure_microscope/api/v2/views/actions/stage.py index 1488ea2e..d5e79ba1 100644 --- a/openflexure_microscope/api/v2/views/actions/stage.py +++ b/openflexure_microscope/api/v2/views/actions/stage.py @@ -7,11 +7,11 @@ from labthings.views import ActionView class MoveStageAPI(ActionView): args = { "absolute": fields.Boolean( - load_default=False, example=False, metadata={"description": "Move to an absolute position"} + load_default=False, metadata={"description": "Move to an absolute position", "example": False} ), - "x": fields.Int(load_default=None, example=100, allow_none=False), - "y": fields.Int(load_default=None, example=100, allow_none=False), - "z": fields.Int(load_default=None, example=20, allow_none=False), + "x": fields.Int(load_default=None, metadata={"example": 100}, allow_none=False), + "y": fields.Int(load_default=None, metadata={"example": 100}, allow_none=False), + "z": fields.Int(load_default=None, metadata={"example": 20}, allow_none=False), } def post(self, args): diff --git a/openflexure_microscope/api/v2/views/captures.py b/openflexure_microscope/api/v2/views/captures.py index 4935bb46..64fe536b 100644 --- a/openflexure_microscope/api/v2/views/captures.py +++ b/openflexure_microscope/api/v2/views/captures.py @@ -24,7 +24,7 @@ class InstrumentSchema(Schema): class ImageSchema(Schema): id = fields.UUID() - time = fields.String(format="date") + time = fields.String(metadata={"format": "date"}) format = fields.String() name = fields.String() tags = fields.List(fields.String()) diff --git a/openflexure_microscope/api/v2/views/stage.py b/openflexure_microscope/api/v2/views/stage.py index 9db97aed..66bd8f4f 100644 --- a/openflexure_microscope/api/v2/views/stage.py +++ b/openflexure_microscope/api/v2/views/stage.py @@ -8,9 +8,8 @@ class StageTypeProperty(PropertyView): schema = fields.String( load_default=None, - example="SangaStage", validate=validate.OneOf(["SangaStage", "SangaDeltaStage"]), - metadata={"description": "The translation stage geometry"}, + metadata={"description": "The translation stage geometry", "example": "SangaStage",}, allow_none=False, )