Merge pull request #1228 from plotly/prevent-initial-call

Prevent initial call

Author: alexcjohnson

CHANGELOG.md

@@ -4,6 +4,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [UNRELEASED]
 ### Added
+- [#1228](https://github.com/plotly/dash/pull/1228) Adds control over firing callbacks on page (or layout chunk) load. Individual callbacks can have their initial calls disabled in their definition `@app.callback(..., prevent_initial_call=True)` and similar for `app.clientside_callback`. The app-wide default can also be changed with `app=Dash(prevent_initial_callbacks=True)`, then individual callbacks may disable this behavior.
 - [#1201](https://github.com/plotly/dash/pull/1201) New attribute `app.validation_layout` allows you to create a multi-page app without `suppress_callback_exceptions=True` or layout function tricks. Set this to a component layout containing the superset of all IDs on all pages in your app.
 - [#1078](https://github.com/plotly/dash/pull/1078) Permit usage of arbitrary file extensions for assets within component libraries
 

dash-renderer/src/actions/dependencies.js

@@ -1238,6 +1238,9 @@ export function getCallbacksInLayout(graphs, paths, layoutChunk, opts) {
                 ) {
                     // This callback should trigger even with no changedProps,
                     // since the props that changed no longer exist.
+                    // We're kind of abusing the `initialCall` flag here, it's
+                    // more like a "final call" for the removed inputs, but
+                    // this case is not subject to `prevent_initial_call`.
                     if (flatten(cb.getOutputs(newPaths)).length) {
                         cb.initialCall = true;
                         cb.changedPropIds = {};
@@ -1255,10 +1258,13 @@ export function getCallbacksInLayout(graphs, paths, layoutChunk, opts) {
                 const cb = getCallbackByOutput(graphs, paths, id, property);
                 if (cb) {
                     // callbacks found in the layout by output should always run
+                    // unless specifically requested not to.
                     // ie this is the initial call of this callback even if it's
                     // not the page initialization but just a new layout chunk
-                    cb.initialCall = true;
-                    addCallback(cb);
+                    if (!cb.callback.prevent_initial_call) {
+                        cb.initialCall = true;
+                        addCallback(cb);
+                    }
                 }
             }
         }
@@ -1270,14 +1276,13 @@ export function getCallbacksInLayout(graphs, paths, layoutChunk, opts) {
             if (chunkPath) {
                 handleThisCallback = cb => {
                     if (
-                        all(
+                        !all(
                             startsWith(chunkPath),
                             pluck('path', flatten(cb.getOutputs(paths)))
                         )
                     ) {
-                        cb.changedPropIds = {};
+                        maybeAddCallback(cb);
                     }
-                    maybeAddCallback(cb);
                 };
             }
             for (const property in inIdCallbacks) {

dash/dash.py

@@ -211,6 +211,15 @@ class Dash(object):
         env: ``DASH_SUPPRESS_CALLBACK_EXCEPTIONS``
     :type suppress_callback_exceptions: boolean
 
+    :param prevent_initial_callbacks: Default ``False``: Sets the default value
+        of ``prevent_initial_call`` for all callbacks added to the app.
+        Normally all callbacks are fired when the associated outputs are first
+        added to the page. You can disable this for individual callbacks by
+        setting ``prevent_initial_call`` in their definitions, or set it
+        ``True`` here in which case you must explicitly set it ``False`` for
+        those callbacks you wish to have an initial call. This setting has no
+        effect on triggering callbacks when their inputs change later on.
+
     :param show_undo_redo: Default ``False``, set to ``True`` to enable undo
         and redo buttons for stepping through the history of the app state.
     :type show_undo_redo: boolean
@@ -241,6 +250,7 @@ def __init__(
         external_scripts=None,
         external_stylesheets=None,
         suppress_callback_exceptions=None,
+        prevent_initial_callbacks=False,
         show_undo_redo=False,
         plugins=None,
         **obsolete
@@ -288,6 +298,7 @@ def __init__(
             suppress_callback_exceptions=get_combined_config(
                 "suppress_callback_exceptions", suppress_callback_exceptions, False
             ),
+            prevent_initial_callbacks=prevent_initial_callbacks,
             show_undo_redo=show_undo_redo,
         )
         self.config.set_read_only(
@@ -813,14 +824,18 @@ def interpolate_index(self, **kwargs):
     def dependencies(self):
         return flask.jsonify(self._callback_list)
 
-    def _insert_callback(self, output, inputs, state):
+    def _insert_callback(self, output, inputs, state, prevent_initial_call):
+        if prevent_initial_call is None:
+            prevent_initial_call = self.config.prevent_initial_callbacks
+
         _validate.validate_callback(output, inputs, state)
         callback_id = create_callback_id(output)
         callback_spec = {
             "output": callback_id,
             "inputs": [c.to_dict() for c in inputs],
             "state": [c.to_dict() for c in state],
             "clientside_function": None,
+            "prevent_initial_call": prevent_initial_call,
         }
         self.callback_map[callback_id] = {
             "inputs": callback_spec["inputs"],
@@ -830,7 +845,9 @@ def _insert_callback(self, output, inputs, state):
 
         return callback_id
 
-    def clientside_callback(self, clientside_function, output, inputs, state=()):
+    def clientside_callback(
+        self, clientside_function, output, inputs, state=(), prevent_initial_call=None
+    ):
         """Create a callback that updates the output by calling a clientside
         (JavaScript) function instead of a Python function.
 
@@ -890,8 +907,12 @@ def clientside_callback(self, clientside_function, output, inputs, state=()):
              Input('another-input', 'value')]
         )
         ```
+
+        The last, optional argument `prevent_initial_call` causes the callback
+        not to fire when its outputs are first added to the page. Defaults to
+        `False` unless `prevent_initial_callbacks=True` at the app level.
         """
-        self._insert_callback(output, inputs, state)
+        self._insert_callback(output, inputs, state, prevent_initial_call)
 
         # If JS source is explicitly given, create a namespace and function
         # name, then inject the code.
@@ -922,8 +943,19 @@ def clientside_callback(self, clientside_function, output, inputs, state=()):
             "function_name": function_name,
         }
 
-    def callback(self, output, inputs, state=()):
-        callback_id = self._insert_callback(output, inputs, state)
+    def callback(self, output, inputs, state=(), prevent_initial_call=None):
+        """
+        Normally used as a decorator, `@app.callback` provides a server-side
+        callback relating the values of one or more `output` items to one or
+        more `input` items which will trigger the callback when they change,
+        and optionally `state` items which provide additional information but
+        do not trigger the callback directly.
+
+        The last, optional argument `prevent_initial_call` causes the callback
+        not to fire when its outputs are first added to the page. Defaults to
+        `False` unless `prevent_initial_callbacks=True` at the app level.
+        """
+        callback_id = self._insert_callback(output, inputs, state, prevent_initial_call)
         multi = isinstance(output, (list, tuple))
 
         def wrap_func(func):