Development

Install from git

To install pyobsplot from git:

pip install git+https://github.com/juba/pyobsplot.git

To install pyobsplot npm package from git:

npm install 'https://gitpkg.now.sh/juba/pyobsplot/packages/pyobsplot-js?main'

Install fom source

If you want to build pyobsplot from source, you’ll have to follow these steps:

  • Install node.js
  • Install uv dependency management system
  • Clone the pyobsplot repository
  • Install Python and Python dependencies with : uv sync
  • Install pyobsplot-js JavaScript dependencies with : npm install --workspaces
  • Install pyobsplot dependencies with : npm install

The widget renderer uses the anywidget Jupyter widget framework. Python source code is in src/pyobsplot/widget.py. JavaScript and CSS source code are in js/ and css/.

The jsdom renderer is provided by the pyobsplot-js npm package whose source is in packages/pyobsplot-js. Python source code is in src/pyobsplot/jsdom.py.

Widget JavaScript modification and bundling

Each time the widget JavaScript or CSS code is modified in the js/ or css/ directories, it must be bundled with one of the following commands in pyobsplot:

# Bundle only once
npm run bundle
# Bundle and watch for code change
npm run watch

The result is put into src/pyobsplot/static.

Tests

pyobsplot comes with three types of tests : Python test, JavaScript tests and Visual regression tests.

To run Python tests, use:

npm run test

To run JavaScript tests, use:

npm run test --workspaces

Visual regression tests allow to test if generated plots stay the same. They use the galata framework. To run them you first have to start a specific Jupyter instance with:

npm run uistart

If you use visual regression tests for the first time, you have to generate reference images with:

# Create / update reference images
npm run uitest:update

After that, you can test that currently generated images are the same as the reference one with:

# Compare with reference images
npm run uitest

Debug mode

“Debug mode” outputs the computed JavaScript plot structure (the one passed to Plot.plot).

To activate it, add debug=True when using Plot.plot() or when creating your plot generator object:

op = Obsplot(debug=True)

If using the widget renderer, debug output will be displayed in JavaScript console. With the jsdom renderer, it will be displayed directly in the notebook.

Documentation

To generate the documentation with Quarto:

uv run quarto render doc/

Maintenance notes

Releases

  • If necessary release the npm package with npm publish in packages/pyobsplot-js
  • Check that the min_npm_version value in utils.py is correct
  • Change version in NEWS.md and pyproject.toml
  • Build the Python package with npm run build
  • Release the Python package with uvx twine upload dist/pyobsplot-0.X.Y*
  • Tag the version in git
  • Create a release on Github
  • Bump to dev version in pyproject.toml and NEWS.md

New Plot versions

When a new Plot version is released:

  • update with npm install @observablehq/plot d3 --workspaces --include-workspace-root
  • run utils/get_plot_methods.js to update Plot methods in src/pyobsplot/plot.py