Convert Service to REST using FastAPI and Make ScanSpecs Pydantic Models

.github/workflows/code.yml

@@ -41,12 +41,12 @@ jobs:
       matrix:
         os: ["ubuntu-latest"] # can add windows-latest, macos-latest
         python: ["3.9", "3.10", "3.11"]
-        install: ["-e .[dev,graphql,plotting]"]
+        install: ["-e .[dev,service,plotting]"]
         # Make one version be non-editable to test both paths of version code
         include:
           - os: "ubuntu-latest"
             python: "3.8"
-            install: ".[dev,graphql,plotting]"
+            install: ".[dev,service,plotting]"
 
     runs-on: ${{ matrix.os }}
     env:

.github/workflows/docs.yml

@@ -28,7 +28,7 @@ jobs:
         uses: ./.github/actions/install_requirements
         with:
           requirements_file: requirements-dev-3.x.txt
-          install_options: -e .[dev,graphql,plotting]
+          install_options: -e .[dev,service,plotting]
 
       - name: Build docs
         run: tox -e docs

.vscode/launch.json

@@ -20,6 +20,25 @@
                 // https://github.com/microsoft/vscode-python/issues/693
                 "PYTEST_ADDOPTS": "--no-cov"
             },
+        },
+        {
+            "name": "Python (Current File)",
+            "type": "python",
+            "request": "launch",
+            "justMyCode": false,
+            "console": "integratedTerminal",
+            "program": "${file}"
+        },
+        {
+            "name": "Scanspec Service",
+            "type": "python",
+            "request": "launch",
+            "justMyCode": false,
+            "console": "integratedTerminal",
+            "module": "scanspec",
+            "args": [
+                "service"
+            ]
         }
     ]
-}
+}

docs/conf.py

@@ -42,10 +42,8 @@
     "sphinx.ext.inheritance_diagram",
     # Adds plotting directives
     "matplotlib.sphinxext.plot_directive",
-    # Graphiql directive
-    "sphinx_graphql.graphiql",
-    # Makes autodoc understand apischema annotated classes/functions
-    "sphinx_apischema",
+    # OpenAPI directive
+    "sphinxcontrib.openapi",
     # Add example_spec directive
     "scanspec.sphinxext",
     # Add a copy button to each code block
@@ -77,6 +75,8 @@
     ("py:class", "'object'"),
     ("py:class", "'id'"),
     ("py:class", "typing_extensions.Literal"),
+    ("py:class", "pydantic.config.BaseConfig"),
+    ("py:class", "starlette.responses.JSONResponse"),
 ]
 
 # Both the class’ and the __init__ method’s docstring are concatenated and

docs/how-to/serialize-a-spec.rst

@@ -11,7 +11,7 @@ Lets start with an example `Spec`.
 This Spec has a `repr` that shows its parameters it was instantiated with:
 
 >>> spec
-Product(outer=Line(axis='y', start=4, stop=5, num=6), inner=Line(axis='x', start=1, stop=2, num=3))
+Product(outer=Line(axis='y', start=4.0, stop=5.0, num=6), inner=Line(axis='x', start=1.0, stop=2.0, num=3))
 
 
 How to Serialize
@@ -20,29 +20,12 @@ How to Serialize
 We can recursively serialize it to a dictionary:
 
 >>> spec.serialize()
-{'Product': {'outer': {'Line': {'axis': 'y', 'start': 4, 'stop': 5, 'num': 6}}, 'inner': {'Line': {'axis': 'x', 'start': 1, 'stop': 2, 'num': 3}}}}
-
+{'outer': {'axis': 'y', 'start': 4.0, 'stop': 5.0, 'num': 6, 'type': 'Line'}, 'inner': {'axis': 'x', 'start': 1.0, 'stop': 2.0, 'num': 3, 'type': 'Line'}, 'type': 'Product'}
 
 How to Deserialize
 ------------------
 
 We can turn this back into a spec using `Spec.deserialize`:
 
->>> Spec.deserialize({'Product': {'outer': {'Line': {'axis': 'y', 'start': 4, 'stop': 5, 'num': 6}}, 'inner': {'Line': {'axis': 'x', 'start': 1, 'stop': 2, 'num': 3}}}})
+>>> Spec.deserialize({'outer': {'axis': 'y', 'start': 4.0, 'stop': 5.0, 'num': 6, 'type': 'Line'}, 'inner': {'axis': 'x', 'start': 1.0, 'stop': 2.0, 'num': 3, 'type': 'Line'}, 'type': 'Product'})
 Product(outer=Line(axis='y', start=4.0, stop=5.0, num=6), inner=Line(axis='x', start=1.0, stop=2.0, num=3))
-
-
-How to send it over GraphQL
----------------------------
-
-Every Spec lists in its documentation a list of parameters and types. The GraphQL
-representation is the dictionary of these parameters, wrapped in a dictionary
-with a single element whose key is the classname. This allows the
-deserialization code to pick the correct class to deserialize to. For example::
-
-    {Line: {axis: "y", start: 4, stop: 5, num: 6}}
-
-You can use `Spec.to_gql_input` to produce this from an existing spec:
-
->>> spec.to_gql_input()
-'{Product: {outer: {Line: {axis: "y", start: 4, stop: 5, num: 6}}, inner: {Line: {axis: "x", start: 1, stop: 2, num: 3}}}}'

docs/reference.rst

@@ -9,6 +9,7 @@ Practical step-by-step guides for the more experienced user.
     :caption: Reference
 
     reference/api
+    reference/rest_api
     reference/contributing
     Releases <https://github.com/dls-controls/scanspec/releases>
     Index <genindex.html#http://>

docs/reference/api.rst

@@ -14,7 +14,7 @@ from code:
 - `scanspec.specs`: `Spec` and its subclasses
 - `scanspec.regions`: `Region` and its subclasses
 - `scanspec.plot`: `plot_spec` to visualize a scan
-- `scanspec.service`: Defines queries and field structure in graphQL such as `PointsResponse`
+- `scanspec.service`: Defines queries and field structure in REST such as `MidpointsResponse`
 
 .. data:: scanspec.__version__
     :type: str
@@ -55,16 +55,6 @@ from code:
 
 .. automodule:: scanspec.service
     :members:
-    :exclude-members: abs_diffs, Points, AxisFrames, PointsResponse
 
     ``scanspec.service``
     --------------------
-
-    .. autoclass:: scanspec.service.Points
-        :members:
-
-    .. autoclass:: scanspec.service.AxisFrames
-        :members:
-
-    .. autoclass:: scanspec.service.PointsResponse
-        :members:

docs/reference/rest_api.rst

@@ -0,0 +1,6 @@
+REST API
+========
+
+The endpoints of the REST service are documented below.
+
+.. openapi:: ../../schema.json

docs/tutorials.rst

@@ -10,4 +10,4 @@ Tutorials for installation, library and commandline usage. New users start here.
 
     tutorials/installation
     tutorials/creating-a-spec
-    tutorials/graphql-service
+    tutorials/rest-service