use dataclasses for options instead of typeddict

Author: rmorshea

docs/app.py

@@ -6,7 +6,7 @@
 
 from idom import component
 from idom.core.types import ComponentConstructor
-from idom.server.sanic import configure, use_request
+from idom.server.sanic import Options, configure, use_request
 
 from .examples import load_examples
 
@@ -26,10 +26,10 @@ def run():
     configure(
         app,
         Example(),
-        {
-            "redirect_root_to_index": False,
-            "url_prefix": IDOM_MODEL_SERVER_URL_PREFIX,
-        },
+        Options(
+            redirect_root=False,
+            url_prefix=IDOM_MODEL_SERVER_URL_PREFIX,
+        ),
     )
 
     app.run(

docs/source/guides/getting-started/running-idom.rst

@@ -99,11 +99,29 @@ Tornado is run using it's own builtin server rather than an external WSGI or ASG
 server.
 
 
-Configuration Options
----------------------
+Server Configuration Options
+----------------------------
 
 IDOM's various server implementations come with ``Options`` that can be passed to their
-respective ``configure()`` functions. Each provides a similar set of key value pairs
+respective ``configure()`` functions. Those which are common amongst the options are:
+
+- ``url_prefix`` - prefix all routes configured by IDOM
+- ``redirect_root`` - whether to redirect the root of the application to the IDOM view
+- ``serve_static_files`` - whether to server IDOM's static files from it's default route
+
+You'd then pass these options to ``configure()`` in the following way:
+
+.. code-block::
+
+    configure(app, MyComponent, Options(...))
+
+To learn more read the description for your chosen server implementation:
+
+- :class:`idom.server.fastapi.Options`
+- :class:`idom.server.flask.Options`
+- :class:`idom.server.sanic.Options`
+- :class:`idom.server.starlette.Options`
+- :class:`idom.server.tornado.Options`
 
 
 Running IDOM in Debug Mode

scripts/live_docs.py

@@ -14,7 +14,7 @@
 )
 
 from docs.app import IDOM_MODEL_SERVER_URL_PREFIX, Example, make_app, reload_examples
-from idom.server.sanic import configure, serve_development_app
+from idom.server.sanic import Options, configure, serve_development_app
 from idom.testing import clear_idom_web_modules_dir
 
 
@@ -33,7 +33,7 @@ def wrap_builder(old_builder):
     configure(
         app,
         Example,
-        {"cors": True, "url_prefix": IDOM_MODEL_SERVER_URL_PREFIX},
+        Options(cors=True, url_prefix=IDOM_MODEL_SERVER_URL_PREFIX),
     )
 
     thread_started = threading.Event()

setup.cfg

@@ -9,6 +9,9 @@ warn_unused_ignores = True
 
 [flake8]
 ignore = E203, E266, E501, W503, F811, N802, N806
