Raise helpful error message when importing optional dependencies that are not installed.

[danschef]

Description

If cartopy is installed without optional dependencies, it would be nice to have a helpful error message when trying to use functions that depend on such libraries. Currently, just an ImportError is raised. It would be more useful to notify the user of the optional dependency (possibly including a documentation link).

Code to reproduce

from cartopy.crs import epsg
epsg(32633)

Traceback

ModuleNotFoundError                       Traceback (most recent call last)
<ipython-input-2-a9ebc24438bc> in <module>
----> 1 epsg(32633)

~/miniconda3/envs/spechomo/lib/python3.8/site-packages/cartopy/crs.py in epsg(code)
   2555     """
   2556     import cartopy._epsg
-> 2557     return cartopy._epsg._EPSGProjection(code)

~/miniconda3/envs/spechomo/lib/python3.8/site-packages/cartopy/_epsg.py in __init__(self, code)
     40 class _EPSGProjection(ccrs.Projection):
     41     def __init__(self, code):
---> 42         import pyepsg
     43         projection = pyepsg.get(code)
     44         if not (isinstance(projection, pyepsg.ProjectedCRS) or

ModuleNotFoundError: No module named 'pyepsg'

Full environment definition

Operating system

Linux-64

Cartopy version

cartopy 0.18.0 py38h88488af_4 conda-forge

conda list

_libgcc_mutex             0.1                 conda_forge    conda-forge
_openmp_mutex             4.5                       1_gnu    conda-forge
argon2-cffi               20.1.0           py38h1e0a361_2    conda-forge
async_generator           1.10                       py_0    conda-forge
attrs                     20.2.0             pyh9f0ad1d_0    conda-forge
backcall                  0.2.0              pyh9f0ad1d_0    conda-forge
backports                 1.0                        py_2    conda-forge
backports.functools_lru_cache 1.6.1                      py_0    conda-forge
bleach                    3.2.1              pyh9f0ad1d_0    conda-forge
blosc                     1.20.1               he1b5a44_0    conda-forge
boost-cpp                 1.74.0               h9359b55_0    conda-forge
branca                    0.4.1                      py_0    conda-forge
brotli                    1.0.9                he1b5a44_2    conda-forge
brotlipy                  0.7.0           py38h8df0ef7_1001    conda-forge
brunsli                   0.1                  he1b5a44_0    conda-forge
bzip2                     1.0.8                h516909a_3    conda-forge
c-ares                    1.16.1               h516909a_3    conda-forge
ca-certificates           2020.6.20            hecda079_0    conda-forge
cairo                     1.16.0            h488836b_1006    conda-forge
cartopy                   0.18.0           py38h88488af_4    conda-forge
certifi                   2020.6.20        py38h924ce5b_2    conda-forge
cffi                      1.14.3           py38h1bdcb99_1    conda-forge
cfitsio                   3.470                hce51eda_7    conda-forge
chardet                   3.0.4           py38h924ce5b_1008    conda-forge
charls                    2.1.0                he1b5a44_2    conda-forge
click                     7.1.2              pyh9f0ad1d_0    conda-forge
click-plugins             1.1.1                      py_0    conda-forge
cligj                     0.6.0              pyh9f0ad1d_0    conda-forge
cloudpickle               1.6.0                      py_0    conda-forge
cmocean                   2.0                      pypi_0    pypi
colorama                  0.4.4              pyh9f0ad1d_0    conda-forge
cryptography              3.1.1            py38hb23e4d4_1    conda-forge
curl                      7.71.1               he644dc0_8    conda-forge
cycler                    0.10.0                     py_2    conda-forge
cython                    0.29.21                  pypi_0    pypi
cytoolz                   0.11.0           py38h1e0a361_1    conda-forge
dask-core                 2.30.0                     py_0    conda-forge
decorator                 4.4.2                      py_0    conda-forge
defusedxml                0.6.0                      py_0    conda-forge
dill                      0.3.2              pyh9f0ad1d_0    conda-forge
entrypoints               0.3             py38h32f6830_1002    conda-forge
expat                     2.2.9                he1b5a44_2    conda-forge
fast-histogram            0.9                      pypi_0    pypi
fiona                     1.8.17           py38h676c6b2_1    conda-forge
folium                    0.11.0                     py_0    conda-forge
fontconfig                2.13.1            h1056068_1002    conda-forge
freetype                  2.10.3               he06d7ca_0    conda-forge
freexl                    1.0.5             h516909a_1002    conda-forge
future                    0.18.2                   pypi_0    pypi
gdal                      3.1.3            py38h9edfc58_1    conda-forge
geoarray                  0.10.0           py38h32f6830_0    conda-forge
geojson                   2.5.0                      py_0    conda-forge
geopandas                 0.8.1                      py_0    conda-forge
geos                      3.8.1                he1b5a44_0    conda-forge
geotiff                   1.6.0                h5d11630_3    conda-forge
gettext                   0.19.8.1          hf34092f_1003    conda-forge
giflib                    5.2.1                h516909a_2    conda-forge
gitdb                     4.0.5                      py_0    conda-forge
gitpython                 3.1.9                      py_0    conda-forge
glib                      2.66.1               he1b5a44_1    conda-forge
hdf4                      4.2.13            hf30be14_1003    conda-forge
hdf5                      1.10.6          nompi_h54c07f9_1110    conda-forge
icu                       67.1                 he1b5a44_0    conda-forge
idna                      2.10               pyh9f0ad1d_0    conda-forge
imagecodecs               2020.5.30        py38h63741c2_4    conda-forge
imageio                   2.9.0                      py_0    conda-forge
importlib-metadata        2.0.0                      py_1    conda-forge
importlib_metadata        2.0.0                         1    conda-forge
ipykernel                 5.3.4            py38h1cdfbd6_1    conda-forge
ipympl                    0.5.8              pyh9f0ad1d_0    conda-forge
ipython                   7.18.1           py38h1cdfbd6_1    conda-forge
ipython_genutils          0.2.0                      py_1    conda-forge
ipywidgets                7.5.1              pyh9f0ad1d_1    conda-forge
iso8601                   0.1.13                   pypi_0    pypi
jedi                      0.17.2           py38h32f6830_1    conda-forge
jinja2                    2.11.2             pyh9f0ad1d_0    conda-forge
joblib                    0.17.0                     py_0    conda-forge
jpeg                      9d                   h516909a_0    conda-forge
json-c                    0.13.1            hbfbb72e_1002    conda-forge
json5                     0.9.5              pyh9f0ad1d_0    conda-forge
jsonschema                3.2.0                      py_2    conda-forge
jupyter_client            6.1.7                      py_0    conda-forge
jupyter_core              4.6.3            py38h32f6830_2    conda-forge
jupyterlab                2.2.8                      py_0    conda-forge
jupyterlab-git            0.22.1                     py_0    conda-forge
jupyterlab_pygments       0.1.2              pyh9f0ad1d_0    conda-forge
jupyterlab_server         1.2.0                      py_0    conda-forge
jxrlib                    1.1                  h516909a_2    conda-forge
kealib                    1.4.13               h33137a7_1    conda-forge
kiwisolver                1.2.0            py38hbf85e49_1    conda-forge
krb5                      1.17.1               hfafb76e_3    conda-forge
lcms2                     2.11                 hbd6801e_0    conda-forge
ld_impl_linux-64          2.35                 h769bd43_9    conda-forge
lerc                      2.2                  he1b5a44_0    conda-forge
libaec                    1.0.4                he1b5a44_1    conda-forge
libblas                   3.8.0               17_openblas    conda-forge
libcblas                  3.8.0               17_openblas    conda-forge
libcurl                   7.71.1               hcdd3856_8    conda-forge
libdap4                   3.20.6               h1d1bd15_1    conda-forge
libedit                   3.1.20191231         he28a2e2_2    conda-forge
libev                     4.33                 h516909a_1    conda-forge
libffi                    3.2.1             he1b5a44_1007    conda-forge
libgcc-ng                 9.3.0               h5dbcf3e_17    conda-forge
libgdal                   3.1.3                h670eac6_1    conda-forge
libgfortran-ng            7.5.0               hae1eefd_17    conda-forge
libgfortran4              7.5.0               hae1eefd_17    conda-forge
libglib                   2.66.1               h0dae87d_1    conda-forge
libgomp                   9.3.0               h5dbcf3e_17    conda-forge
libiconv                  1.16                 h516909a_0    conda-forge
libkml                    1.3.0             h74f7ee3_1012    conda-forge
liblapack                 3.8.0               17_openblas    conda-forge
libnetcdf                 4.7.4           nompi_h84807e1_105    conda-forge
libnghttp2                1.41.0               h8cfc5f6_2    conda-forge
libopenblas               0.3.10               h5a2b251_0
libpng                    1.6.37               hed695b0_2    conda-forge
libpq                     12.3                 h5513abc_2    conda-forge
libsodium                 1.0.18               h516909a_1    conda-forge
libspatialindex           1.9.3                he1b5a44_3    conda-forge
libspatialite             5.0.0                h4dde289_0    conda-forge
libssh2                   1.9.0                hab1572f_5    conda-forge
libstdcxx-ng              9.3.0               h2ae2ef3_17    conda-forge
libtiff                   4.1.0                hc7e4089_6    conda-forge
libuuid                   2.32.1            h14c3975_1000    conda-forge
libuv                     1.40.0               hd18ef5c_0    conda-forge
libwebp-base              1.1.0                h516909a_3    conda-forge
libxcb                    1.13              h14c3975_1002    conda-forge
libxml2                   2.9.10               h68273f3_2    conda-forge
libzopfli                 1.0.3                he1b5a44_0    conda-forge
lxml                      4.6.1                    pypi_0    pypi
lz4-c                     1.9.2                he1b5a44_3    conda-forge
markupsafe                1.1.1            py38h8df0ef7_2    conda-forge
matplotlib-base           3.3.2            py38h4d1ce4f_1    conda-forge
mistune                   0.8.4           py38h1e0a361_1002    conda-forge
mpl-scatter-density       0.7                      pypi_0    pypi
munch                     2.5.0                      py_0    conda-forge
natsort                   7.0.1                      py_0    conda-forge
nbclient                  0.5.1                      py_0    conda-forge
nbconvert                 6.0.7            py38h32f6830_1    conda-forge
nbdime                    2.1.0                      py_0    conda-forge
nbformat                  5.0.8                      py_0    conda-forge
ncurses                   6.2                  he1b5a44_2    conda-forge
nest-asyncio              1.4.1                      py_0    conda-forge
nested_dict               1.61               pyh9f0ad1d_0    conda-forge
networkx                  2.5                        py_0    conda-forge
nodejs                    14.13.1              h568c755_0    conda-forge
notebook                  6.1.4            py38h32f6830_1    conda-forge
numpy                     1.19.2           py38hf89b668_1    conda-forge
obspy                     1.2.2                    pypi_0    pypi
olefile                   0.46               pyh9f0ad1d_1    conda-forge
openjpeg                  2.3.1                h981e76c_3    conda-forge
openssl                   1.1.1h               h516909a_0    conda-forge
packaging                 20.4               pyh9f0ad1d_0    conda-forge
pandas                    1.1.3            py38hc5bc63f_2    conda-forge
pandoc                    2.11.0.2             hd18ef5c_0    conda-forge
pandocfilters             1.4.2                      py_1    conda-forge
parso                     0.7.1              pyh9f0ad1d_0    conda-forge
patsy                     0.5.1                      py_0    conda-forge
pcre                      8.44                 he1b5a44_0    conda-forge
pexpect                   4.8.0              pyh9f0ad1d_2    conda-forge
pickleshare               0.7.5                   py_1003    conda-forge
pillow                    8.0.0            py38h9776b28_0    conda-forge
pip                       20.2.4                     py_0    conda-forge
pixman                    0.38.0            h516909a_1003    conda-forge
plotly                    4.11.0                   pypi_0    pypi
poppler                   0.89.0               h4190859_1    conda-forge
poppler-data              0.4.9                         1    conda-forge
postgresql                12.3                 h8573dbc_2    conda-forge
proj                      7.1.1                h966b41f_3    conda-forge
prometheus_client         0.8.0              pyh9f0ad1d_0    conda-forge
prompt-toolkit            3.0.8                      py_0    conda-forge
pthread-stubs             0.4               h14c3975_1001    conda-forge
ptitprince                0.2.5                    pypi_0    pypi
ptvsd                     4.3.2            py38h1e0a361_2    conda-forge
ptyprocess                0.6.0                   py_1001    conda-forge
py-tools-ds               0.15.7           py38h32f6830_0    conda-forge
pycparser                 2.20               pyh9f0ad1d_2    conda-forge
pygments                  2.7.1                      py_0    conda-forge
pyhamcrest                2.0.2                    pypi_0    pypi
pyopenssl                 19.1.0                     py_1    conda-forge
pyparsing                 2.4.7              pyh9f0ad1d_0    conda-forge
pyproj                    2.6.1.post1      py38h56787f0_3    conda-forge
pyrsistent                0.17.3           py38h1e0a361_1    conda-forge
pyrsr                     0.3.8                      py_0    conda-forge
pyshp                     2.1.2              pyh9f0ad1d_0    conda-forge
pysocks                   1.7.1            py38h924ce5b_2    conda-forge
python                    3.8.6           h852b56e_0_cpython    conda-forge
python-dateutil           2.8.1                      py_0    conda-forge
python_abi                3.8                      1_cp38    conda-forge
pytz                      2020.1             pyh9f0ad1d_0    conda-forge
pywavelets                1.1.1            py38hab2c0dc_3    conda-forge
pyyaml                    5.3.1            py38h8df0ef7_1    conda-forge
pyzmq                     19.0.2           py38ha71036d_2    conda-forge
readline                  8.0                  he28a2e2_2    conda-forge
requests                  2.24.0             pyh9f0ad1d_0    conda-forge
retrying                  1.3.3                    pypi_0    pypi
rtree                     0.9.4            py38h08f867b_1    conda-forge
scikit-image              0.17.2           py38hc5bc63f_3    conda-forge
scikit-learn              0.23.2           py38h519568a_1    conda-forge
scipy                     1.5.2            py38h8c5af15_2    conda-forge
seaborn                   0.11.0                        0    conda-forge
seaborn-base              0.11.0                     py_0    conda-forge
send2trash                1.5.0                      py_0    conda-forge
setuptools                49.6.0           py38h924ce5b_2    conda-forge
shapely                   1.7.1            py38hc7361b7_1    conda-forge
six                       1.15.0             pyh9f0ad1d_0    conda-forge
smmap                     3.0.4              pyh9f0ad1d_0    conda-forge
snappy                    1.1.8                he1b5a44_3    conda-forge
specclassify              0.2.6              pyh9f0ad1d_0    conda-forge
spechomo                  0.8.2                      py_0    conda-forge
spechomo-eval             0.3.3                     dev_0    <develop>
specidx                   0.2.8                     dev_0    <develop>
spectral                  0.22.1             pyh9f0ad1d_0    conda-forge
sqlalchemy                1.3.20                   pypi_0    pypi
sqlite                    3.33.0               h4cf870e_1    conda-forge
statsmodels               0.12.0           py38hab2c0dc_1    conda-forge
tabulate                  0.8.7              pyh9f0ad1d_0    conda-forge
terminado                 0.9.1            py38h32f6830_1    conda-forge
testpath                  0.4.4                      py_0    conda-forge
threadpoolctl             2.1.0              pyh5ca1d4c_0    conda-forge
tifffile                  2020.10.1                  py_0    conda-forge
tiledb                    2.1.1                h47b529c_1    conda-forge
tk                        8.6.10               hed695b0_1    conda-forge
toolz                     0.11.1                     py_0    conda-forge
tornado                   6.0.4            py38h1e0a361_2    conda-forge
tqdm                      4.50.2             pyh9f0ad1d_0    conda-forge
traitlets                 5.0.5                      py_0    conda-forge
tzcode                    2020a                h516909a_0    conda-forge
urllib3                   1.25.11                    py_0    conda-forge
wcwidth                   0.2.5              pyh9f0ad1d_2    conda-forge
webencodings              0.5.1                      py_1    conda-forge
wheel                     0.35.1             pyh9f0ad1d_0    conda-forge
widgetsnbextension        3.5.1            py38h32f6830_4    conda-forge
xarray                    0.16.1                   pypi_0    pypi
xerces-c                  3.2.3                hfe33f54_1    conda-forge
xeus                      0.24.2               h841dea4_1    conda-forge
xeus-python               0.8.6            py38h2078d81_1    conda-forge
xorg-kbproto              1.0.7             h14c3975_1002    conda-forge
xorg-libice               1.0.10               h516909a_0    conda-forge
xorg-libsm                1.2.3             h84519dc_1000    conda-forge
xorg-libx11               1.6.12               h516909a_0    conda-forge
xorg-libxau               1.0.9                h14c3975_0    conda-forge
xorg-libxdmcp             1.1.3                h516909a_0    conda-forge
xorg-libxext              1.3.4                h516909a_0    conda-forge
xorg-libxrender           0.9.10            h516909a_1002    conda-forge
xorg-renderproto          0.11.1            h14c3975_1002    conda-forge
xorg-xextproto            7.3.0             h14c3975_1002    conda-forge
xorg-xproto               7.0.31            h14c3975_1007    conda-forge
xz                        5.2.5                h516909a_1    conda-forge
yaml                      0.2.5                h516909a_0    conda-forge
zeromq                    4.3.3                he1b5a44_2    conda-forge
zfp                       0.5.5                he1b5a44_4    conda-forge
zipp                      3.3.1                      py_0    conda-forge
zlib                      1.2.11            h516909a_1010    conda-forge
zstd                      1.4.5                h6597ccf_2    conda-forge

[mathause]

It's nice that cartopy has less dependencies. But it may be surprising to many users that cartopy can no longer plot any plots in the default conda installation (at least matplotlib and scipy seem to be required, which are no longer installed per default).

[gcaria]

I'd be happy to work on this. I'm guessing a try-except around the import would fix this.

Should only the files inside lib/cartopy/* be modified with the helpful error message (no docs/ nor examples/) ?
Maybe also the lib/cartopy/tests should not be touched since only developers use it.

An idea, would it be correct to add import matplotlib and a try-except around it in lib/cartopy/mpl/__init__.py since clearly matplotlib is used everywhere in that package ?

[greglucas]

I believe all of our optional dependencies now have try/except around them (scipy/pykdtree):

cartopy/lib/cartopy/img_transform.py

Lines 15 to 24 in 6e6f3b5

	try:
	import pykdtree.kdtree
	_is_pykdtree = True
	except ImportError:
	try:
	import scipy.spatial
	except ImportError as e:
	raise ImportError("Using image transforms requires either "
	"pykdtree or scipy.") from e
	_is_pykdtree = False

and pyepsg is no longer used now that we are using pyproj.