Developing ITables#
In this page you will find instructions on how to create a development environment and how to test your changes.
How to create a development environment#
This project uses pixi for dependency management. First, install pixi>=0.60.0 by following the instructions at https://pixi.sh.
Then, activate ITables’ development environment with:
pixi shell
Install the pre-commit hooks with
pre-commit install
How to run the Python test suite#
The Python code can be tested with just
pytest
Running the pytest test suite is not enough to guarantee that a change won’t
break itables. You also need to test that the tables are well rendered in the
different contexts like Jupyter Book, Jupyter Lab, VS Code.
Browser-based (Playwright) tests#
A few regressions (e.g. dark mode issues) can only be caught by actually
rendering a table in a browser and inspecting the resulting DOM/CSS. These
tests live under tests/playwright/ and are skipped when Playwright and its
browser binaries are not installed, since they are not part of the standard
test dependencies. Run them locally with the dedicated playwright pixi
environment:
pixi run -e playwright playwright install chromium
pixi run -e playwright pytest tests/playwright
This environment has its own CI job (pytest-playwright), so these tests do
run on every push and pull request, in addition to being run locally
whenever you touch the dark-mode or FixedColumns related CSS/JS.
Reproducing Quarto-specific issues#
Quarto’s Bootstrap-based HTML theme can interact with the ColumnControl
CSS in ways that a plain notebook render won’t reveal (see #536). Render
docs/quarto/quarto_column_control.qmd with the dedicated quarto pixi
environment to reproduce and check such issues:
pixi run -e quarto quarto render docs/quarto/quarto_column_control.qmd
How to build the package locally#
Build both the wheel and source distribution with:
pixi run -e build hatch build
The build artifacts are created in dist/.
This uses the dedicated build pixi environment, which pins hatch and
virtualenv to versions that are currently compatible with the
jupyter-builder build hook.
Jupyter Book#
The itables documentation uses Jupyter Book.
Build the documentation with:
pixi run -e docs jupyter book build docs
This will give you a link to a local version of the documentation.
If you make any significant change then you should go through the updated documentation and make sure all the examples still work properly.
Jupyter Lab#
In the pixi environment, you can start Jupyter with
pixi run jupyter lab
or if you’re already in a pixi shell:
jupyter lab
You should test at least this code snippet:
import itables
# try both connected=False (the default) and connected=True
itables.init_notebook_mode(connected=False)
itables.sample_dfs.get_countries(html=True)
You can do this using for instance the notebook at tests/test_notebook.ipynb.
Note that you can also open the documentation in Jupyter:
go to the docs folder and open any .md file as a notebook (using a right click).
Other notebook editors#
If you change anything related to the Javascript/HTML code, you should test the supported editors in both the connected and offline mode.
For the online editors like Google Colab, you might have to install your development version there with e.g.
!pip uninstall itables -y
!pip install git+https://github.com/mwouts/itables.git@branch