Metadata-Version: 2.4
Name: nbappinator
Version: 0.2.0
Summary: Jupyter Notebook Application Builder
Project-URL: Homepage, https://github.com/iqmo-org/nbappinator
Project-URL: Repository, https://github.com/iqmo-org/nbappinator
Project-URL: Issues, https://github.com/iqmo-org/nbappinator/issues
Author-email: Paul T <paul@iqmo.com>
Maintainer-email: Paul T <paul@iqmo.com>
License-Expression: BSD-3-Clause
License-File: LICENSE.md
Keywords: Bquant,Jupyter,nbappinator
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: anywidget>=0.9.0
Requires-Dist: ipyaggrid>=0.5.4
Requires-Dist: ipytree>=0.2.2
Requires-Dist: ipyvuetify>=1.9.4
Requires-Dist: ipywidgets>=8.1.3
Requires-Dist: pandas>=2.2.2
Requires-Dist: plotly>=5.22.0
Description-Content-Type: text/markdown

[![PyPI Version](https://badge.fury.io/py/nbappinator.svg)](https://pypi.python.org/pypi/nbappinator)
[![Anaconda-Server Badge](https://anaconda.org/conda-forge/nbappinator/badges/version.svg)](https://anaconda.org/conda-forge/nbappinator)
[![Tests](https://github.com/iqmo-org/nbappinator/actions/workflows/build_release.yml/badge.svg)](https://github.com/iqmo-org/nbappinator/actions/workflows/build_release.yml)
[![Tests](https://github.com/iqmo-org/nbappinator/actions/workflows/test_coverage.yml/badge.svg)](https://github.com/iqmo-org/nbappinator/actions/workflows/test_coverage.yml)

<!--[![Coverage badge](https://raw.githubusercontent.com/iqmo-org/nbappinator/python-coverage-comment-action-data/badge.svg)](https://htmlpreview.github.io/?https://github.com/iqmo-org/nbappinator/blob/python-coverage-comment-action-data/htmlcov/index.html)-->

[![Coverage badge2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/iqmo-org/nbappinator/python-coverage-comment-action-data/endpoint.json)](https://htmlpreview.github.io/?https://github.com/iqmo-org/nbappinator/blob/python-coverage-comment-action-data/htmlcov/index.html)

# 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

<!--![Example](readme_example.png)-->

# Getting Started

```py
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

```py
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

```py
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.

```py
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

```py
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

```py
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

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

### Callbacks

Callbacks receive the app as their only argument:

```py
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

```py
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](https://ipyvuetify.readthedocs.io/en/latest/) provides the underlying UI widgets, bringing modern VUE components to Jupyter.

[AG Grid](https://ag-grid.com/) is an excellent javascript grid library, which [ipyaggrid](https://github.com/widgetti/ipyaggrid) provides as a Jupyter extension.

[Plotly](https://plotly.com/) is given first class support, although any matplotlib charting library works, such as Seaborn.

[D3.js](https://d3js.org/) powers the interactive NetworkX graph visualizations with force-directed layouts.

This all builds on [Jupyter](https://jupyter.org/) and [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/).

# 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.
