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 hatch dependency management system
  • Clone the pyobsplot repository
  • Install Python dependencies with : hatch shell
  • 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 creating your plot generator object:

op = Obsplot(render="widget", 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.

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 is correct
  • Change version in NEWS.md and src/pyobsplot/__about__.py
  • Release the Python package with hatch build and hatch publish in pyobsplot
  • 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 and update utils.py in pyobsplot