RFC/1630 Signals

sanic/app.py

@@ -1,3 +1,4 @@
+import asyncio
 import logging
 import logging.config
 import os
@@ -13,7 +14,9 @@
 from traceback import format_exc
 from typing import (
     Any,
+    Awaitable,
     Callable,
+    Coroutine,
     Deque,
     Dict,
     Iterable,
@@ -26,6 +29,7 @@
 from urllib.parse import urlencode, urlunparse
 
 from sanic_routing.exceptions import FinalizationError  # type: ignore
+from sanic_routing.exceptions import NotFound  # type: ignore
 from sanic_routing.route import Route  # type: ignore
 
 from sanic import reloader_helpers
@@ -48,20 +52,17 @@
     FutureListener,
     FutureMiddleware,
     FutureRoute,
+    FutureSignal,
     FutureStatic,
 )
 from sanic.models.handler_types import ListenerType, MiddlewareType
 from sanic.request import Request
 from sanic.response import BaseHTTPResponse, HTTPResponse
 from sanic.router import Router
-from sanic.server import (
-    AsyncioServer,
-    HttpProtocol,
-    Signal,
-    serve,
-    serve_multiple,
-    serve_single,
-)
+from sanic.server import AsyncioServer, HttpProtocol
+from sanic.server import Signal as ServerSignal
+from sanic.server import serve, serve_multiple, serve_single
+from sanic.signals import Signal, SignalRouter
 from sanic.websocket import ConnectionClosed, WebSocketProtocol
 
 
