Add priority and final keyword to hooks.

Author: T4rk1n

dash/__init__.py

@@ -41,7 +41,7 @@
 from ._patch import Patch  # noqa: F401,E402
 from ._jupyter import jupyter_dash  # noqa: F401,E402
 
-from . import _hooks as hooks  # noqa: F401,E402
+from ._hooks import hooks  # noqa: F401,E402
 
 ctx = callback_context
 

dash/_hooks.py

@@ -3,65 +3,150 @@
 
 import flask as _f
 
-_ns = {
-    "setup": [],
-    "layout": [],
-    "routes": [],
-    "error": [],
-    "callback": [],
-}
-
-
-def layout(func):
-    """
-    Run a function when serving the layout, the return value
-    will be used as the layout.
-    """
-    _ns["layout"].append(func)
-    return func
-
-
-def setup(func):
-    """
-    Can be used to get a reference to the app after it is instantiated.
-    """
-    _ns["setup"].append(func)
-    return func
-
-
-def route(name: _t.Optional[str] = None, methods: _t.Sequence[str] = ("GET",)):
-    """
-    Add a route to the Dash server.
-    """
-
-    def wrap(func: _t.Callable[[], _f.Response]):
-        _name = name or func.__name__
-        _ns["routes"].append((_name, func, methods))
-        return func
-
-    return wrap
-
-
-def error(func: _t.Callable[[Exception], _t.Any]):
-    """Automatically add an error handler to the dash app."""
-    _ns["error"].append(func)
-    return func
-
-
-def callback(*args, **kwargs):
-    """
-    Add a callback to all the apps with the hook installed.
-    """
-
-    def wrap(func):
-        _ns["callback"].append((list(args), dict(kwargs), func))
-        return func
-
-    return wrap
+from .exceptions import HookError
+
+
+if _t.TYPE_CHECKING:
+    from .dash import Dash
+    from .development.base_component import Component
+
+    ComponentType = _t.TypeVar("ComponentType", bound=Component)
+    LayoutType = _t.Union[ComponentType, _t.List[ComponentType]]
+else:
+    LayoutType = None
+    ComponentType = None
+    Dash = None
+
+
+# pylint: disable=too-few-public-methods
+class _Hook:
+    def __init__(self, func, priority, final=False, data=None):
+        self.func = func
+        self.final = final
+        self.data = data
+        self.priority = priority
+
+    def __call__(self, *args, **kwargs):
+        return self.func(*args, **kwargs)
+
+
+class _Hooks:
+    def __init__(self) -> None:
+        self._ns = {
+            "setup": [],
+            "layout": [],
+            "routes": [],
+            "error": [],
+            "callback": [],
+        }
+        self._finals = {}
+
+    def add_hook(
+        self, hook: str, func: _t.Callable, priority=None, final=False, data=None
+    ):
+        if final:
+            existing = self._finals.get(hook)
+            if existing:
+                raise HookError("Final hook already present")
+            self._finals[hook] = _Hook(func, priority, final, data=data)
+            return
+        hks = self._ns.get(hook, [])
+        if not priority and len(hks):
+            priority_max = max(h.priority for h in hks)
+            priority = priority_max - 1
+        elif not priority:
+            priority = 0
+        hks.append(_Hook(func, priority=priority, data=data))
+        self._ns[hook] = sorted(hks, reverse=True, key=lambda h: h.priority)
+
+    def get_hooks(self, hook: str):
+        final = self._finals.get(hook, None)
+        if final:
+            final = [final]
+        else:
+            final = []
+        return self._ns.get(hook, []) + final
+
+    def layout(self, priority: _t.Optional[int] = None, final: bool = False):
+        """
+        Run a function when serving the layout, the return value
+        will be used as the layout.
+        """
+
+        def _wrap(func: _t.Callable[[LayoutType], LayoutType]):
+            self.add_hook("layout", func, priority=priority, final=final)
+            return func
+
+        return _wrap
+
+    def setup(self, priority: _t.Optional[int] = None, final: bool = False):
+        """
+        Can be used to get a reference to the app after it is instantiated.
+        """
+
+        def _setup(func: _t.Callable[[Dash], None]):
+            self.add_hook("setup", func, priority=priority, final=final)
+            return func
+
+        return _setup
+
+    def route(
+        self,
+        name: _t.Optional[str] = None,
+        methods: _t.Sequence[str] = ("GET",),
+        priority=None,
+        final=False,
+    ):
+        """
+        Add a route to the Dash server.
+        """
+
+        def wrap(func: _t.Callable[[], _f.Response]):
+            _name = name or func.__name__
+            self.add_hook(
+                "routes",
+                func,
+                priority=priority,
+                final=final,
+                data=dict(name=_name, methods=methods),
+            )
+            return func
+
+        return wrap
+
+    def error(self, priority=None, final=False):
+        """Automatically add an error handler to the dash app."""
+
+        def _error(func: _t.Callable[[Exception], _t.Any]):
+            self.add_hook("error", func, priority=priority, final=final)
+            return func
+
+        return _error
+
+    def callback(self, *args, priority=None, final=False, **kwargs):
+        """
+        Add a callback to all the apps with the hook installed.
+        """
+
+        def wrap(func):
+            self.add_hook(
+                "callback",
+                func,
+                priority=priority,
+                final=final,
+                data=(list(args), dict(kwargs)),
+            )
+            return func
+
+        return wrap
+
+
+hooks = _Hooks()
 
 
 class HooksManager:
     _registered = False