+per-file-ignores =
+    # sometimes this is required in order to hide setup for an example
+    docs/*/_examples/*.py:E402
 max-line-length = 88
 max-complexity = 18
 select = B,C,E,F,W,T4,B9,N,ROH

src/idom/server/default.py

@@ -9,8 +9,12 @@
 from .utils import all_implementations
 
 
-def configure(app: Any, component: RootComponentConstructor) -> None:
+def configure(
+    app: Any, component: RootComponentConstructor, options: None = None
+) -> None:
     """Configure the given app instance to display the given component"""
+    if options is not None:  # pragma: no cover
+        raise ValueError("Default implementation cannot be configured with options")
     return _default_implementation().configure(app, component)
 
 

src/idom/server/fastapi.py

@@ -19,6 +19,9 @@
 use_websocket = starlette.use_websocket  # noqa: ROH101
 """Alias for :func:`starlette.use_websocket`"""
 
+Options = starlette.Options
+"""Alias for :class:`starlette.Options`"""
+
 
 def configure(
     app: FastAPI,
@@ -34,9 +37,7 @@ def configure(
     """
     options = starlette._setup_options(options)
     starlette._setup_common_routes(options, app)
-    starlette._setup_single_view_dispatcher_route(
-        options["url_prefix"], app, constructor
-    )
+    starlette._setup_single_view_dispatcher_route(options.url_prefix, app, constructor)
 
 
 def create_development_app() -> FastAPI:

src/idom/server/flask.py

@@ -4,6 +4,7 @@
 import json
 import logging
 from asyncio import Queue as AsyncQueue
+from dataclasses import dataclass
 from queue import Queue as ThreadQueue
 from threading import Event as ThreadEvent
 from threading import Thread
@@ -24,7 +25,6 @@
 from gevent import pywsgi
 from geventwebsocket.handler import WebSocketHandler
 from geventwebsocket.websocket import WebSocket
-from typing_extensions import TypedDict
 
 import idom
 from idom.config import IDOM_WEB_MODULES_DIR
@@ -53,8 +53,8 @@ def configure(
         options: Options for configuring server behavior
         app: An application instance (otherwise a default instance is created)
     """
-    options = _setup_options(options)
-    blueprint = Blueprint("idom", __name__, url_prefix=options["url_prefix"])
+    options = options or Options()
+    blueprint = Blueprint("idom", __name__, url_prefix=options.url_prefix)
     _setup_common_routes(blueprint, options)
     _setup_single_view_dispatcher_route(app, options, component)
     app.register_blueprint(blueprint)
@@ -126,48 +126,33 @@ def use_scope() -> dict[str, Any]:
     return use_request().environ
 
 
-class Options(TypedDict, total=False):
+@dataclass
+class Options:
     """Render server config for :class:`FlaskRenderServer`"""
 
-    cors: Union[bool, Dict[str, Any]]
+    cors: Union[bool, Dict[str, Any]] = False
     """Enable or configure Cross Origin Resource Sharing (CORS)
 
     For more information see docs for ``flask_cors.CORS``
     """
 
-    import_name: str
-    """The module where the application instance was created
-
-    For more info see :class:`flask.Flask`.
-    """
-
-    redirect_root_to_index: bool
+    redirect_root: bool = True
     """Whether to redirect the root URL (with prefix) to ``index.html``"""
 
-    serve_static_files: bool
+    serve_static_files: bool = True
     """Whether or not to serve static files (i.e. web modules)"""
 
-    url_prefix: str
+    url_prefix: str = ""
     """The URL prefix where IDOM resources will be served from"""
 
 
-def _setup_options(options: Options | None) -> Options:
-    return {
-        "url_prefix": "",
-        "cors": False,
-        "serve_static_files": True,
-        "redirect_root_to_index": True,
-        **(options or {}),  # type: ignore
-    }
-
-
 def _setup_common_routes(blueprint: Blueprint, options: Options) -> None:
-    cors_options = options["cors"]
+    cors_options = options.cors
     if cors_options:  # pragma: no cover
         cors_params = cors_options if isinstance(cors_options, dict) else {}
         CORS(blueprint, **cors_params)
 
-    if options["serve_static_files"]:
+    if options.serve_static_files:
 
         @blueprint.route("/client/<path:path>")
         def send_client_dir(path: str) -> Any:
@@ -177,7 +162,7 @@ def send_client_dir(path: str) -> Any:
         def send_modules_dir(path: str) -> Any:
             return send_from_directory(str(IDOM_WEB_MODULES_DIR.current), path)
 
-        if options["redirect_root_to_index"]:
+        if options.redirect_root:
 
             @blueprint.route("/")
             def redirect_to_index() -> Any:
@@ -195,7 +180,7 @@ def _setup_single_view_dispatcher_route(
 ) -> None:
     sockets = Sockets(app)
 
-    @sockets.route(_join_url_paths(options["url_prefix"], "/stream"))  # type: ignore
+    @sockets.route(_join_url_paths(options.url_prefix, "/stream"))  # type: ignore
     def model_stream(ws: WebSocket) -> None:
         def send(value: Any) -> None:
             ws.send(json.dumps(value))

src/idom/server/sanic.py

@@ -3,10 +3,10 @@
 import asyncio
 import json
 import logging
+from dataclasses import dataclass
 from typing import Any, Dict, Tuple, Union
 from uuid import uuid4
 
-from mypy_extensions import TypedDict
 from sanic import Blueprint, Sanic, request, response
 from sanic.config import Config
 from sanic.models.asgi import ASGIScope
@@ -39,10 +39,8 @@ def configure(
     app: Sanic, component: RootComponentConstructor, options: Options | None = None
 ) -> None:
     """Configure an application instance to display the given component"""
-    options = _setup_options(options)
-    blueprint = Blueprint(
-        f"idom_dispatcher_{id(app)}", url_prefix=options["url_prefix"]
-    )
+    options = options or Options()
+    blueprint = Blueprint(f"idom_dispatcher_{id(app)}", url_prefix=options.url_prefix)
     _setup_common_routes(blueprint, options)
     _setup_single_view_dispatcher_route(blueprint, component)
     app.blueprint(blueprint)
@@ -83,46 +81,37 @@ def use_scope() -> ASGIScope:
     return asgi_app.transport.scope
 
 
-class Options(TypedDict, total=False):
+@dataclass
+class Options:
     """Options for :class:`SanicRenderServer`"""
 
-    cors: Union[bool, Dict[str, Any]]
+    cors: Union[bool, Dict[str, Any]] = False
     """Enable or configure Cross Origin Resource Sharing (CORS)
 
     For more information see docs for ``sanic_cors.CORS``
     """
 
-    redirect_root_to_index: bool
+    redirect_root: bool = True
     """Whether to redirect the root URL (with prefix) to ``index.html``"""
 
-    serve_static_files: bool
+    serve_static_files: bool = True
     """Whether or not to serve static files (i.e. web modules)"""
 
-    url_prefix: str
+    url_prefix: str = ""
     """The URL prefix where IDOM resources will be served from"""
 
 
-def _setup_options(options: Options | None) -> Options:
-    return {
-        "cors": False,
-        "url_prefix": "",
-        "serve_static_files": True,
-        "redirect_root_to_index": True,
-        **(options or {}),  # type: ignore
-    }
-
-
 def _setup_common_routes(blueprint: Blueprint, options: Options) -> None:
-    cors_options = options["cors"]
+    cors_options = options.cors
     if cors_options:  # pragma: no cover
         cors_params = cors_options if isinstance(cors_options, dict) else {}
         CORS(blueprint, **cors_params)
 
-    if options["serve_static_files"]:
+    if options.serve_static_files:
         blueprint.static("/client", str(CLIENT_BUILD_DIR))
         blueprint.static("/modules", str(IDOM_WEB_MODULES_DIR.current))
 
-        if options["redirect_root_to_index"]:
+        if options.redirect_root:
 
             @blueprint.route("/")  # type: ignore
             def redirect_to_index(

src/idom/server/starlette.py

@@ -3,9 +3,9 @@
 import asyncio
 import json
 import logging
+from dataclasses import dataclass
 from typing import Any, Dict, Tuple, Union
 
-from mypy_extensions import TypedDict
 from starlette.applications import Starlette
 from starlette.middleware.cors import CORSMiddleware
 from starlette.requests import Request
@@ -50,9 +50,9 @@ def configure(
         constructor: A component constructor
         options: Options for configuring server behavior
     """
-    options = _setup_options(options)
+    options = options or Options()
     _setup_common_routes(options, app)
-    _setup_single_view_dispatcher_route(options["url_prefix"], app, constructor)
+    _setup_single_view_dispatcher_route(options.url_prefix, app, constructor)
 
 
 def create_development_app() -> Starlette:
@@ -85,37 +85,28 @@ def use_scope() -> Scope:
     return use_websocket().scope
 
 
-class Options(TypedDict, total=False):
+@dataclass
+class Options:
     """Optionsuration options for :class:`StarletteRenderServer`"""
 
-    cors: Union[bool, Dict[str, Any]]
+    cors: Union[bool, Dict[str, Any]] = False
     """Enable or configure Cross Origin Resource Sharing (CORS)
 
     For more information see docs for ``starlette.middleware.cors.CORSMiddleware``
     """
 
-    redirect_root_to_index: bool
+    redirect_root: bool = True
     """Whether to redirect the root URL (with prefix) to ``index.html``"""
 
-    serve_static_files: bool
+    serve_static_files: bool = True
     """Whether or not to serve static files (i.e. web modules)"""
 
-    url_prefix: str
+    url_prefix: str = ""
     """The URL prefix where IDOM resources will be served from"""
 
 
-def _setup_options(options: Options | None) -> Options:
-    return {
-        "cors": False,
-        "url_prefix": "",
-        "serve_static_files": True,
-        "redirect_root_to_index": True,
-        **(options or {}),  # type: ignore
-    }
-
-
 def _setup_common_routes(options: Options, app: Starlette) -> None:
-    cors_options = options["cors"]
+    cors_options = options.cors
     if cors_options:  # pragma: no cover
         cors_params = (
             cors_options if isinstance(cors_options, dict) else {"allow_origins": ["*"]}
@@ -124,8 +115,8 @@ def _setup_common_routes(options: Options, app: Starlette) -> None:
 
     # This really should be added to the APIRouter, but there's a bug in Starlette
     # BUG: https://github.com/tiangolo/fastapi/issues/1469
-    url_prefix = options["url_prefix"]
-    if options["serve_static_files"]:
+    url_prefix = options.url_prefix
+    if options.serve_static_files:
         app.mount(
             f"{url_prefix}/client",
             StaticFiles(
@@ -145,7 +136,7 @@ def _setup_common_routes(options: Options, app: Starlette) -> None:
             name="idom_web_module_files",
         )
 
-        if options["redirect_root_to_index"]:
+        if options.redirect_root:
 
             @app.route(f"{url_prefix}/")
             def redirect_to_index(request: Request) -> RedirectResponse: