App introduction

The app module implements the connection between Python and JavaScript.

It implements a simple server based on Tornado. HTML is served to provide the client with the JavaScript and CSS, but once connected, all communication goed via a websocket.

A central component is the Model class, which allows definition of objects that have both a Python and JavaScript representation, forming a basis for model-view-like systems.

Some background info on the server process

Each server process hosts on a single URL (domain+port), but can serve multiple applications (via different paths). Each process uses one tornado IOLoop, and exactly one Tornado Application object.


A Model class can be made into an application by decorating it with app.serve. This registers the application, so that clients can connect to the app based on its name. One instance of this class is instantiated per connection. Multiple apps can be hosted from the same process simply be specifying more app classes. To connect to the application corresponding to the MyApp class, one should connect to “http://domain:port/MyApp”.

An app can also be launched (via app.launch()), which will invoke a client webruntime which is connected to the returned app object. This is the intended way to launch desktop-like apps. An app can also be exported to HTML via app.export().

Starting the server

Use start() to enter the mainloop for the server. For desktop applications you can use run(), which does what start() does, except the main loop exits when there are no more connections (i.e. the server stops when the window is closed).

In the notebook

In the IPython/Jupyter notebook, the user needs to run init_notebook() which will inject JS and CSS into the browser. Simple widgets (e.g. buttons) will display just fine, but for other widgets you might want to use SomeWidget(style='height:300px') to specify its size.