+    hooks = hooks
 
     # pylint: disable=too-few-public-methods
     class HookErrorHandler:
@@ -77,9 +162,9 @@ def __call__(self, err: Exception):
                 hook_result = hook(err)
             return result or hook_result
 
-    @staticmethod
-    def get_hooks(hook: str):
-        return _ns.get(hook, []).copy()
+    @classmethod
+    def get_hooks(cls, hook: str):
+        return cls.hooks.get_hooks(hook)
 
     @classmethod
     def register_setuptools(cls):

dash/dash.py

@@ -600,10 +600,9 @@ def _setup_hooks(self):
         for setup in self._hooks.get_hooks("setup"):
             setup(self)
 
-        for callback_args, callback_kwargs, callback in self._hooks.get_hooks(
-            "callback"
-        ):
-            self.callback(*callback_args, **callback_kwargs)(callback)
+        for hook in self._hooks.get_hooks("callback"):
+            callback_args, callback_kwargs = hook.data
+            self.callback(*callback_args, **callback_kwargs)(hook.func)
 
         if self._hooks.get_hooks("error"):
             self._on_error = self._hooks.HookErrorHandler(self._on_error)
@@ -708,8 +707,8 @@ def _setup_routes(self):
                 "_alive_" + jupyter_dash.alive_token, jupyter_dash.serve_alive
             )
 
-        for name, func, methods in self._hooks.get_hooks("routes"):
-            self._add_url(name, func, methods)
+        for hook in self._hooks.get_hooks("routes"):
+            self._add_url(hook.data["name"], hook.func, hook.data["methods"])
 
         # catch-all for front-end routes, used by dcc.Location
         self._add_url("<path:path>", self.index)

dash/exceptions.py

@@ -101,3 +101,7 @@ class PageError(DashException):
 
 class ImportedInsideCallbackError(DashException):
     pass
+
+
+class HookError(DashException):
+    pass

tests/integration/test_hooks.py

@@ -5,7 +5,7 @@
 from dash import Dash, Input, Output, html, hooks, set_props
 
 
-@pytest.fixture(scope="module", autouse=True)
+@pytest.fixture
 def hook_cleanup():
     yield
     hooks._ns["layout"] = []
@@ -15,8 +15,8 @@ def hook_cleanup():
     hooks._ns["callback"] = []
 
 
-def test_hook001_layout(dash_duo):
-    @hooks.layout
+def test_hook001_layout(hook_cleanup, dash_duo):
+    @hooks.layout()
     def on_layout(layout):
         return [html.Div("Header", id="header")] + layout
 
@@ -29,10 +29,10 @@ def on_layout(layout):
     dash_duo.wait_for_text_to_equal("#body", "Body")
 
 
-def test_hook002_setup():
+def test_hook002_setup(hook_cleanup):
     setup_title = None
 
-    @hooks.setup
+    @hooks.setup()
     def on_setup(app: Dash):
         nonlocal setup_title
         setup_title = app.title
@@ -43,7 +43,7 @@ def on_setup(app: Dash):
     assert setup_title == "setup-test"
 
 
-def test_hook003_route(dash_duo):
+def test_hook003_route(hook_cleanup, dash_duo):
     @hooks.route(methods=("POST",))
     def hook_route():
         return jsonify({"success": True})
@@ -57,8 +57,8 @@ def hook_route():
     assert data["success"]
 
 
-def test_hook004_error(dash_duo):
-    @hooks.error
+def test_hook004_error(hook_cleanup, dash_duo):
+    @hooks.error()
     def on_error(error):
         set_props("error", {"children": str(error)})
 
@@ -74,7 +74,7 @@ def on_click(_):
     dash_duo.wait_for_text_to_equal("#error", "hook error")
 
 
-def test_hook005_callback(dash_duo):
+def test_hook005_callback(hook_cleanup, dash_duo):
     @hooks.callback(
         Output("output", "children"),
         Input("start", "n_clicks"),
@@ -92,3 +92,41 @@ def on_hook_cb(n_clicks):
     dash_duo.start_server(app)
     dash_duo.wait_for_element("#start").click()
     dash_duo.wait_for_text_to_equal("#output", "clicked 1")
+
+
+def test_hook006_priority_final(hook_cleanup, dash_duo):
+    @hooks.layout(final=True)
+    def hook_final(layout):
+        return html.Div([html.Div("final")] + [layout], id="final-wrapper")
+
+    @hooks.layout()
+    def hook1(layout):
+        layout.children.append(html.Div("first"))
+        return layout
+
+    @hooks.layout()
+    def hook2(layout):
+        layout.children.append(html.Div("second"))
+        return layout
+
+    @hooks.layout()
+    def hook3(layout):
+        layout.children.append(html.Div("third"))
+        return layout
+
+    @hooks.layout(priority=6)
+    def hook4(layout):
+        layout.children.insert(0, html.Div("Prime"))
+        return layout
+
+    app = Dash()
+
+    app.layout = html.Div([html.Div("layout")], id="body")
+
+    dash_duo.start_server(app)
+    dash_duo.wait_for_text_to_equal("#final-wrapper > div:first-child", "final")
+    dash_duo.wait_for_text_to_equal("#body > div:first-child", "Prime")
+    dash_duo.wait_for_text_to_equal("#body > div:nth-child(2)", "layout")
+    dash_duo.wait_for_text_to_equal("#body > div:nth-child(3)", "first")
+    dash_duo.wait_for_text_to_equal("#body > div:nth-child(4)", "second")
+    dash_duo.wait_for_text_to_equal("#body > div:nth-child(5)", "third")