nbappinator 0.2.0

Jupyter Notebook Application Builder

Introduction

nbappinator streamlines Jupyter and Voila app development through a structured, opinionated framework for UI construction. Adding a button to a tab is as simple as app.tab(0).button("Run", on_click=callback).

nbappinator has three goals:

• Simplify UI development for Notebook developers by reducing the surface area of APIs to learn.
• Abstract the underlying UI components, allowing nbappinator to plug in different frameworks to achieve equivalent behavior.
• Provide a foundation to develop reusable and portable themes to improve app styling.

Example

Getting Started

import nbappinator as nb

def my_action(app):
    with app.messages:
        print("This message will be written to the Messages footer")
        app.tab(0).label("This is some text")

def choose_action(app):
    with app.messages:
        chosen_value = app["choose1"]
        print(f"You chose {chosen_value}")
        app.tab(1).label(f"You chose {chosen_value}")

# Create a Tabbed UI comprised of three sections:
# "Config" Header, Tabbed Pages: "First Tab" and "Second Tab", and a "Messages" Footer
myapp = nb.App(tabs=["First Tab", "Second Tab"], footer="Messages", header="Config")
myapp.config.label("This is static text in the Config section. Add global settings, buttons and other widgets here.")

# Add a button to First Tab
myapp.tab(0).label("This is the first tab")
myapp.tab(0).button("but1", on_click=my_action, label="Some button")
myapp.tab(0).label("Click the button")

# Add a dropdown selection to Second Tab
myapp.tab(1).select("choose1", options=list(range(10)), on_change=choose_action, label="Choose A Number")

# Render the app:
myapp.display()

API Overview

Creating an App

app = nb.App(
    tabs=["Tab 1", "Tab 2"],  # Required: list of tab names
    header="Config",          # Optional: collapsible header section
    footer="Messages",        # Optional: collapsible footer (default)
    title="My App",           # Optional: browser title
)

Accessing Sections

app.config           # Header section (if configured)
app.tab(0)           # Tab by index
app.tab("Tab 1")     # Tab by name
app.footer           # Footer section
app.messages         # Output widget in footer for print statements

Input Widgets

All input widgets return the page for method chaining.

page.select("name", options=["a", "b"], default="a", on_change=callback)
page.combobox("name", options=["a", "b"])           # Select with text input
page.slider("name", min_val=0, max_val=100, default=50)
page.radio("name", options=["a", "b"], horizontal=True)
page.text("name", default="", multiline=False)
page.checkbox("name", default=False)
page.button("name", on_click=callback, status=True)  # status=True adds progress indicator

Display Widgets

page.label("Static text")
page.pre("Preformatted text")
page.html("<b>HTML content</b>")
page.separator(color="gray")
page.output("name")                # Output area for print statements

Data and Charts

page.dataframe("name", df, on_click=callback, tree=True, tree_column="path")
page.plotly(fig)
page.matplotlib(fig)
page.networkx(graph, layout="force")   # D3 force-directed graph
page.tree("name", paths=["a~b~c"], delimiter="~")

Layout

row = page.row()       # Horizontal container
row.button(...)
col = page.column()    # Vertical container

Callbacks

Callbacks receive the app as their only argument:

def my_callback(app):
    value = app["widget_name"]       # Get widget value
    app["widget_name"] = new_value   # Set widget value
    app.status("Working...")         # Update button status
    app.done("Complete")             # Mark button as done

Button with Status

app.config.button("Run", on_click=run_task, status=True)

def run_task(app):
    app.status("Loading data...")
    # ... do work ...
    app.status("Processing...")
    # ... more work ...
    app.done("Complete")

Deployment and BQuant

nbappinator was originally designed to simplify developing applications within Bloomberg's BQuant environment, which provides a managed but locked down Jupyter environment with a Voila-based deployment of applications.

Acknowledgements

nbappinator builds on some great projects that provide useful building blocks in Jupyter, which themselves build on other great web technologies. At the same time, nbappinator is implementation agnostic - a core goal is to allow any of these components to be swapped out.

ipyvuetify provides the underlying UI widgets, bringing modern VUE components to Jupyter.

AG Grid is an excellent javascript grid library, which ipyaggrid provides as a Jupyter extension.

Plotly is given first class support, although any matplotlib charting library works, such as Seaborn.

D3.js powers the interactive NetworkX graph visualizations with force-directed layouts.

This all builds on Jupyter and ipywidgets.

Testing Notes

A significant portion of the tests are Notebook smoketests designed to exercise the code base in its entirety. The coverage report primarily reflects the percentage of the code base that the Notebooks exercise: but manual verification of the Notebook behavior is still required.

Some assertions are baked into the Notebooks, but largely its intended to ensure that all the features are exercised.