custom jupyter widgets made easy
Project description
anywidget 
custom jupyter widgets made easy
- 🛠️ create widgets without complicated cookiecutter templates
- 📚 publish to PyPI like any other Python package
- 🤖 prototype within
.ipynbor.pyfiles - 🚀 run in Jupyter, JupyterLab, Google Colab, VSCode, and more
- ⚡ develop with instant HMR, like modern web frameworks
Learn more in the announcement.
Installation
Warning: anywidget is new and under active development. It is not yet ready for production as APIs are subject to change.
anywidget is available on PyPI and
may be installed with pip:
pip install "anywidget[dev]"
It is also available on conda-forge. If you have Anaconda or Miniconda installed on your computer, you can install anywidget with the following command:
conda install -c conda-forge anywidget
Usage
import anywidget
import traitlets
class CounterWidget(anywidget.AnyWidget):
# Widget front-end JavaScript code
_esm = """
export function render({ model, el }) {
let getCount = () => model.get("count");
let button = document.createElement("button");
button.innerHTML = `count is ${getCount()}`;
button.addEventListener("click", () => {
model.set("count", getCount() + 1);
model.save_changes();
});
model.on("change:count", () => {
button.innerHTML = `count is ${getCount()}`;
});
el.appendChild(button);
}
"""
# Stateful property that can be accessed by JavaScript & Python
count = traitlets.Int(0).tag(sync=True)
Front-end code can also live in separate files (recommend):
import pathlib
import anywidget
import traitlets
class CounterWidget(anywidget.AnyWidget):
_esm = pathlib.Path("index.js")
_css = pathlib.Path("styles.css")
count = traitlets.Int(0).tag(sync=True)
Read the documentation to learn more.
Contributing
This is a monorepo, meaning the repo holds multiple packages. It requires the use of pnpm. You can install pnpm with:
npm i -g pnpm
Then, create a Python virtual environment with a complete development install:
pip install -e ".[dev,test]"
or alternatively use the hatch CLI:
hatch shell
If you are using the classic Jupyter Notebook you need to install the nbextension:
jupyter nbextension install --py --symlink --sys-prefix anywidget
jupyter nbextension enable --py --sys-prefix anywidget
Note for developers:
- the
-epip option allows one to modify the Python code in-place. Restart the kernel in order to see the changes. - the
--symlinkargument on Linux or OS X allows one to modify the JavaScript code in-place. This feature is not available with Windows.
For developing with JupyterLab:
jupyter labextension develop --overwrite anywidget
Sending PRs
Code styling
There are a few guidelines we follow:
- For JavaScript, internal variables are written with
snake_casewhile external APIs are written withcamelCase(if applicable). - For Python, ensure
black --check .andruff .pass. You can runblack .andruff --fix .to format and fix linting errors.
Generating changelogs
For changes to be reflected in package changelogs, run npx changeset and
follow the prompts.
Note not every PR requires a changeset. Since changesets are focused on releases and changelogs, changes to the repository that don't effect these won't need a changeset (e.g., documentation, tests).
Release
The Changesets GitHub action will create and update a PR that applies changesets and publishes new versions of anywidget to NPM and PyPI.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file anywidget-0.5.2.tar.gz.
File metadata
- Download URL: anywidget-0.5.2.tar.gz
- Upload date:
- Size: 3.0 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | ddc1255d1face1488c8d9deb2a84272d607ce3774236c83580637d9e664ccba3 |
|
| MD5 | 8970e7b75e6c8fc5789287a66e300223 |
|
| BLAKE2b-256 | 3c6acfbe944ecbd4913db4f2c26629942b4c0c21cdd6e2ec839ddd19bbe36e26 |
File details
Details for the file anywidget-0.5.2-py3-none-any.whl.
File metadata
- Download URL: anywidget-0.5.2-py3-none-any.whl
- Upload date:
- Size: 38.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 69f1c1bf046b4dce5625309a77cadaff72b967d446ea03fccba0e3c138d02582 |
|
| MD5 | ff040f3f76a1bd5d45d8b172001c3ccf |
|
| BLAKE2b-256 | dbcb87083f5710eb14f92cc4e7c68c7df02c874788cb3ccf399940b7ce95233c |
