Merge pull request #29 from delsim/doc_live_updating

Documentation for live updating

Author: GibbsConsulting

demo/demo/plotly_apps.py

@@ -134,6 +134,7 @@ def callback_c(*args, **kwargs):
     html.Div(id='button_local_counter', children="Press any button to start"),
     ], className="")
 
+#pylint: disable=too-many-arguments
 @liveIn.expanded_callback(
     dash.dependencies.Output('button_local_counter', 'children'),
     [dash.dependencies.Input('red-button', 'n_clicks'),
@@ -186,10 +187,10 @@ def callback_liveIn_button_press(red_clicks, blue_clicks, green_clicks,
                                                                                              datetime.fromtimestamp(0.001*timestamp))
 
 liveOut = DjangoDash("LiveOutput",
-                    )#serve_locally=True)
+                     )#serve_locally=True)
 
 def _get_cache_key(state_uid):
-    return "demo-liveout-s4-%s" % state_uid
+    return "demo-liveout-s6-%s" % state_uid
 
 def generate_liveOut_layout():
     'Generate the layout per-app, generating each tine a new uuid for the state_uid argument'
@@ -210,6 +211,7 @@ def generate_liveOut_layout():
 
 liveOut.layout = generate_liveOut_layout
 
+#pylint: disable=unused-argument
 #@liveOut.expanded_callback(
 @liveOut.callback(
     dash.dependencies.Output('internal_state', 'children'),
@@ -242,6 +244,18 @@ def callback_liveOut_pipe_in(named_count, state_uid, **kwargs):
             colour_set = [(None, 0, 100) for i in range(5)]
 
         _, last_ts, prev = colour_set[-1]
+
+        # Loop over all existing timestamps and find the latest one
+        if not click_timestamp or click_timestamp < 1:
+            click_timestamp = 0
+
+            for _, the_colour_set in state.items():
+                _, lts, _ = the_colour_set[-1]
+                if lts > click_timestamp:
+                    click_timestamp = lts
+
+            click_timestamp = click_timestamp + 1000
+
         if click_timestamp > last_ts:
             colour_set.append((user, click_timestamp, prev * random.lognormvariate(0.0, 0.1)),)
             colour_set = colour_set[-100:]
@@ -268,23 +282,28 @@ def callback_show_timeseries(internal_state_string, state_uid, **kwargs):
 
     colour_series = {}
 
+    colors = {'red':'#FF0000',
+              'blue':'#0000FF',
+              'green':'#00FF00',
+              'yellow': '#FFFF00',
+              'cyan': '#00FFFF',
+              'magenta': '#FF00FF',
+              'black' : '#000000',
+             }
+
     for colour, values in state.items():
         timestamps = [datetime.fromtimestamp(int(0.001*ts)) for _, ts, _ in values if ts > 0]
-        users = [user for user, ts, _ in values if ts > 0]
+        #users = [user for user, ts, _ in values if ts > 0]
         levels = [level for _, ts, level in values if ts > 0]
-        colour_series[colour] = pd.Series(levels, index=timestamps).groupby(level=0).first()
+        if colour in colors:
+            colour_series[colour] = pd.Series(levels, index=timestamps).groupby(level=0).first()
 
     df = pd.DataFrame(colour_series).fillna(method="ffill").reset_index()[-25:]
 
-    colors = {'red':'#FF0000',
-              'blue':'#0000FF',
-              'green':'#00FF00',
-             }
-
     traces = [go.Scatter(y=df[colour],
                          x=df['index'],
                          name=colour,
-                         line=dict(color=colors[colour]),
+                         line=dict(color=colors.get(colour, '#000000')),
                         ) for colour in colour_series]
 
     return {'data':traces,

demo/demo/settings.py

@@ -125,6 +125,8 @@
     "ws_route" : "ws/channel",
 
     "insert_demo_migrations" : True,  # Insert model instances used by the demo
+
+    "http_poke_enabled" : True, # Flag controlling availability of direct-to-messaging http endpoint
     }
 
 # Static files (CSS, JavaScript, Images)
@@ -165,6 +167,10 @@
 # can be useful for development especially if offline - we add in the root directory
 # of each module. This is a bit of fudge and only needed if serve_locally=True is
 # set on a DjangoDash instance.
+#
+# Note that this makes all of the python module (including .py and .pyc) files available
+# through the static route. This is not a big deal for development but at the same time
+# not particularly neat or tidy.
 
 if DEBUG:
 

demo/demo/templates/base.html

@@ -25,6 +25,9 @@
          <a class="nav-item nav-link btn btn-lg" href="{%url "demo-two"%}">Demo Two - Initial State</a>
          <a class="nav-item nav-link btn btn-lg" href="{%url "demo-three"%}">Demo Three - Enhanced Callbacks</a>
          <a class="nav-item nav-link btn btn-lg" href="{%url "demo-four"%}">Demo Four - Live Updating</a>
+         <a class="nav-item nav-link btn btn-lg"
+            target="_blank"
+            href="https://django-plotly-dash.readthedocs.io/en/latest/">Online Documentation</a>
          {%endblock%}
        </div>
      </nav>

demo/demo/templates/demo_four.html

@@ -41,4 +41,17 @@ <h1>Live Updating</h1>
     {%plotly_app slug="liveoutput-2" ratio=0.5 %}
   </div>
 </div>
+<p>
+</p>
+<p>
+  Any http command
+  can be used to send a message to the apps. This is equiavent to a press of
+  the red button. Other colours can be specified, including yellow, cyan and black in
+  addition to the three named in the LiveInput app.
+</p>
+<div class="card bg-light border-dark">
+  <div class="card-body">
+    curl http://localhost:8000/dpd/views/poke/ -d'{"channel_name":"live_button_counter","label":"named_counts","value":{"click_colour":"red"}}'
+  </div>
+</div>
 {%endblock%}

demo/demo/urls.py

@@ -28,6 +28,8 @@
 # Load demo plotly apps - this triggers their registration
 import demo.plotly_apps # pylint: disable=unused-import
 
+from django_plotly_dash.views import add_to_session
+
 urlpatterns = [
     url('^$', TemplateView.as_view(template_name='index.html'), name="home"),
     url('^demo-one$', TemplateView.as_view(template_name='demo_one.html'), name="demo-one"),
@@ -36,6 +38,8 @@
     url('^demo-four$', TemplateView.as_view(template_name='demo_four.html'), name="demo-four"),
     url('^admin/', admin.site.urls),
     url('^django_plotly_dash/', include('django_plotly_dash.urls')),
+
+    url('^demo-session-var$', add_to_session, name="session-variable-example"),
 ]
 
 # Add in static routes so daphne can serve files; these should

django_plotly_dash/routing.py

@@ -29,11 +29,19 @@
 from django.conf.urls import url
 
 from .consumers import MessageConsumer, PokePipeConsumer
-from .util import pipe_ws_endpoint_name, http_endpoint
+from .util import pipe_ws_endpoint_name, http_endpoint, http_poke_endpoint_enabled
 
 # TODO document this and discuss embedding with other routes
+
+http_routes = [
+    ]
+
+if http_poke_endpoint_enabled():
+    http_routes.append(url(http_endpoint("poke"), PokePipeConsumer))
+
+http_routes.append(url("^", AsgiHandler)) # AsgiHandler is 'the normal Django view handlers'
+
 application = ProtocolTypeRouter({
     'websocket': AuthMiddlewareStack(URLRouter([url(pipe_ws_endpoint_name(), MessageConsumer),])),
-    'http': AuthMiddlewareStack(URLRouter([url(http_endpoint("poke"), PokePipeConsumer),
-                                           url("^", AsgiHandler),])), # AsgiHandler is 'the normal Django view handlers'
+    'http': AuthMiddlewareStack(URLRouter(http_routes)),
     })

django_plotly_dash/util.py

@@ -49,3 +49,7 @@ def insert_demo_migrations():
     'Check settings and report if objects for demo purposes should be inserted during migration'
 
     return _get_settings().get('insert_demo_migrations', False)
+
+def http_poke_endpoint_enabled():
+    'Return true if the http endpoint is enabled through the settings'
+    return _get_settings().get('http_poke_enabled', True)

django_plotly_dash/views.py

@@ -106,3 +106,18 @@ def component_suites(request, resource=None, component=None, **kwargs):
         redone_url = "/static/dash/%s/%s" %(component, resource)
 
     return HttpResponseRedirect(redirect_to=redone_url)
+
+
+# pylint: disable=wrong-import-position, wrong-import-order
+from django.template.response import TemplateResponse
+
+def add_to_session(request, template_name="index.html", **kwargs):
+    'Add some info to a session in a place that django-plotly-dash can pass to a callback'
+
+    django_plotly_dash = request.session.get("django_plotly_dash", dict())
+
+    session_add_count = django_plotly_dash.get('add_counter', 0)
+    django_plotly_dash['add_counter'] = session_add_count + 1
+    request.session['django_plotly_dash'] = django_plotly_dash
+
+    return TemplateResponse(request, template_name, {})

docs/configuration.rst

@@ -16,6 +16,9 @@ below.
       # Route used for direct http insertion of pipe messages
       "http_route" : "dpd/views",
 
+      # Flag controlling existince of http poke endpoint
+      "http_poke_enabled" : True,
+
       # Insert data for the demo when migrating
       "insert_demo_migrations" : False,
   }

docs/dash_components.rst

@@ -3,10 +3,39 @@
 Dash components
 ===============
 
-The ``dpd-components`` package contains ``Dash`` components.
+The ``dpd-components`` package contains ``Dash`` components. This package is installed as a
+dependency of ``django-plotly-dash``.
 
 .. _pipe_component:
 The ``Pipe`` component
 --------------
 
-Blah
+Each ``Pipe`` component instance listens for messages on a single channel. The ``value`` member of any message on that channel whose ``label`` matches
+that of the component will be used to update the ``value`` property of the component. This property can then be used in callbacks like
+any other ``Dash`` component property.
+
+An example, from the demo application:
+
+.. code-block:: python
+
+    import dpd_components as dpd
+
+    app.layout = html.Div([
+        ...
+        dpd.Pipe(id="named_count_pipe",               # ID in callback
+                 value=None,                          # Initial value prior to any message
+                 label="named_counts",                # Label used to identify relevant messages
+                 channel_name="live_button_counter"), # Channel whose messages are to be examined
+        ...
+        ])
+
+The ``value`` of the message is sent from the server to all front ends with ``Pipe`` components listening
+on the given ``channel_name``. This means that this part of the message should be small, and it must
+be JSON serialisable. Also, there is no guarantee that any callbacks will be executed in the same Python
+process as the one that initiated the initial message from server to front end.
+
+The ``Pipe`` properties can be persisted like any other ``DashApp`` instance, although it is unlikely
+that continued persistence of state on each update of this component is likely to be useful.
+
+This component requires a bidirectional connection, such as a websocket, to the server. Inserting
+a ``plotly_message_pipe`` :ref:`template tag <plotly_message_pipe>` is sufficient.