Split optional dependencies in pyproject.toml

docs/installation.md

@@ -12,16 +12,43 @@ and on conda-forge:
 conda install -c conda-forge virtualizarr
 ```
 
+## Optional dependencies
+
+VirtualiZarr has many optional dependencies, split into those for reading various file formats, and those for writing virtual references out to different formats.
+
+Optional dependencies can be installed in groups via pip. For example to read HDF files and write virtual references to icechunk you could install all necessary dependencies via:
+
+```shell
+pip install "virtualizarr[hdf, icechunk]"
+```
+
+The full list of optional dependencies can be seen in the `pyproject.toml` file:
+
+```{literalinclude} ../pyproject.toml
+:start-at: "[project.optional-dependencies]"
+:end-before: "test ="
+```
+
+The compound groups allow you to install multiple sets of dependencies at once, e.g. install every file reader via
+
+```shell
+pip install "virtualizarr[all_readers]"
+```
+
+The basic `pip install virtualizarr` will only install the minimal required dependencies, and so may not be particularly useful on its own.
 
 ## Install Test Dependencies
 
+For local development you will want to install the test dependencies so that you can run all the tests in the test suite:
+
 ```shell
 pip install '-e .[test]'
 ```
 
-
 ## Install Docs Dependencies
 
+To build the documentation locally you will need further dependencies:
+
 ```shell
 pip install '-e .[docs]'
 ```

docs/releases.rst

@@ -9,6 +9,8 @@ v1.1.1 (unreleased)
 New Features
 ~~~~~~~~~~~~
 
+- Optional dependencies can now be installed in groups via pip. See the installation docs.
+  (:pull:`309`) By `Tom Nicholas <https://github.com/TomNicholas>`_.
 - Add a ``virtual_backend_kwargs`` keyword argument to file readers and to ``open_virtual_dataset``, to allow reader-specific options to be passed down.
   (:pull:`315`) By `Tom Nicholas <https://github.com/TomNicholas>`_.
 

pyproject.toml

@@ -23,30 +23,65 @@ dynamic = ["version"]
 dependencies = [
     "xarray>=2024.10.0",
     "numpy>=2.0.0",
-    "packaging",
     "universal-pathlib",
     "numcodecs",
     "ujson",
+    "packaging",
 ]
 
 [project.optional-dependencies]
-hdf_reader = [
+# non-kerchunk-based readers
+hdf = [
     "fsspec",
     "h5py",
     "hdf5plugin",
     "imagecodecs",
     "imagecodecs-numcodecs==2024.6.1",
-    "numcodecs"
+]
+# kerchunk-based readers
+hdf5 = [
+    "kerchunk>=0.25.0",
+    "h5py",
+]
+netcdf3 = [
+    "kerchunk>=0.25.0",
+    "scipy",
+]
+fits = [
+    "kerchunk>=0.25.0",
+    "astropy",
+]
+# un-implemented readers
+# tiff = [
+#     "kerchunk>=0.25.0",
+#     "tifffile",
+# ]
+# grib = ["kerchunk>=0.25.0"]
+# zarr = ["zarr==3.0.0b2"]
+all_readers = [
+    "virtualizarr[hdf]",
+    "virtualizarr[hdf5]",
+    "virtualizarr[netcdf3]",
+    "virtualizarr[fits]",
+#    "virtualizarr[tiff]",
+#    "virtualizarr[grib]",
+#    "virtualizarr[zarr]",
+]
+# writers
+icechunk = ["icechunk"]
+# technically also a reader, as fastparquet is also required to read parquet-formatted kerchunk references
+kerchunk = ["fastparquet"]
+all_writers = [
+    "virtualizarr[icechunk]",
+    "virtualizarr[kerchunk]",
+]
+all = [
+    "virtualizarr[all_readers]",
+    "virtualizarr[all_writers]",
 ]
 test = [
     "codecov",
-    "fastparquet",
-    "fsspec",
-    "h5py",
-    "kerchunk>=0.2.5",
     "mypy",
-    "netcdf4",
-    "numcodecs",
     "pandas-stubs",
     "pooch",
     "pre-commit",
@@ -55,8 +90,7 @@ test = [
     "pytest",
     "ruff",
     "s3fs",
-    "scipy",
-    "virtualizarr[hdf_reader]"
+    "virtualizarr[all]"
 ]
 
 [project.urls]