Merge pull request #208 from csiro-coasts/split-plot-module

Split plot module up

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)