From 2928aa20a0ffa0947e7263c3ba069cee6fe24e5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20H=C3=B8xbro=20Hansen?= Date: Mon, 20 Jan 2025 18:31:11 +0100 Subject: [PATCH] enh(dev): Make default environment the developer environment (#6456) Co-authored-by: Maxime Liquet <35924738+maximlt@users.noreply.github.com> --- doc/developer_guide/index.md | 92 ++++++++++++++++++++----- pixi.toml | 130 ++++++++++++++++++++++------------- 2 files changed, 158 insertions(+), 64 deletions(-) diff --git a/doc/developer_guide/index.md b/doc/developer_guide/index.md index 6183017313..50f0517e6f 100644 --- a/doc/developer_guide/index.md +++ b/doc/developer_guide/index.md @@ -27,7 +27,9 @@ To contribute to HoloViews, you will also need [Github account](https://github.c ### Pixi -Developing all aspects of HoloViews requires a wide range of packages in different environments. To make this more manageable, Pixi manages the developer experience. To install Pixi, follow [this guide](https://pixi.sh/latest/#installation). +Developing all aspects of HoloViews requires a wide range of packages in different environments, but for new contributors the `default` environment will be more than enough. + +To make this more manageable, Pixi manages the developer experience. To install Pixi, follow [this guide](https://pixi.sh/latest/#installation). #### Glossary @@ -43,6 +45,7 @@ For more information, see the [Pixi documentation](https://pixi.sh/latest/). The first time you run `pixi`, it will create a `.pixi` directory in the source directory. This directory will contain all the files needed for the virtual environments. The `.pixi` directory can be large, so it is advised not to put the source directory into a cloud-synced directory. + ::: ## Installing the Project @@ -60,13 +63,30 @@ This `holoviews` directory is the _source checkout_ for the remainder of this do ## Start developing -To start developing, run the following command +To start developing, run the following command, this will create an environment called `default` and install HoloViews in [editable mode](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs): + +```bash +pixi run install +``` + +:::{admonition} Note +:class: info + +The first time you run it, it will create a `pixi.lock` file with information for all available environments. +This command will take a minute or so to run. + +::: +:::{admonition} Advanced usage +:class: tip + +Currently, an editable install needs to be run in each environment. So, if you want to install in the `test-core` environment, you can add `--environment` / `-e` to the command: ```bash -pixi install +pixi run -e test-core install ``` -The first time you run it, it will create a `pixi.lock` file with information for all available environments. This command will take a minute or so to run. +::: + When this is finished, it is possible to run the following command to download the data HoloViews tests and examples depend upon. ```bash @@ -85,24 +105,41 @@ Syncing the git tags can be done with: pixi run sync-git-tags ``` -### Editable install +## Developer Environment -It can be advantageous to install the HoloViews in [editable mode](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs): +The `default` environment is meant to provide all the tools needed to develop HoloViews. -```bash -pixi run install -``` +This environment can be created by running `pixi run install`, which will set up the environment and make an editable install of HoloViews. -:::{admonition} Note -:class: info +To activate this environment you can run `pixi shell`, this is equivalent to `source venv/bin/activate` in a virtual environment or `conda activate` in a conda environment. -Currently, this needs to be run for each environment. So, if you want to install in the `test-ui` environment, you can add `--environment` / `-e` to the command: +If you need to run a command directly instead of via `pixi`, you activate the environment and run your command (e.g. `pytest holoviews/tests/`). -```bash -pixi run -e test-ui install -``` +### VS Code -::: +This environment can also be selected in your IDE. In VS Code, this can be done by running the command `Python: Select Interpreter` and choosing `{'default': Pixi}`. + +

+ 001 + 002 +

+ +To confirm you are using this dev environment, check the bottom right corner: + +![003](https://assets.holoviews.org/static/dev_guide/003.png) + +### Jupyter Lab + +You can launch Jupyter lab with the `default` environment with `pixi run lab`. +This can be advantageous when you need to edit the documentation or debug an example notebook. ## Linting @@ -118,6 +155,18 @@ Linting can also be set up to run automatically with each commit; this is the re pixi run lint-install ``` +:::{admonition} Note +:class: info + +Alternatively, if you have `pre-commit` installed elsewhere you can run + +```bash +pre-commit install # To install +pre-commit run --all-files # To run on all files +``` + +::: + ## Testing To help keep HoloViews maintainable, all Pull Requests (PR) with code changes should typically be accompanied by relevant tests. While exceptions may be made for specific circumstances, the default assumption should be that a Pull Request without tests will not be merged. @@ -133,9 +182,18 @@ Unit tests can be run with the `test-unit` task: pixi run test-unit ``` +:::{admonition} Advanced usage +:class: tip + The task is available in the following environments: `test-39`, `test-310`, `test-311`, `test-312`, and `test-core`. Where the first ones have the same environments except for different Python versions, and `test-core` only has a core set of dependencies. -If you haven't set the environment flag in the command, a menu will help you select which one of the environments to use. +You can run the task in a specific environment with the `-e` flag. For example, to run the `test-unit` task in the `test-39` environment, you can run: + +```bash +pixi run -e test-39 test-unit +``` + +::: ### Example tests diff --git a/pixi.toml b/pixi.toml index 63ca5bfdae..387a20da30 100644 --- a/pixi.toml +++ b/pixi.toml @@ -3,28 +3,60 @@ name = "holoviews" channels = ["pyviz/label/dev", "bokeh/label/rc", "conda-forge"] platforms = ["linux-64", "osx-arm64", "osx-64", "win-64"] -[tasks] -check-latest-packages = 'python scripts/check_latest_packages.py' -download-data = 'python scripts/download_data.py' -install = 'python -m pip install --no-deps --disable-pip-version-check -e .' -sync-git-tags = 'python scripts/sync_git_tags.py holoviews' - -[activation.env] -PYTHONIOENCODING = "utf-8" - [environments] -test-39 = ["py39", "test-core", "test", "example", "test-example", "test-unit-task"] -test-310 = ["py310", "test-core", "test", "example", "test-example", "test-unit-task"] -test-311 = ["py311", "test-core", "test", "example", "test-example", "test-unit-task"] -test-312 = ["py312", "test-core", "test", "example", "test-example", "test-unit-task"] -test-ui = ["py312", "test-core", "test", "test-ui"] -test-core = ["py313", "test-core", "test-unit-task"] -test-gpu = ["py312", "test-core", "test", "test-gpu"] -docs = ["py311", "example", "doc"] -build = ["py311", "build"] -lint = ["py311", "lint"] - -[dependencies] +default = [ + "required", + "py312", + "optional", + "test-core", + "test-example", + "test-unit-task", + "test-ui", + "lint", + "dev", +] + +[environments.test-39] +features = ["required", "py39", "optional", "test-core", "test-example", "test-unit-task"] +no-default-feature = true + +[environments.test-310] +features = ["required", "py310", "optional", "test-core", "test-example", "test-unit-task"] +no-default-feature = true + +[environments.test-311] +features = ["required", "py311", "optional", "test-core", "test-example", "test-unit-task"] +no-default-feature = true + +[environments.test-312] +features = ["required", "py312", "optional", "test-core", "test-example", "test-unit-task"] +no-default-feature = true + +[environments.test-ui] +features = ["required", "py312", "optional", "test-core", "test-ui"] +no-default-feature = true + +[environments.test-core] +features = ["required", "py313", "test-core", "test-unit-task"] +no-default-feature = true + +[environments.test-gpu] +features = ["required", "py312", "test-core", "optional", "test-gpu"] +no-default-feature = true + +[environments.docs] +features = ["required", "py311", "optional", "doc"] +no-default-feature = true + +[environments.build] +features = ["required", "py311", "build"] +no-default-feature = true + +[environments.lint] +features = ["lint"] +no-default-feature = true + +[feature.required.dependencies] nomkl = "*" pip = "*" # Required @@ -37,6 +69,15 @@ panel = ">=1.0" param = ">=2.0,<3.0" pyviz_comms = ">=2.1" +[feature.required.tasks] +check-latest-packages = 'python scripts/check_latest_packages.py' +download-data = 'python scripts/download_data.py' +install = 'python -m pip install --no-deps --disable-pip-version-check -e .' +sync-git-tags = 'python scripts/sync_git_tags.py holoviews' + +[feature.required.activation.env] +PYTHONIOENCODING = "utf-8" + [feature.py39.dependencies] python = "3.9.*" panel = "1.4.*" @@ -63,13 +104,17 @@ bokeh_sampledata = "*" [feature.py313.activation.env] COVERAGE_CORE = "sysmon" -[feature.example.dependencies] +[feature.optional.dependencies] cftime = "*" +contourpy = "*" dask-core = "*" +dask-expr = "*" datashader = ">=0.11.1" ffmpeg = "*" +ibis-sqlite = "*" ipython = ">=5.4.0" matplotlib-base = ">=3" +nbconvert-core = "*" netcdf4 = "*" networkx = "*" notebook = "*" @@ -78,10 +123,24 @@ plotly = ">=4.0" pooch = "*" pyarrow = "*" scikit-image = "*" -scipy = "*" +scipy = ">=1.10" # Python 3.9 + Windows downloads 1.9 +selenium = "*" shapely = "*" +spatialpandas = "*" streamz = ">=0.5.0" xarray = ">=0.10.4" +xyzservices = "*" + +[feature.optional.target.unix.dependencies] +tsdownsample = "*" # currently not available on Windows + +[feature.dev.dependencies] +jupyterlab = "*" +jupyterlab-myst = "*" +setuptools_scm = "*" + +[feature.dev.tasks] +lab = 'jupyter lab' # ============================================= # =================== TESTS =================== @@ -95,32 +154,9 @@ pytest-github-actions-annotate-failures = "*" pytest-rerunfailures = "*" pytest-xdist = "*" -[feature.test-unit-task.tasks] # So it is not showing up in the test-ui environment +[feature.test-unit-task.tasks] # So it is not showing up in the test-gpu + test-ui environment test-unit = 'pytest holoviews/tests -n logical --dist loadgroup' -[feature.test.dependencies] -cftime = "*" -contourpy = "*" -dask-core = "*" -dask-expr = "*" -datashader = ">=0.11.1" -ffmpeg = "*" -ibis-sqlite = "*" -nbconvert = "*" -matplotlib-base = ">=3" -networkx = "*" -plotly = ">=4.0" -pillow = "*" -scipy = ">=1.10" # Python 3.9 + Windows downloads 1.9 -selenium = "*" -shapely = "*" -spatialpandas = "*" -xarray = ">=0.10.4" -xyzservices = "*" - -[feature.test.target.unix.dependencies] -tsdownsample = "*" # currently not available on Windows - [feature.test-example.tasks] test-example = { cmd = 'pytest -n logical --dist loadscope --nbval-lax examples', env = { DASK_DATAFRAME__QUERY_PLANNING = "False" } }