Start explicit metadata argument for marshmallow

A side effect of re-locking dependencies is having a newer marshmallow.
This deprecates having `description=` as a keyword, and puts it in a
separate metadata arg instead.

This commit is the start of my search-and-replaceing to update to the new
format.

docs/source/extensions/actions.rst

@@ -18,7 +18,7 @@ Like properties, we use a special view class to identify a view as an action: ``
         Take an image capture and return it without saving
         """
         # Expect a "use_video_port" boolean, which defaults to True if none is given
-        args = {"use_video_port": fields.Boolean(missing=True)}
+        args = {"use_video_port": fields.Boolean(load_default=True)}
 
         # Our success response (200) returns an image (image/jpeg mimetype)
         responses = {

docs/source/extensions/example_extension/05_actions.py

@@ -91,7 +91,7 @@ class QuickCaptureAPI(ActionView):
     """
 
     # Expect a "use_video_port" boolean, which defaults to True if none is given
-    args = {"use_video_port": fields.Boolean(missing=True)}
+    args = {"use_video_port": fields.Boolean(load_default=True)}
 
     # Our success response (200) returns an image (image/jpeg mimetype)
     responses = {200: {"content": {"image/jpeg": {}}}}

docs/source/extensions/example_extension/06_tasks_locks.py

@@ -69,7 +69,7 @@ class TimelapseAPIView(ActionView):
             required=True, example=5, description="Number of images"
         ),
         "t_between": fields.Number(
-            missing=1, example=1, description="Time (seconds) between images"
+            load_default=1, example=1, description="Time (seconds) between images"
         ),
     }
 

docs/source/extensions/example_extension/07_ev_gui.py

