Add optional dependencies (#4480)

* Add optional dependencies

See #2888

Criteria for inclusion:
- Mentioned in https://xarray.pydata.org/en/stable/installing.html#optional-dependencies
- Listed in PyPI
- Should not fail during build (due to build dependencies or external libraries)

* Update what's new doc

* Document installation with extras

* Apply suggestions on documenting opt dependencies

Co-authored-by: Mathias Hauser <[email protected]>

* Include netCDF4 to io extras

* Mention that extra dep are specified in setup.cfg

* Remove dummy dependency iris. Add extras docs.

  pip install -e '.[docs]'

installs all the extra packages required to generate
the documentation from source.

* Literal include extras_require snippet

* Modify extras as suggested by @keewis

* Rm pyke, add dask[complete] and other docs deps

* Apply suggestions from code review

Co-authored-by: Mathias Hauser <[email protected]>

* Update doc/installing.rst

* Update doc/whats-new.rst

Co-authored-by: Mathias Hauser <[email protected]>
Co-authored-by: Deepak Cherian <[email protected]>

Author: 3 people

doc/installing.rst

@@ -16,6 +16,12 @@ Required dependencies
 Optional dependencies
 ---------------------
 
+.. note::
+
+  If you are using pip to install xarray, optional dependencies can be installed by
+  specifying *extras*. :ref:`installation-instructions` for both pip and conda
+  are given below.
+
 For netCDF and IO
 ~~~~~~~~~~~~~~~~~
 
@@ -116,6 +122,7 @@ You can see the actual minimum tested versions:
 - `For everything else
   <https://github.com/pydata/xarray/blob/master/ci/requirements/py36-min-all-deps.yml>`_
 
+.. _installation-instructions:
 
 Instructions
 ------------
@@ -139,6 +146,26 @@ pandas) installed first. Then, install xarray with pip::
 
     $ pip install xarray
 
+We also maintain other dependency sets for different subsets of functionality::
+
+    $ pip install "xarray[io]"        # Install optional dependencies for handling I/O
+    $ pip install "xarray[accel]"     # Install optional dependencies for accelerating xarray
+    $ pip install "xarray[parallel]"  # Install optional dependencies for dask arrays
+    $ pip install "xarray[viz]"       # Install optional dependencies for visualization
+    $ pip install "xarray[complete]"  # Install all the above
+
+The above commands should install most of the `optional dependencies`_. However,
+some packages which are either not listed on PyPI or require extra
+installation steps are excluded. To know which dependencies would be
+installed, take a look at the ``[options.extras_require]`` section in
+``setup.cfg``:
+
+.. literalinclude:: ../setup.cfg
+   :language: ini
+   :start-at: [options.extras_require]
+   :end-before: [options.package_data]
+
+
 Testing
 -------
 

doc/whats-new.rst

@@ -56,6 +56,15 @@ Documentation
 
 Internal Changes
 ~~~~~~~~~~~~~~~~
+
+- Optional dependencies can be installed along with xarray by specifying
+  extras as ``pip install "xarray[extra]"`` where ``extra`` can be one of ``io``,
+  ``accel``, ``parallel``, ``viz`` and ``complete``. See docs for updated
+  :ref:`installation instructions <installation-instructions>`.
+  (:issue:`2888`, :pull:`4480`).
+  By `Ashwin Vishnu <https://github.com/ashwinvis>`_, `Justus Magin
+  <https://github.com/keewis>`_ and `Mathias Hauser
+  <https://github.com/mathause>`_.
 - Removed stray spaces that stem from black removing new lines (:pull:`4504`).
   By `Mathias Hauser <https://github.com/mathause>`_.
 

setup.cfg

@@ -81,6 +81,52 @@ setup_requires =
     setuptools >= 38.4
     setuptools_scm
 
+[options.extras_require]
+io =
+    netCDF4
+    h5netcdf
+    scipy
+    pydap
+    zarr
+    fsspec
+    cftime
+    rasterio
+    cfgrib
+    ## Scitools packages & dependencies (e.g: cartopy, cf-units) can be hard to install
+    # scitools-iris
+
+accel =
+    scipy
+    bottleneck
+    numbagg
+
+parallel =
+    dask[complete]
+
+viz =
+    matplotlib
+    seaborn
+    nc-time-axis
+    ## Cartopy requires 3rd party libraries and only provides source distributions
+    ## See: https://github.com/SciTools/cartopy/issues/805
+    # cartopy
+
+complete =
+    %(io)s
+    %(accel)s
+    %(parallel)s
+    %(viz)s
+
+docs =
+    %(complete)s
+    sphinx-autosummary-accessors
+    sphinx_rtd_theme
+    ipython
+    ipykernel
+    jupyter-client
+    nbsphinx
+    scanpydoc
+
 [options.package_data]
 xarray =
     py.typed