Split plot module up

It was getting long, and with the geometry rewrite on the way it was
about to get longer. This split makes it easier to support matplotlib as
an optional dependency via the plot extra.

Author: mx-moth

docs/api/plot.rst

@@ -2,6 +2,37 @@
 emsarray.plot
 =============
 
-.. automodule:: emsarray.plot
-    :members:
+.. currentmodule:: emsarray.plot
 
+Plotting an entire figure
+=========================
+
+The :func:`plot_on_figure` and :func:`animate_on_figure` functions
+will generate a simple plot of any supported variables.
+These functions are intended as quick and simple ways of exploring a dataset
+and have limited customisation options.
+Consult the :ref:`examples gallery <examples>`
+for demonstrations on making more customised plots.
+
+.. autofunction:: plot_on_figure
+.. autofunction:: animate_on_figure
+
+Shortcuts
+=========
+
+These functions make common plotting operations simple.
+They are designed as quick shortcuts
+and aim for ease of use and simplicity over being fully featured.
+Most of these functions defer to other parts of matplotlib or cartopy for the actual implementation,
+and users are encouraged to call these underlying implementations directly if more customisation is required.
+
+.. autofunction:: add_coast
+.. autofunction:: add_gridlines
+.. autofunction:: add_landmarks
+
+Utilities
+=========
+
+.. autofunction:: polygons_to_collection
+.. autofunction:: bounds_to_extent
+.. autofunction:: make_plot_title

docs/examples/index.rst

@@ -1,3 +1,5 @@
+.. _examples:
+
 ========
 Examples
 ========

docs/releases/development.rst

@@ -28,3 +28,8 @@ Next release (in development)
   In practice this will usually be "viridis"
   unless the user has changed their local defaults
   (:pr:`206`).
+* Split the :mod:`emsarray.plot` module in to multiple files.
+  It was getting unruly in size and was about to become larger again.
+  The documentation has been updated to match the conceptual divisions.
+  The new layout makes it easier to support matplotlib as an optional dependency
+  (:pr:`207`).

src/emsarray/conventions/_base.py

@@ -15,14 +15,11 @@
 from shapely.geometry.base import BaseGeometry
 from shapely.strtree import STRtree
 
+from emsarray import plot as _plot
 from emsarray import utils
 from emsarray.exceptions import InvalidPolygonWarning, NoSuchCoordinateError
 from emsarray.operations import depth, point_extraction
 from emsarray.operations.cache import hash_attributes, hash_int, hash_string
-from emsarray.plot import (
-    _requires_plot, animate_on_figure, make_plot_title, plot_on_figure,
-    polygons_to_collection
-)
 from emsarray.state import State
 from emsarray.types import Bounds, DataArrayOrName, Pathish
 
@@ -709,7 +706,7 @@ def wind(
         pass
 
     @cached_property  # type: ignore
-    @_requires_plot
+    @_plot._requires_plot
     def data_crs(self) -> 'CRS':
         """
         The coordinate reference system that coordinates in this dataset are
@@ -721,7 +718,7 @@ def data_crs(self) -> 'CRS':
         from cartopy.crs import PlateCarree
         return PlateCarree()
 
-    @_requires_plot
+    @_plot._requires_plot
     def plot_on_figure(
         self,
         figure: 'Figure',
@@ -778,11 +775,11 @@ def plot_on_figure(
             #
             # Users can supply their own titles
             # if this automatic behaviour is insufficient
-            kwargs['title'] = make_plot_title(self.dataset, kwargs['scalar'])
+            kwargs['title'] = _plot.make_plot_title(self.dataset, kwargs['scalar'])
 
-        plot_on_figure(figure, self, **kwargs)
+        _plot.plot_on_figure(figure, self, **kwargs)
 
-    @_requires_plot
+    @_plot._requires_plot
     def plot(self, *args: Any, **kwargs: Any) -> None:
         """Plot a data array and automatically display it.
 
@@ -801,7 +798,7 @@ def plot(self, *args: Any, **kwargs: Any) -> None:
         self.plot_on_figure(pyplot.figure(), *args, **kwargs)
         pyplot.show()
 
-    @_requires_plot
+    @_plot._requires_plot
     def animate_on_figure(
         self,
         figure: 'Figure',
@@ -899,9 +896,9 @@ def animate_on_figure(
                 title_bits.append('{}')
             kwargs['title'] = '\n'.join(title_bits)
 
-        return animate_on_figure(figure, self, coordinate=coordinate, **kwargs)
+        return _plot.animate_on_figure(figure, self, coordinate=coordinate, **kwargs)
 
-    @_requires_plot
+    @_plot._requires_plot
     @utils.timed_func
     def make_poly_collection(
         self,
@@ -978,9 +975,9 @@ def make_poly_collection(
         if 'transform' not in kwargs:
             kwargs['transform'] = self.data_crs
 
-        return polygons_to_collection(self.polygons[self.mask], **kwargs)
+        return _plot.polygons_to_collection(self.polygons[self.mask], **kwargs)
 
-    @_requires_plot
+    @_plot._requires_plot
     def make_quiver(
         self,
         axes: 'Axes',

src/emsarray/plot/__init__.py

@@ -0,0 +1,49 @@
+from typing import Any
+
+from emsarray.utils import RequiresExtraException, requires_extra
+
+try:
+    from . import utils
+    from .base import animate_on_figure, plot_on_figure
+    from .shortcuts import add_coast, add_gridlines, add_landmarks
+    from .utils import (
+        bounds_to_extent, make_plot_title, polygons_to_collection
+    )
+
+    CAN_PLOT = True
+    IMPORT_EXCEPTION = None
+
+except ImportError as exc:
+    CAN_PLOT = False
+    IMPORT_EXCEPTION = exc
+
+    def __getattr__(name: str) -> Any:
+        # module.__getattr__("name") is called when code accessed module.name,
+        # but the module doesn't have that attribute set.
+        # We use this to raise a RequiresExtraException with the assumption
+        # that importing something failed.
+
+        if name in __all__:
+            raise RequiresExtraException("plot") from IMPORT_EXCEPTION
+        else:
+            raise AttributeError(name)
+
+
+# The external API of this module.
+__all__ = [
+    'CAN_PLOT', '_requires_plot',
+
+    # Export the utils module explicitly. Future utility methods may not be
+    # exported using this public API, and instead be accessed using `plot.utils.some_method`
+    'utils',
+
+    # Methods from .base
+    'animate_on_figure', 'plot_on_figure',
+
+    # Methods from .utils
+    'add_coast', 'add_gridlines', 'add_landmarks', 'polygons_to_collection',
+    'bounds_to_extent', 'make_plot_title'
+]
+
+
+_requires_plot = requires_extra(extra='plot', import_error=IMPORT_EXCEPTION)