@@ -102,7 +102,7 @@ class TimelapseAPIView(ActionView):
             required=True, example=5, description="Number of images"
         ),
         "t_between": fields.Number(
-            missing=1, example=1, description="Time (seconds) between images"
+            load_default=1, example=1, description="Time (seconds) between images"
         ),
     }
 

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, missing="Default value", example="Example value")
+    fields.String(required=False, load_default="Default value", 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.
 
@@ -43,7 +43,7 @@ For example, if you are creating an API route, in which you expect parameters ``
     class UserSchema(Schema):
         name = fields.String(required=True)
         age = fields.Integer(required=True)
-        job = fields.String(required=False, missing="Unknown")
+        job = fields.String(required=False, load_default="Unknown")
 
 To inform your POST method to expect these arguments, use the ``args`` class attribute:
 
@@ -63,7 +63,7 @@ Alternatively, if your schema is only used in a single location, it may be simpl
         args = {
             "name": fields.String(required=True),
             "age": fields.Integer(required=True),
-            "job": fields.String(required=False, missing="Unknown")
+            "job": fields.String(required=False, load_default="Unknown")
         }
 
         def post(self, args):
@@ -88,7 +88,7 @@ This JSON data is the parsed, converted into a Python dictionary, and passed as
         args = {
             "name": fields.String(required=True),
             "age": fields.Integer(required=True),
-            "job": fields.String(required=False, missing="Unknown")
+            "job": fields.String(required=False, load_default="Unknown")
         }
 
         def post(self, args):

openflexure_microscope/api/default_extensions/autofocus.py

@@ -349,7 +349,7 @@ class AutofocusExtension(BaseExtension):
         args={
             "dz": fields.List(
                 fields.Int(),
-                description="An ascending list of relative z positions",
+                metadata={"description": "An ascending list of relative z positions"},
                 example=[int(x) for x in np.linspace(-300, 300, 7)],
             )
         }
@@ -410,7 +410,7 @@ class AutofocusExtension(BaseExtension):
 
     @extension_action(
         args={
-            "dz": fields.Int(required=True, description="The relative Z move to make")
+            "dz": fields.Int(required=True, metadata={"description": "The relative Z move to make"})
         }
     )
     def move_and_measure(
@@ -432,9 +432,9 @@ class AutofocusExtension(BaseExtension):
     @extension_action(
         args={
             "dz": fields.Int(
-                missing=2000,
+                load_default=2000,
                 example=2000,
-                description="Total Z range to search over (in stage steps)",
+                metadata={"description": "Total Z range to search over (in stage steps)"},
             )
         }
     )
@@ -528,14 +528,14 @@ class AutofocusExtension(BaseExtension):
     @extension_action(
         args={
             "dz": fields.Int(
-                missing=500,
+                load_default=500,
                 example=500,
-                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)"},
             ),
             "delay": fields.Int(
-                missing=5,
+                load_default=5,
                 example=5,
-                description="How long to measure sharpness for after the move",
+                metadata={"description": "How long to measure sharpness for after the move"},
             ),
         }
     )
@@ -556,23 +556,23 @@ class AutofocusExtension(BaseExtension):
     @extension_action(
         args={
             "dz": fields.Int(
-                missing=2000,
+                load_default=2000,
                 example=2000,
-                description="Total Z range to search over (in stage steps)",
+                metadata={"description": "Total Z range to search over (in stage steps)"},
             ),
             "target_z": fields.Int(
-                missing=0,
+                load_default=0,
                 example=-100,
-                description="Target finishing position, relative to the focus.",
+                metadata={"description": "Target finishing position, relative to the focus."},
             ),
             "initial_move_up": fields.Bool(
-                missing=True,
-                description="Set to Flase to disable the initial move upwards",
+                load_default=True,
+                metadata={"description": "Set to Flase to disable the initial move upwards"},
             ),
             "backlash": fields.Int(
-                missing=25,
+                load_default=25,
                 minimum=0,
-                description="Distance to undershoot, before correction move.",
+                metadata={"description": "Distance to undershoot, before correction move."},
             ),
         }
     )

openflexure_microscope/api/default_extensions/camera_stage_mapping.py

@@ -298,10 +298,10 @@ class CalibrateXYView(ActionView):
 class MoveInImageCoordinatesView(ActionView):
     args = {
         "x": fields.Float(
-            description="The number of pixels to move in X", required=True, example=100
+            metadata={"description": "The number of pixels to move in X"}, required=True, example=100
         ),
         "y": fields.Float(
-            description="The number of pixels to move in Y", required=True, example=100
+            metadata={"description": "The number of pixels to move in Y"}, required=True, example=100
         ),
     }
 
@@ -316,10 +316,10 @@ class MoveInImageCoordinatesView(ActionView):
 class ClosedLoopMoveInImageCoordinatesView(ActionView):
     args = {
         "x": fields.Float(
-            description="The number of pixels to move in X", required=True, example=100
+            metadata={"description": "The number of pixels to move in X"}, required=True, example=100
         ),
         "y": fields.Float(
-            description="The number of pixels to move in Y", required=True, example=100
+            metadata={"description": "The number of pixels to move in Y"}, required=True, example=100
         ),
     }
 
@@ -336,13 +336,13 @@ class ClosedLoopMoveInImageCoordinatesView(ActionView):
 class TestClosedLoopSpiralScanView(ActionView):
     args = {
         "x_step": fields.Float(
-            description="The number of pixels to move in X", required=True, example=100
+            metadata={"description": "The number of pixels to move in X"}, required=True, example=100
         ),
         "y_step": fields.Float(
-            description="The number of pixels to move in Y", required=True, example=100
+            metadata={"description": "The number of pixels to move in Y"}, required=True, example=100
         ),
         "N": fields.Int(
-            description="The number of rings in the spiral scan",
+            metadata={"description": "The number of rings in the spiral scan"},
             required=True,
             example=3,
         ),

openflexure_microscope/api/default_extensions/picamera_autocalibrate/extension.py

@@ -172,20 +172,20 @@ class DeleteLSTView(ActionView):
 class AutoExposureFromRawView(ActionView):
     args = {
         "target_white_level": fields.Int(
-            missing=700,
+            load_default=700,
             example=700,
             description=(
                 "The pixel value (10-bit format) that we aim for when adjusting shutter/gain."
             ),
         ),
         "max_iterations": fields.Int(
-            missing=20,
+            load_default=20,
             description=(
                 "The number of adjustments to the camera's settings to make before giving up."
             ),
         ),
         "tolerance": fields.Float(
-            missing=0.05,
+            load_default=0.05,
             example=0.05,
             description=(
                 "We stop adjusting when we get within this fraction of the target "
@@ -193,7 +193,7 @@ class AutoExposureFromRawView(ActionView):
             ),
         ),
         "percentile": fields.Float(
-            missing=99.9,
+            load_default=99.9,
             example=99.9,
             description=(
                 "A float between 0 and 100 setting the centile to use "
@@ -212,7 +212,7 @@ class AutoExposureFromRawView(ActionView):
 class AutoWhiteBalanceFromRawView(ActionView):
     args = {
         "percentile": fields.Float(
-            missing=99.9,
+            load_default=99.9,
             example=99.9,
             description=(
                 "A float between 0 and 100 setting the centile to use "
@@ -232,7 +232,7 @@ class GetRawChannelPercentilesView(ActionView):
     args = {
         "percentile": fields.Float(
             example=99.9,
-            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"},
         )
     }
     schema = fields.List(fields.Integer)

openflexure_microscope/api/default_extensions/scan.py

@@ -578,19 +578,19 @@ class ScanExtension(BaseExtension):
 
 
 class TileScanArgs(FullCaptureArgs):
-    namemode = fields.String(missing="coordinates", example="coordinates")
+    namemode = fields.String(load_default="coordinates", example="coordinates")
     grid = fields.List(
         fields.Integer(validate=marshmallow.validate.Range(min=1)),
-        missing=[3, 3, 3],
+        load_default=[3, 3, 3],
         example=[3, 3, 3],
     )
-    style = fields.String(missing="raster")
-    autofocus_dz = fields.Integer(missing=50)
-    fast_autofocus = fields.Boolean(missing=False)
+    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, missing=[2000, 1500, 100], example=[2000, 1500, 100]
+        fields.Integer, load_default=[2000, 1500, 100], example=[2000, 1500, 100]
     )
-    detect_empty_fields_and_skip_autofocus = fields.Boolean(missing=False)
+    detect_empty_fields_and_skip_autofocus = fields.Boolean(load_default=False)
 
 
 class TileScanAPI(ActionView):

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(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)

openflexure_microscope/api/v2/views/actions/camera.py

@@ -15,18 +15,18 @@ class CaptureResizeSchema(Schema):
 
 
 class BasicCaptureArgs(Schema):
-    use_video_port = fields.Boolean(missing=False)
+    use_video_port = fields.Boolean(load_default=False)
     bayer = fields.Boolean(
-        missing=False, description="Include raw bayer data in capture"
+        load_default=False, metadata={"description": "Include raw bayer data in capture"}
     )
     resize = fields.Nested(CaptureResizeSchema(), required=False)
 
 
 class FullCaptureArgs(BasicCaptureArgs):
     filename = fields.String(example="MyFileName")
-    temporary = fields.Boolean(missing=False, description="Delete capture on shutdown")
-    annotations = fields.Dict(missing={}, example={"Client": "SwaggerUI"})
-    tags = fields.List(fields.String, missing=[], example=["docs"])
+    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"])
 
 
 class CaptureAPI(ActionView):
@@ -113,7 +113,7 @@ class GPUPreviewStartAPI(ActionView):
     in the format ``[x, y, width, height]``.
     """
 
-    args = {"window": fields.List(fields.Integer, missing=[], example=[0, 0, 640, 480])}
+    args = {"window": fields.List(fields.Integer, load_default=[], example=[0, 0, 640, 480])}
 
     def post(self, args):
         """

openflexure_microscope/api/v2/views/actions/stage.py

@@ -7,11 +7,11 @@ from labthings.views import ActionView
 class MoveStageAPI(ActionView):
     args = {
         "absolute": fields.Boolean(
-            missing=False, example=False, description="Move to an absolute position"
+            load_default=False, example=False, metadata={"description": "Move to an absolute position"}
         ),
-        "x": fields.Int(missing=None, example=100, allow_none=False),
-        "y": fields.Int(missing=None, example=100, allow_none=False),
-        "z": fields.Int(missing=None, example=20, allow_none=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),
     }
 
     def post(self, args):

openflexure_microscope/api/v2/views/captures.py

@@ -59,7 +59,7 @@ class CaptureSchema(ImageSchema):
     # without the server having to do a tonne of file IO
     dataset = fields.Nested(BasicDatasetSchema())
     file = fields.String(
-        data_key="path", description="Path of file on microscope device"
+        data_key="path", metadata={"description": "Path of file on microscope device"}
     )
     # No need to make a schema for links as we only ever
     # create the dictionary right here in `generate_links`

openflexure_microscope/api/v2/views/stage.py

@@ -7,10 +7,10 @@ class StageTypeProperty(PropertyView):
     """The type of the stage"""
 
     schema = fields.String(
-        missing=None,
+        load_default=None,
         example="SangaStage",
         validate=validate.OneOf(["SangaStage", "SangaDeltaStage"]),
-        description="The translation stage geometry",
+        metadata={"description": "The translation stage geometry"},
         allow_none=False,
     )