reactpy.run and configure(...) refactoring

docs/source/about/changelog.rst

@@ -26,11 +26,15 @@ Unreleased
 **Changed**
 
 - :pull:`1050` - Warn and attempt to fix missing mime types, which can result in ``reactpy.run`` not working as expected.
+- :pull:`1051` - Rename ``reactpy.backend.BackendImplementation`` to ``reactpy.backend.BackendProtocol``
+- :pull:`1051` - Allow ``reactpy.run`` to fail in more predictable ways
 
 **Fixed**
 
 - :issue:`930` - better traceback for JSON serialization errors (via :pull:`1008`)
 - :issue:`437` - explain that JS component attributes must be JSON (via :pull:`1008`)
+- :pull:`1051` - Fix ``reactpy.run`` port assignment sometimes attaching to in-use ports on Windows
+- :pull:`1051` - Fix ``reactpy.run`` not recognizing ``fastapi``
 
 
 v1.0.0

src/py/reactpy/reactpy/backend/_common.py

@@ -14,53 +14,49 @@
 from reactpy.utils import vdom_to_html
 
 if TYPE_CHECKING:
+    import uvicorn
     from asgiref.typing import ASGIApplication
 
 PATH_PREFIX = PurePosixPath("/_reactpy")
 MODULES_PATH = PATH_PREFIX / "modules"
 ASSETS_PATH = PATH_PREFIX / "assets"
 STREAM_PATH = PATH_PREFIX / "stream"
-
 CLIENT_BUILD_DIR = Path(_reactpy_file_path).parent / "_static" / "app" / "dist"
 
-try:
+
+async def serve_with_uvicorn(
+    app: ASGIApplication | Any,
+    host: str,
+    port: int,
+    started: asyncio.Event | None,
+) -> None:
+    """Run a development server for an ASGI application"""
     import uvicorn
