Skip to content

MaayanLab/appyter

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Jul 2, 2024
8bfdf91 · Jul 2, 2024
Feb 14, 2022
Jul 2, 2024
Apr 6, 2022
May 31, 2022
Jun 15, 2022
Mar 25, 2022
Dec 4, 2020
Jun 2, 2023
Mar 5, 2024
Sep 22, 2020
Mar 8, 2022
Jan 31, 2023
Sep 1, 2021

Repository files navigation

Appyter

This module enables you to turn your jupyter notebook into a jinja2 template-driven web application. Or just parse for other purposes.

Installation

NOTE: This application uses modern python features including async await (3.5) and fstrings (3.6), to ensure you have the best experience please use python >= 3.8.

# Install package from pip
pip3 install --upgrade appyter

# OR Install package from github repository main
pip3 install --upgrade git+https://github.com/Maayanlab/appyter.git

Usage

Appyter enables you to serve that notebook on an executable webapp.

appyter jupyter_notebook.ipynb

If for some reason, appyter doesn't end up discoverable in your PATH, you can use python3 -m appyter instead.

  • A dotenv file (.env) or environment variables can be use to configure HOST (APPYTER_HOST), PORT (APPYTER_PORT), and PREFIX (APPYTER_PREFIX) of the webserver.
  • Some pre-configured profiles can be used for styling the form (--profile=profile_name) see appyter/profiles
  • In debug mode (--debug), changes to the notebook will automatically update the webapp.
  • Custom fields can be used by putting them in the directory of execution with the following format:
    • ./fields/YourField.py: Python Field Implementation
  • The templates used natively by the application can be modified to provide your own look and feel:
    • ./templates/head.jinja2: Custom head (title, CSS, scripts)
    • ./templates/form.jinja2: Custom form handling
    • ./templates/fields/StringField.jinja2: Override field style
  • Custom jinja2 filters can be added if necessary
    • ./filters/your_filter.py: Python jinja2 filter (function)
  • Custom externally-referenced resources (i.e. images) can be put under the static directory
    • ./static/img/your_image.png: Reference in templates with {% static 'img/your_image.png' %}
  • Custom blueprints to additionally mount with flask
    • ./blueprints/your_app/__init__.py: your_app = Blueprint('your_app', __name__)

Creating an Appyter

Create a standard python jupyter notebook, make the first cell:

#%%appyter init
from appyter import magic
magic.init(lambda _=globals: _())

Normal cells are allowed, you also have access to jinja2-rendered cells:

%%appyter {cell_type}

Supported cell_types:

  • markdown: Substitute jinja2 template variables, render as a markdown cell
  • hide: Substitute jinja2 template variables, show it rendered in your notebook with the default values, but when executing publicly, don't show/execute the cell.
  • code_exec: Substitute jinja2 template variables, render as python, show it rendered in your notebook with the default values and execute it
  • code_eval: Substitute jinja2 template variables, render as python, show it rendered in your notebook with the default values and execute it, "eval" the last line of the cell and display the result.

Discussion

Consider the following notebook:

%%appyter markdown
# {{ StringField(name='title', label='Title', default='My Title').render_value }}

{{ TextField(name='description', label='Description', default='My description').render_value }}
%%appyter code_eval
{% set number_1 = IntField(name='number_1', label='First Number', min=0, max=10, default=5) %}
{% set number_2 = IntField(name='number_2', label='Second Number', min=0, max=10, default=5) %}
{% set op = ChoiceField(
  name='operator',
  label='Operator',
  choices={
    'add': '+',
    'subtract': '-',
    'multiply': '*',
    'divide': '/',
    'power': '**',
  },
  default='add',
) %}
answer = {{ number_1 }} {{ op }} {{ number_2 }}

This can be parsed in various ways:

# Parse variables alone
assert parse_variables(appyter) == {
  'number_1': IntField(name='number_1', label='First Number', min=0, max=10, default=5),
  'number_2': IntField(name='number_2', label='Second Number', min=0, max=10, default=5),
  'operator': ChoiceField(
    name='operator',
    label='Operator',
    choices={
      'add': '+',
      'subtract': '-',
      'multiply': '*',
      'divide': '/',
      'power': '**'
    },
    default='add'
  ),
}

# Render jupyter notebook with variables substituted
assert render_jupyter(appyter, {
  'title': 'Test',
  'description': '',
  'number_1': 0,
  'number_2': 5,
  'operator': 'subtract',
}) == '''
---
# Test

---
answer = 0 - 5
---
''' # in valid ipynb syntax

# Render web UI
assert render_html(appyter) == '''
<form id="notebook">
  Title: <input type="string" name="title"></input>
  Description: <textarea name="description"></textarea>
  First Number: <input type="number" name="number_1" min=0 max=10></input>
  Second Number: <input type="number" name="number_2" min=0 max=10></input>
  Operator: <select name="operator">
    <option value="add">add</option>
    <option value="subtract">subtract</option>
    <option value="divide">divide</option>
    <option value="power">power</option>
  </select>
  <input type="submit" text="Submit"></input>
</form>
<script src="./appyter.js"></script>
<script>
  document.getElementById("notebook").on('submit', appyter.submit)
</script>
'''

# Web UI Renderer
assert render_html_renderer(appyter, {
  'title': 'Test',
  'description': '',
  'number_1': 0,
  'number_2': 5,
  'operator': 'subtract',
}) == '''
<div id="notebook"></div>
<script src="./appyter.js"></script>
<script>
  document.on('load', function () {
    appyter.render(
      document.getElementById("notebook"),
      {
        "title": "Test",
        "description": "",
        "number_1": 0,
        "number_2": 5,
        "operator": "subtract",
      }
    )
  })
</script>
'''

appyter can be used to get these conversions, it can also be used to host standalone webapps using these mechanisms.

Development

Testing

pytest is used for python testing. It can be invoked as follows:

# it is also prudent to test other protocols such as s3 (production) & sbfs (CAVATICA)
export FSSPEC_URI='memory://'
pytest --log-cli-level=DEBUG appyter