Rework How IDOM Integrates With Servers (#703)

* initial work to move away from run func

* initial work converting to new server interface

* finish up flask conversion

* convert tornado + begin reworking test utils

* remove shared dispatchers and rename to serve module

* misc fixes

* start to switch test suite to playwright

* get basic tests working

* get some tests working

* slight optimization

* misc minor improvements

* fix test_html

* implement test_module

* implement connection context

* fix playwright install in nox

* add minimal docstrings

* remove pytest-playwright

* get suite to run (with failures)

* fix log assertion problems

* misc fixes in order to get reconnect test to work

* expose use_scope instead of use_connection

* fix test common

* fix test_client

* test use_scope

* remove unused imports

* fix live docs

* fix typing issues

* fix rest of tests

* improve coverage

* import protocol from typing extensions

* fix syntax error

* fix docs test

* fix flake8

* test run function

* use selector event loop

* try to fix loop

* only install chromium

* remove unused import

* fix shutdown code

* skip browser tests on windows

* fix coverage + reorg testing utils

* minor logging changes

* fix live docs script

* fix log message

* fix types

* documentation updates

* use dataclasses for options instead of typeddict

* move section

* add note to changelog

* fix missing refs

* fix ref

* fix fastapi alias

* fix tornado redirect

* remove unused imports

* changelog entry

* fix noxfile tag commit msg

* improve changelog entry

* fix typo in old cl entry

Author: rmorshea

.github/workflows/test.yml

@@ -15,7 +15,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - uses: nanasess/setup-chromedriver@master
       - uses: actions/setup-node@v2
         with:
           node-version: "14.x"
@@ -29,7 +28,7 @@ jobs:
         run: pip install -r requirements/nox-deps.txt
       - name: Run Tests
         env: { "CI": "true" }
-        run: nox -s test_python_suite -- --headless --maxfail=3
+        run: nox -s test_python_suite -- --maxfail=3
   test-python-environments:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -38,7 +37,6 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
     steps:
       - uses: actions/checkout@v2
-      - uses: nanasess/setup-chromedriver@master
       - uses: actions/setup-node@v2
         with:
           node-version: "14.x"
@@ -52,7 +50,7 @@ jobs:
         run: pip install -r requirements/nox-deps.txt
       - name: Run Tests
         env: { "CI": "true" }
-        run: nox -s test_python --stop-on-first-error -- --headless --maxfail=3 --no-cov
+        run: nox -s test_python --stop-on-first-error -- --maxfail=3 --no-cov
   test-docs:
     runs-on: ubuntu-latest
     steps:

docs/app.py

@@ -4,8 +4,9 @@
 
 from sanic import Sanic, response
 
-from idom.server.sanic import PerClientStateServer
-from idom.widgets import multiview
+from idom import component
+from idom.core.types import ComponentConstructor
+from idom.server.sanic import Options, configure, use_request
 
 from .examples import load_examples
 
@@ -22,13 +23,13 @@
 def run():
     app = make_app()
 
-    PerClientStateServer(
-        make_examples_component(),
-        {
-            "redirect_root_to_index": False,
-            "url_prefix": IDOM_MODEL_SERVER_URL_PREFIX,
-        },
+    configure(
         app,
+        Example(),
+        Options(
+            redirect_root=False,
+            url_prefix=IDOM_MODEL_SERVER_URL_PREFIX,
+        ),
     )
 
     app.run(
@@ -39,8 +40,28 @@ def run():
     )
 
 
+@component
+def Example():
+    view_id = use_request().get_args().get("view_id")
+    return _get_examples()[view_id]()
+
+
+def _get_examples():
+    if not _EXAMPLES:
+        _EXAMPLES.update(load_examples())
+    return _EXAMPLES
+
+
+def reload_examples():
+    _EXAMPLES.clear()
+    _EXAMPLES.update(load_examples())
+
+
+_EXAMPLES: dict[str, ComponentConstructor] = {}
+
+
 def make_app():
-    app = Sanic(__name__)
+    app = Sanic("docs_app")
 
     app.static("/docs", str(HERE / "build"))
 
@@ -49,12 +70,3 @@ async def forward_to_index(request):
         return response.redirect("/docs/index.html")
 
     return app
-
-
-def make_examples_component():
-    mount, component = multiview()
-
-    for example_name, example_component in load_examples():
-        mount.add(example_name, example_component)
-
-    return component

docs/examples.py

@@ -23,7 +23,7 @@ def load_examples() -> Iterator[tuple[str, Callable[[], ComponentType]]]:
 def all_example_names() -> set[str]:
     names = set()
     for file in _iter_example_files(SOURCE_DIR):
-        path = file.parent if file.name == "app.py" else file
+        path = file.parent if file.name == "main.py" else file
         names.add("/".join(path.relative_to(SOURCE_DIR).with_suffix("").parts))
     return names
 
@@ -48,7 +48,7 @@ def get_main_example_file_by_name(
 ) -> Path:
     path = _get_root_example_path_by_name(name, relative_to)
     if path.is_dir():
-        return path / "app.py"
+        return path / "main.py"
     else:
         return path.with_suffix(".py")
 

docs/source/_exts/idom_example.py

@@ -51,7 +51,7 @@ def run(self):
         if len(ex_files) == 1:
             labeled_tab_items.append(
                 (
-                    "app.py",
+                    "main.py",
                     _literal_include(
                         path=ex_files[0],
                         linenos=show_linenos,

docs/source/about/changelog.rst

@@ -11,13 +11,41 @@ Changelog
 All notable changes to this project will be recorded in this document. The style of
 which is based on `Keep a Changelog <https://keepachangelog.com/>`__. The versioning
 scheme for the project adheres to `Semantic Versioning <https://semver.org/>`__. For
-more info, see the :ref:`Contributor Guide <Create a Changelog Entry>`.
+more info, see the :ref:`Contributor Guide <Creating a Changelog Entry>`.
 
 
+.. INSTRUCTIONS FOR CHANGELOG CONTRIBUTORS
+.. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+.. If you're adding a changelog entry, be sure to read the "Creating a Changelog Entry"
+.. section of the documentation before doing so for instructions on how to adhere to the
+.. "Keep a Changelog" style guide (https://keepachangelog.com).
+
 Unreleased
 ----------
 
-Nothing yet...
+Changed:
+
+- How IDOM integrates with servers - :pull:`703`
+
+  - ``idom.run`` no longer accepts an app instance to discourage use outside of testing
+  - IDOM's server implementations now provide ``configure()`` functions instead
+  - ``idom.testing`` has been completely reworked in order to support async web drivers
+
+Added:
+
+- Access to underlying server requests via contexts - :issue:`669`
+
+Removed:
+
+- ``idom.widgets.multiview`` since basic routing view ``use_scope`` is now possible
+- All ``SharedClientStateServer`` implementations.
+- All ``PerClientStateServer`` implementations have been replaced with ``configure()``
+
+Fixed:
+
+- IDOM's test suite no longer uses sync web drivers - :issue:`591`
+- Updated Sanic requirement to ``>=21`` - :issue:`678`
+- How we advertise ``idom.run`` - :issue:`657`
 
 
 0.37.2
@@ -30,7 +58,8 @@ Changed:
 
 Fixed:
 
-- A typo caused IDOM to use the insecure `ws` web-socket protocol on pages loaded with `https` instead of the secure `wss` protocol - :pull:`716`
+- A typo caused IDOM to use the insecure ``ws`` web-socket protocol on pages loaded with
+  ``https`` instead of the secure ``wss`` protocol - :pull:`716`
 
 
 0.37.1

docs/source/about/contributor-guide.rst

@@ -66,8 +66,8 @@ about how to get started. To make a change to IDOM you'll do the following:
     :ref:`equality checks <Code Quality Checks>` and, with any luck, accept your request.
     At that point your contribution will be merged into the main codebase!
 
-Create a Changelog Entry
-........................
+Creating a Changelog Entry
+..........................
 
 As part of your pull request, you'll want to edit the `Changelog
 <https://github.com/idom-team/idom/blob/main/docs/source/about/changelog.rst>`__ by

docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/app.py renamed to docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/main.py

@@ -151,7 +151,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Initial render</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 2
 
@@ -165,7 +165,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Initial state declaration</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 3
 
@@ -181,7 +181,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Define event handler</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 5
 
@@ -196,7 +196,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Return the view</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 16
 
@@ -212,7 +212,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>User interaction</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 5
 
@@ -226,7 +226,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>New state is set</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 6
 
@@ -242,7 +242,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Next render begins</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 2
 
@@ -256,7 +256,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Next state is acquired</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 3
 
@@ -272,7 +272,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Repeat...</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
 
         From this point on, the steps remain the same. The only difference being the

docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/app.py renamed to docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/main.py

@@ -3,7 +3,7 @@
 
 @component
 def App():
-    return html.h1("Hello, World!")
+    return html.h1("Hello, world!")
 
 
 run(App)

docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/app.py renamed to docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/main.py

@@ -0,0 +1,23 @@
+# :lines: 11-
+
+from idom import run
+from idom.server import fastapi as fastapi_server
+
+
+# the run() function is the entry point for examples
+fastapi_server.configure = lambda _, cmpt: run(cmpt)
+
+
+from fastapi import FastAPI
+
+from idom import component, html
+from idom.server.fastapi import configure
+
+
+@component
+def HelloWorld():
+    return html.h1("Hello, world!")
+
+
+app = FastAPI()
+configure(app, HelloWorld)

docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/app.py renamed to docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/main.py

@@ -0,0 +1,23 @@
+# :lines: 11-
+
+from idom import run
+from idom.server import flask as flask_server
+
+
+# the run() function is the entry point for examples
+flask_server.configure = lambda _, cmpt: run(cmpt)
+
+
+from flask import Flask
+
+from idom import component, html
+from idom.server.flask import configure
+
+
+@component
+def HelloWorld():
+    return html.h1("Hello, world!")
+
+
+app = Flask(__name__)
+configure(app, HelloWorld)

docs/source/guides/adding-interactivity/components-with-state/index.rst

@@ -0,0 +1,27 @@
+# :lines: 11-
+
+from idom import run
+from idom.server import sanic as sanic_server
+
+
+# the run() function is the entry point for examples
+sanic_server.configure = lambda _, cmpt: run(cmpt)
+
+
+from sanic import Sanic
+
+from idom import component, html
+from idom.server.sanic import configure
+
+
+@component
+def HelloWorld():
+    return html.h1("Hello, world!")
+
+
+app = Sanic("MyApp")
+configure(app, HelloWorld)
+
+
+if __name__ == "__main__":
+    app.run(port=8000)

docs/source/guides/escape-hatches/_examples/super_simple_chart/app.py renamed to docs/source/guides/escape-hatches/_examples/super_simple_chart/main.py

@@ -0,0 +1,23 @@
+# :lines: 11-
+
+from idom import run
+from idom.server import starlette as starlette_server
+
+
+# the run() function is the entry point for examples
+starlette_server.configure = lambda _, cmpt: run(cmpt)
+
+
+from starlette.applications import Starlette
+
+from idom import component, html
+from idom.server.starlette import configure
+
+
+@component
+def HelloWorld():
+    return html.h1("Hello, world!")
+
+
+app = Starlette()
+configure(app, HelloWorld)