Developer Guide#

Set up #

The hvPlot library is a complex project which provides a wide range of data interfaces and an extensible set of plotting backends, which means the development and testing process involves a wide set of libraries.

If you have any problems with the steps here, please contact the developers on Discord.

Preliminaries #

Git #

The hvPlot source code is stored in a Git source control repository. The first step to working on hvPlot is to install Git on to your system. There are different ways to do this depending on whether, you are using Windows, OSX, or Linux.

To install Git on any platform, refer to the Installing Git section of the Pro Git Book.

Conda (optional)#

Developing hvPlot requires a wide range of dependencies that can all be installed with the conda package manager. Using conda is sometimes the easiest way to install a dependency (e.g. graphviz, Firefox drivers). However, these days most of the dependencies required to develop hvPlot can be installed with pip.

Follow these instructions to download conda.

Cloning the Repository #

The source code for the hvPlot project is hosted on GitHub. To clone the source repository, issue the following command:

git clone https://github.com/holoviz/hvplot.git

This will create a hvplot directory at your file system location. This hvplot directory is referred to as the source checkout for the remainder of this document.

Installing Dependencies #

hvPlot requires many additional packages for development and testing.

pip

Start by creating a virtual environment with venv:

python -m venv .venv

Activate it:

# Linux/MacOs
source .venv/bin/activate
# Windows
.venv\Scripts\activate

Install the test dependencies:

pip install -e '.[tests, examples-tests, geo, hvdev, hvdev-geo, dev-extras]'

conda

Create a development conda environment using one of the environment files present in the ./envs folder, and activate it:

conda env create --file envs/py3.10-tests.yaml
conda activate hvplottests

Setting up pre-commit #

hvPlot uses pre-commit to automatically apply linting to hvPlot code. If you intend to contribute to hvPlot we recommend you enable it with:

pre-commit install

This will ensure that every time you make a commit linting will automatically be applied.

Testing #

This chapter describes how to run various tests locally in a development environment, guidelines for writing tests, and information regarding the continuous testing infrastructure.

Running Tests Locally #

Before attempting to run hvPlot tests, make sure you have successfully run through all of the instructions in the Developer Guide section of the Developer’s Guide.

Currently hvPlot uses linting two types of tests: regular unit tests which are run with pytest and notebook example tests run with pytest and nbval:

Run the unit tests with:

pytest hvplot
pytest -v hvplot --geo  # include the test that require geo dependencies

Run the example tests with:

pytest -n auto --dist loadscope --nbval-lax -p no:python

Writing Tests #

In order to help keep hvPlot maintainable, all Pull Requests that touch code should normally be accompanied by relevant tests. While exceptions may be made for specific circumstances, the default assumption should be that a Pull Request without tests may not be merged.

Python unit tests maintain the basic functionality of the Python portion of the hvPlot library. A few general guidelines will help you write Python unit tests:

In order to ensure that hvPlot’s unit tests as relocatable and unambiguous as possible, always prefer absolute imports in test files. When convenient, import and use the entire module under test:

Good: import hvplot.pandas
Good: from hvplot.plotting import HvPlotTabular
Bad: from ..plotting import HvPlotTabular

Continuous Integration (CI)#

Every push to the main branch or any Pull Request branch on GitHub automatically triggers a full test build on the Github Action continuous integration service. This is most often useful for running the full hvPlot test suite continuously, but also triggers automated scripts for publishing releases when a tagged branch is pushed.

When in doubt about what command to run, you can always inspect the Github workflow files in the ./github/workflows folder so see what commands are running on the CI.

Github Action provides a limited number free build workers to Open Source projects. Please be considerate of others and group commits into meaningful chunks of work before pushing to GitHub (i.e. don’t push on every commit).