-except ImportError:  # nocov
-    pass
-else:
-
-    async def serve_development_asgi(
-        app: ASGIApplication | Any,
-        host: str,
-        port: int,
-        started: asyncio.Event | None,
-    ) -> None:
-        """Run a development server for an ASGI application"""
-        server = uvicorn.Server(
-            uvicorn.Config(
-                app,
-                host=host,
-                port=port,
-                loop="asyncio",
-                reload=True,
-            )
+
+    server = uvicorn.Server(
+        uvicorn.Config(
+            app,
+            host=host,
+            port=port,
+            loop="asyncio",
         )
-        server.config.setup_event_loop()
-        coros: list[Awaitable[Any]] = [server.serve()]
+    )
+    server.config.setup_event_loop()
+    coros: list[Awaitable[Any]] = [server.serve()]
 
-        # If a started event is provided, then use it signal based on `server.started`
-        if started:
-            coros.append(_check_if_started(server, started))
+    # If a started event is provided, then use it signal based on `server.started`
+    if started:
+        coros.append(_check_if_started(server, started))
 
-        try:
-            await asyncio.gather(*coros)
-        finally:
-            # Since we aren't using the uvicorn's `run()` API, we can't guarantee uvicorn's
-            # order of operations. So we need to make sure `shutdown()` always has an initialized
-            # list of `self.servers` to use.
-            if not hasattr(server, "servers"):  # nocov
-                server.servers = []
-            await asyncio.wait_for(server.shutdown(), timeout=3)
+    try:
+        await asyncio.gather(*coros)
+    finally:
+        # Since we aren't using the uvicorn's `run()` API, we can't guarantee uvicorn's
+        # order of operations. So we need to make sure `shutdown()` always has an initialized
+        # list of `self.servers` to use.
+        if not hasattr(server, "servers"):  # nocov
+            server.servers = []
+        await asyncio.wait_for(server.shutdown(), timeout=3)
 
 
 async def _check_if_started(server: uvicorn.Server, started: asyncio.Event) -> None:
@@ -72,8 +68,7 @@ async def _check_if_started(server: uvicorn.Server, started: asyncio.Event) -> N
 def safe_client_build_dir_path(path: str) -> Path:
     """Prevent path traversal out of :data:`CLIENT_BUILD_DIR`"""
     return traversal_safe_path(
-        CLIENT_BUILD_DIR,
-        *("index.html" if path in ("", "/") else path).split("/"),
+        CLIENT_BUILD_DIR, *("index.html" if path in {"", "/"} else path).split("/")
     )
 
 
@@ -140,6 +135,9 @@ class CommonOptions:
     url_prefix: str = ""
     """The URL prefix where ReactPy resources will be served from"""
 
+    serve_index_route: bool = True
+    """Automatically generate and serve the index route (``/``)"""
+
     def __post_init__(self) -> None:
         if self.url_prefix and not self.url_prefix.startswith("/"):
             msg = "Expected 'url_prefix' to start with '/'"

src/py/reactpy/reactpy/backend/default.py

@@ -5,13 +5,26 @@
 from sys import exc_info
 from typing import Any, NoReturn
 
-from reactpy.backend.types import BackendImplementation
-from reactpy.backend.utils import SUPPORTED_PACKAGES, all_implementations
+from reactpy.backend.types import BackendType
+from reactpy.backend.utils import SUPPORTED_BACKENDS, all_implementations
 from reactpy.types import RootComponentConstructor
 
 logger = getLogger(__name__)
+_DEFAULT_IMPLEMENTATION: BackendType[Any] | None = None
 
 
+# BackendProtocol.Options
+class Options:  # nocov
+    """Create configuration options"""
+
+    def __init__(self, *args: Any, **kwds: Any) -> NoReturn:
+        """This should not be used, since default options should never
+        be constructed. Please override this method."""
+        msg = "Default implementation has no options."
+        raise ValueError(msg)
+
+
+# BackendProtocol.configure
 def configure(
     app: Any, component: RootComponentConstructor, options: None = None
 ) -> None:
@@ -22,17 +35,13 @@ def configure(
     return _default_implementation().configure(app, component)
 
 
+# BackendProtocol.create_development_app
 def create_development_app() -> Any:
     """Create an application instance for development purposes"""
     return _default_implementation().create_development_app()
 
 
-def Options(*args: Any, **kwargs: Any) -> NoReturn:  # nocov
-    """Create configuration options"""
-    msg = "Default implementation has no options."
-    raise ValueError(msg)
-
-
+# BackendProtocol.serve_development_app
 async def serve_development_app(
     app: Any,
     host: str,
@@ -45,10 +54,7 @@ async def serve_development_app(
     )
 
 
-_DEFAULT_IMPLEMENTATION: BackendImplementation[Any] | None = None
-
-
-def _default_implementation() -> BackendImplementation[Any]:
+def _default_implementation() -> BackendType[Any]:
     """Get the first available server implementation"""
     global _DEFAULT_IMPLEMENTATION  # noqa: PLW0603
 
@@ -59,7 +65,7 @@ def _default_implementation() -> BackendImplementation[Any]:
         implementation = next(all_implementations())
     except StopIteration:  # nocov
         logger.debug("Backend implementation import failed", exc_info=exc_info())
-        supported_backends = ", ".join(SUPPORTED_PACKAGES)
+        supported_backends = ", ".join(SUPPORTED_BACKENDS)
         msg = (
             "It seems you haven't installed a backend. To resolve this issue, "
             "you can install a backend by running:\n\n"

src/py/reactpy/reactpy/backend/fastapi.py

@@ -4,22 +4,22 @@
 
 from reactpy.backend import starlette
 
-serve_development_app = starlette.serve_development_app
-"""Alias for :func:`reactpy.backend.starlette.serve_development_app`"""
-
-use_connection = starlette.use_connection
-"""Alias for :func:`reactpy.backend.starlette.use_location`"""
-
-use_websocket = starlette.use_websocket
-"""Alias for :func:`reactpy.backend.starlette.use_websocket`"""
-
+# BackendProtocol.Options
 Options = starlette.Options
-"""Alias for :class:`reactpy.backend.starlette.Options`"""
 
+# BackendProtocol.configure
 configure = starlette.configure
-"""Alias for :class:`reactpy.backend.starlette.configure`"""
 
 
+# BackendProtocol.create_development_app
 def create_development_app() -> FastAPI:
     """Create a development ``FastAPI`` application instance."""
     return FastAPI(debug=True)
+
+
+# BackendProtocol.serve_development_app
+serve_development_app = starlette.serve_development_app
+
+use_connection = starlette.use_connection
+
+use_websocket = starlette.use_websocket

src/py/reactpy/reactpy/backend/flask.py

@@ -45,6 +45,19 @@
 logger = logging.getLogger(__name__)
 
 
+# BackendProtocol.Options
+@dataclass
+class Options(CommonOptions):
+    """Render server config for :func:`reactpy.backend.flask.configure`"""
+
+    cors: bool | dict[str, Any] = False
+    """Enable or configure Cross Origin Resource Sharing (CORS)
+
+    For more information see docs for ``flask_cors.CORS``
+    """
+
+
+# BackendProtocol.configure
 def configure(
     app: Flask, component: RootComponentConstructor, options: Options | None = None
 ) -> None:
@@ -69,20 +82,21 @@ def configure(
     app.register_blueprint(spa_bp)
 
 
+# BackendProtocol.create_development_app
 def create_development_app() -> Flask:
     """Create an application instance for development purposes"""
     os.environ["FLASK_DEBUG"] = "true"
-    app = Flask(__name__)
-    return app
+    return Flask(__name__)
 
 
+# BackendProtocol.serve_development_app
 async def serve_development_app(
     app: Flask,
     host: str,
     port: int,
     started: asyncio.Event | None = None,
 ) -> None:
-    """Run an application using a development server"""
+    """Run a development server for FastAPI"""
     loop = asyncio.get_running_loop()
     stopped = asyncio.Event()
 
@@ -135,17 +149,6 @@ def use_connection() -> Connection[_FlaskCarrier]:
     return conn
 
 
-@dataclass
-class Options(CommonOptions):
-    """Render server config for :func:`reactpy.backend.flask.configure`"""
-
-    cors: bool | dict[str, Any] = False
-    """Enable or configure Cross Origin Resource Sharing (CORS)
-
-    For more information see docs for ``flask_cors.CORS``
-    """
-
-
 def _setup_common_routes(
     api_blueprint: Blueprint,
     spa_blueprint: Blueprint,
@@ -166,10 +169,12 @@ def send_modules_dir(path: str = "") -> Any:
 
     index_html = read_client_index_html(options)
 
-    @spa_blueprint.route("/")
-    @spa_blueprint.route("/<path:_>")
-    def send_client_dir(_: str = "") -> Any:
-        return index_html
+    if options.serve_index_route:
+
+        @spa_blueprint.route("/")
+        @spa_blueprint.route("/<path:_>")
+        def send_client_dir(_: str = "") -> Any:
+            return index_html
 
 
 def _setup_single_view_dispatcher_route(