@@ -76,10 +77,11 @@ class Sanic(BaseSanic):
     def __init__(
         self,
         name: str = None,
-        router: Router = None,
-        error_handler: ErrorHandler = None,
+        router: Optional[Router] = None,
+        signal_router: Optional[SignalRouter] = None,
+        error_handler: Optional[ErrorHandler] = None,
         load_env: bool = True,
-        request_class: Type[Request] = None,
+        request_class: Optional[Type[Request]] = None,
         strict_slashes: bool = False,
         log_config: Optional[Dict[str, Any]] = None,
         configure_logging: bool = True,
@@ -100,6 +102,7 @@ def __init__(
         self.name = name
         self.asgi = False
         self.router = router or Router()
+        self.signal_router = signal_router or SignalRouter()
         self.request_class = request_class
         self.error_handler = error_handler or ErrorHandler()
         self.config = Config(load_env=load_env)
@@ -162,7 +165,7 @@ def add_task(self, task) -> None:
         also return a future, and the actual ensure_future call
         is delayed until before server start.
 
-        `See user guide
+        `See user guide re: background tasks
         <https://sanicframework.org/guide/basics/tasks.html#background-tasks>`__
 
         :param task: future, couroutine or awaitable
@@ -309,6 +312,28 @@ def _apply_middleware(
                 middleware.middleware, middleware.attach_to
             )
 
+    def _apply_signal(self, signal: FutureSignal) -> Signal:
+        return self.signal_router.add(*signal)
+
+    def dispatch(
+        self,
+        event: str,
+        *,
+        where: Optional[Dict[str, str]] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> Coroutine[Any, Any, Awaitable[Any]]:
+        return self.signal_router.dispatch(
+            event,
+            context=context,
+            where=where,
+        )
+
+    def event(self, event: str, timeout: Optional[Union[int, float]] = None):
+        signal = self.signal_router.name_index.get(event)
+        if not signal:
+            raise NotFound("Could not find signal %s" % event)
+        return asyncio.wait_for(signal.ctx.event.wait(), timeout=timeout)
+
     def enable_websocket(self, enable=True):
         """Enable or disable the support for websocket.
 
@@ -382,7 +407,7 @@ def url_for(self, view_name: str, **kwargs):
 
             app.config.SERVER_NAME = "myserver:7777"
 
-        `See user guide
+        `See user guide re: routing
         <https://sanicframework.org/guide/basics/routing.html#generating-a-url>`__
 
         :param view_name: string referencing the view name
@@ -1031,11 +1056,9 @@ def _helper(
     ):
         """Helper function used by `run` and `create_server`."""
 
-        try:
-            self.router.finalize()
-        except FinalizationError as e:
-            if not Sanic.test_mode:
-                raise e
+        self.listeners["before_server_start"] = [
+            self.finalize
+        ] + self.listeners["before_server_start"]
 
         if isinstance(ssl, dict):
             # try common aliaseses
@@ -1064,7 +1087,7 @@ def _helper(
             "unix": unix,
             "ssl": ssl,
             "app": self,
-            "signal": Signal(),
+            "signal": ServerSignal(),
             "loop": loop,
             "register_sys_signals": register_sys_signals,
             "backlog": backlog,
@@ -1159,7 +1182,7 @@ def update_config(self, config: Union[bytes, str, dict, Any]):
         """
         Update app.config. Full implementation can be found in the user guide.
 
-        `See user guide
+        `See user guide re: configuration
         <https://sanicframework.org/guide/deployment/configuration.html#basics>`__
         """
 
@@ -1196,7 +1219,7 @@ def get_app(
                     'Multiple Sanic apps found, use Sanic.get_app("app_name")'
                 )
             elif len(cls._app_registry) == 0:
-                raise SanicException(f"No Sanic apps have been registered.")
+                raise SanicException("No Sanic apps have been registered.")
             else:
                 return list(cls._app_registry.values())[0]
         try:
@@ -1205,3 +1228,17 @@ def get_app(
             if force_create:
                 return cls(name)
             raise SanicException(f'Sanic app name "{name}" not found.')
+
+    # -------------------------------------------------------------------- #
+    # Static methods
+    # -------------------------------------------------------------------- #
+
+    @staticmethod
+    async def finalize(app, _):
+        try:
+            app.router.finalize()
+            if app.signal_router.routes:
+                app.signal_router.finalize()  # noqa
+        except FinalizationError as e:
+            if not Sanic.test_mode:
+                raise e  # noqa

sanic/asgi.py

@@ -43,6 +43,8 @@ async def startup(self) -> None:
         startup event.
         """
         self.asgi_app.sanic_app.router.finalize()
+        if self.asgi_app.sanic_app.signal_router.routes:
+            self.asgi_app.sanic_app.signal_router.finalize()
         listeners = self.asgi_app.sanic_app.listeners.get(
             "before_server_start", []
         ) + self.asgi_app.sanic_app.listeners.get("after_server_start", [])

sanic/base.py

@@ -2,6 +2,7 @@
 from sanic.mixins.listeners import ListenerMixin
 from sanic.mixins.middleware import MiddlewareMixin
 from sanic.mixins.routes import RouteMixin
+from sanic.mixins.signals import SignalMixin
 
 
 class Base(type):
@@ -31,6 +32,7 @@ class BaseSanic(
     MiddlewareMixin,
     ListenerMixin,
     ExceptionMixin,
+    SignalMixin,
     metaclass=Base,
 ):
     def __str__(self) -> str:

sanic/blueprints.py

@@ -1,10 +1,16 @@
+from __future__ import annotations
+
+import asyncio
+
 from collections import defaultdict
-from typing import Dict, Iterable, List, Optional
+from typing import TYPE_CHECKING, Dict, Iterable, List, Optional, Set, Union
 
+from sanic_routing.exceptions import NotFound  # type: ignore
 from sanic_routing.route import Route  # type: ignore
 
 from sanic.base import BaseSanic
 from sanic.blueprint_group import BlueprintGroup
+from sanic.exceptions import SanicException
 from sanic.models.futures import FutureRoute, FutureStatic
 from sanic.models.handler_types import (
     ListenerType,
@@ -13,6 +19,10 @@
 )
 
 
+if TYPE_CHECKING:
+    from sanic import Sanic  # noqa
+
+
 class Blueprint(BaseSanic):
     """
     In *Sanic* terminology, a **Blueprint** is a logical collection of
@@ -21,7 +31,7 @@ class Blueprint(BaseSanic):
 
     It is the main tool for grouping functionality and similar endpoints.
 
-    `See user guide
+    `See user guide re: blueprints
     <https://sanicframework.org/guide/best-practices/blueprints.html>`__
 
     :param name: unique name of the blueprint
@@ -40,6 +50,7 @@ def __init__(
         version: Optional[int] = None,
         strict_slashes: Optional[bool] = None,
     ):
+        self._apps: Set[Sanic] = set()
         self.name = name
         self.url_prefix = url_prefix
         self.host = host
@@ -70,6 +81,14 @@ def __repr__(self) -> str:
         )
         return f"Blueprint({args})"
 
+    @property
+    def apps(self):
+        if not self._apps:
+            raise SanicException(
+                f"{self} has not yet been registered to an app"
+            )
+        return self._apps
+
     def route(self, *args, **kwargs):
         kwargs["apply"] = False
         return super().route(*args, **kwargs)
@@ -90,6 +109,10 @@ def exception(self, *args, **kwargs):
         kwargs["apply"] = False
         return super().exception(*args, **kwargs)
 
+    def signal(self, event: str, *args, **kwargs):
+        kwargs["apply"] = False
+        return super().signal(event, *args, **kwargs)
+
     @staticmethod
     def group(*blueprints, url_prefix="", version=None, strict_slashes=None):
         """
@@ -132,6 +155,7 @@ def register(self, app, options):
             *url_prefix* - URL Prefix to override the blueprint prefix
         """
 
+        self._apps.add(app)
         url_prefix = options.get("url_prefix", self.url_prefix)
 
         routes = []
@@ -200,6 +224,10 @@ def register(self, app, options):
         for listener in self._future_listeners:
             listeners[listener.event].append(app._apply_listener(listener))
 
+        for signal in self._future_signals:
+            signal.where.update({"blueprint": self.name})
+            app._apply_signal(signal)
+
         self.routes = [route for route in routes if isinstance(route, Route)]
 
         # Deprecate these in 21.6
@@ -209,3 +237,28 @@ def register(self, app, options):
         self.middlewares = middleware
         self.exceptions = exception_handlers
         self.listeners = dict(listeners)
+
+    async def dispatch(self, *args, **kwargs):
+        where = kwargs.pop("where", {})
+        where.update({"blueprint": self.name})
+        kwargs["where"] = where
+        await asyncio.gather(
+            *[app.dispatch(*args, **kwargs) for app in self.apps]
+        )
+
+    def event(self, event: str, timeout: Optional[Union[int, float]] = None):
+        events = set()
+        for app in self.apps:
+            signal = app.signal_router.name_index.get(event)
+            if not signal:
+                raise NotFound("Could not find signal %s" % event)
+            events.add(signal.ctx.event)
+
+        if events:
+            return asyncio.wait(
+                [event.wait() for event in events],
+                return_when=asyncio.FIRST_COMPLETED,
+                timeout=timeout,
+            )
+
+        raise NotFound("Could not find signal %s" % event)

sanic/config.py

@@ -134,7 +134,7 @@ class C:
 
             config.update_config(C)
 
-        `See user guide
+        `See user guide re: config
         <https://sanicframework.org/guide/deployment/configuration.html>`__
         """
 

sanic/exceptions.py

@@ -227,6 +227,10 @@ class LoadFileException(SanicException):
     pass
 
 
+class InvalidSignal(SanicException):
+    pass
+
+
 def abort(status_code: int, message: Optional[Union[str, bytes]] = None):
     """
     Raise an exception based on SanicException. Returns the HTTP response

sanic/mixins/listeners.py

@@ -43,8 +43,8 @@ def listener(
             async def before_server_start(app, loop):
                 ...
 
-        `See user guide
-        <https://sanicframework.org/guide/basics/listeners.html#listeners>`_
+        `See user guide re: listeners
+        <https://sanicframework.org/guide/basics/listeners.html#listeners>`__
 
         :param event: event to listen to
         """

sanic/mixins/middleware.py

@@ -19,8 +19,8 @@ def middleware(
         Can either be called as *@app.middleware* or
         *@app.middleware('request')*
 
-        `See user guide
-        <https://sanicframework.org/guide/basics/middleware.html>`_
+        `See user guide re: middleware
+        <https://sanicframework.org/guide/basics/middleware.html>`__
 
         :param: middleware_or_request: Optional parameter to use for
             identifying which type of middleware is being registered.

sanic/mixins/routes.py

@@ -32,7 +32,7 @@ def __init__(self, *args, **kwargs) -> None:
         self.name = ""
         self.strict_slashes: Optional[bool] = False
 
-    def _apply_route(self, route: FutureRoute) -> Route:
+    def _apply_route(self, route: FutureRoute) -> List[Route]:
         raise NotImplementedError  # noqa
 
     def _apply_static(self, static: FutureStatic) -> Route: