Setting up scikit-plots for development#

Template

Template for further usage, template belong to matplotlib.

To set up scikit-plots for development follow these steps:

Fork the scikit-plots repository#

scikit-plots is hosted at scikit-plots/scikit-plots.git. If you plan on solving issues or submitting pull requests to the main scikit-plots repository, you should first fork this repository by clicking the Fork button near the top of the project repository page.

This creates a copy of the code under your account on the GitHub server. See the GitHub documentation for more details.

Retrieve the latest version of the code#

Now that your fork of the repository lives under your GitHub username, you can retrieve the most recent version of the source code with one of the following commands (replace <your-username> with your GitHub username):

git clone https://github.com/<your-username>/scikit-plots.git

git clone git@github.com:<your-username>/scikit-plots.git

This requires you to setup an SSH key in advance, but saves you from typing your password at every connection.

This will place the sources in a directory scikit-plots below your current working directory and set the remote name origin to point to your fork. Change into this directory before continuing:

cd scikit-plots

Now set the remote name upstream to point to the scikit-plots main repository:

git remote add upstream https://github.com/scikit-plots/scikit-plots.git

git remote add upstream git@github.com:scikit-plots/scikit-plots.git

You can now use upstream to retrieve the most current snapshot of the source code, as described in Development workflow.

Additional git and GitHub resources#

For more information on git and GitHub, see:

Create a dedicated environment#

You should set up a dedicated environment to decouple your scikit-plots development from other Python and scikit-plots installations on your system.

We recommend using one of the following options for a dedicated development environment because these options are configured to install the Python dependencies as part of their setup.

Create a new venv environment with

python -m venv <file folder location>

and activate it with one of the following

source <file folder location>/bin/activate  # Linux/macOS
<file folder location>\Scripts\activate.bat  # Windows cmd.exe
<file folder location>\Scripts\Activate.ps1  # Windows PowerShell

On some systems, you may need to type python3 instead of python. For a discussion of the technical reasons, see PEP-394.

Install the Python dependencies with

pip install -r requirements/dev/dev-requirements.txt

Remember to activate the environment whenever you start working on scikit-plots!

Create a new conda environment and install the Python dependencies with

conda env create -f environment.yml

You can use mamba instead of conda in the above command if you have mamba installed.

Activate the environment using

conda activate mpl-dev

Remember to activate the environment whenever you start working on scikit-plots!

GitHub Codespaces is a cloud-based in-browser development environment that comes with the appropriate setup to contribute to scikit-plots.

  1. Open codespaces on your fork by clicking on the green Code button on the GitHub web interface and selecting the Codespaces tab.

  2. Next, click on “Open codespaces on <your branch name>”. You will be able to change branches later, so you can select the default main branch.

  3. After the codespace is created, you will be taken to a new browser tab where you can use the terminal to activate a pre-defined conda environment called mpl-dev:

    conda activate mpl-dev

Remember to activate the mpl-dev environment whenever you start working on scikit-plots.

If you need to open a GUI window with scikit-plots output on Codespaces, our configuration includes a light-weight Fluxbox-based desktop. You can use it by connecting to this desktop via your web browser. To do this:

  1. Press F1 or Ctrl/Cmd+Shift+P and select Ports: Focus on Ports View in the VSCode session to bring it into focus. Open the ports view in your tool, select the noVNC port, and click the Globe icon.

  2. In the browser that appears, click the Connect button and enter the desktop password (vscode by default).

Check the GitHub instructions for more details on connecting to the desktop.

If you also built the documentation pages, you can view them using Codespaces. Use the “Extensions” icon in the activity bar to install the “Live Server” extension. Locate the doc/build/html folder in the Explorer, right click the file you want to open and select “Open with Live Server.”

Install external dependencies#

Python dependencies were installed as part of setting up the environment. Additionally, the following non-Python dependencies must also be installed locally:

For a full list of dependencies, see Dependencies. External dependencies do not need to be installed when working in codespaces.

Install scikit-plots in editable mode#

Install scikit-plots in editable mode from the scikit-plots directory using the command

python -m pip install --verbose --no-build-isolation --editable ".[dev]"

The ‘editable/develop mode’ builds everything and places links in your Python environment so that Python will be able to import scikit-plots from your development source directory. This allows you to import your modified version of scikit-plots without having to re-install after changing a .py or compiled extension file.

When working on a branch that does not have Meson enabled, meaning it does not have PR #26621 in its history (log), you will have to reinstall from source each time you change any compiled extension code.

If the installation is not working, please consult the troubleshooting guide. If the guide does not offer a solution, please reach out via chat or open an issue.

Build options#

If you are working heavily with files that need to be compiled, you may want to inspect the compilation log. This can be enabled by setting the environment variable MESONPY_EDITABLE_VERBOSE or by setting the editable-verbose config during installation

python -m pip install --no-build-isolation --config-settings=editable-verbose=true --editable .

For more information on installation and other configuration options, see the Meson Python editable installs guide.

For a list of the other environment variables you can set before install, see Environment variables.

Verify the Installation#

Run the following command to make sure you have correctly installed scikit-plots in editable mode. The command should be run when the virtual environment is activated:

python -c "import scikitplot; print(scikitplot.__file__)"

This command should return : <scikit-plots_local_repo>\scikitplot\__init__.py

We encourage you to run tests and build docs to verify that the code installed correctly and that the docs build cleanly, so that when you make code or document related changes you are aware of the existing issues beforehand.

Install pre-commit hooks#

pre-commit hooks save time in the review process by identifying issues with the code before a pull request is formally opened. Most hooks can also aide in fixing the errors, and the checks should have corresponding development workflow and pull request guidelines. Hooks are configured in .pre-commit-config.yaml and include checks for spelling and formatting, flake 8 conformity, accidentally committed files, import order, and incorrect branching.

Install pre-commit hooks

python -m pip install pre-commit
pre-commit install

Hooks are run automatically after the git commit stage of the editing workflow. When a hook has found and fixed an error in a file, that file must be staged and committed again.

Hooks can also be run manually. All the hooks can be run, in order as listed in .pre-commit-config.yaml, against the full codebase with

pre-commit run --all-files

To run a particular hook manually, run pre-commit run with the hook id

pre-commit run <hook id> --all-files

Please note that the mypy pre-commit hook cannot check the Type hints for new functions; instead the stubs for new functions are checked using the stubtest CI check and can be checked locally using tox -e stubtest.