Make IPython partially optional on CI to increase test coverage of figure.py (#1496)

Makes IPython an optional dependency in Continuous Integration
for the minimum dependency stream (Python 3.7/NumPy 1.18),
so that uncovered if-branches in `figure.py` are covered. Tests
which require IPython have a pytest.importorskip line added so
that the test suite doesn't break.

* Install IPython as an optional dependency only for Python 3.9 CI tests
* Add pytest.importorskip ipython to test_figure_show
* Add pytest.importorskip ipython and sphinx_gallery to test_pygmtscrapper
* Skip running the fig.inset doctest's fig.show line
* Add test for fig.show using notebook method when IPython isn't installed
* Add tests for figure's PNG and HTML printable representations
* Provide reason for skipping test_figure_show and test_pygmtscrapper
* Silence pylint protected-access warning on accessing PNG and HTML repr
* Try test figure display external method
* Move pytest.importorskip IPython outside of test_pygmtscrapper

Co-authored-by: Dongdong Tian <[email protected]>

Author: weiji14

.github/workflows/ci_tests.yaml

@@ -52,7 +52,7 @@ jobs:
             optional-packages: ''
           - python-version: 3.9
             numpy-version: '1.21'
-            optional-packages: 'geopandas'
+            optional-packages: 'geopandas ipython'
     defaults:
       run:
         shell: bash -l {0}
@@ -96,9 +96,8 @@ jobs:
           mamba install gmt=6.2.0 numpy=${{ matrix.numpy-version }} \
                         pandas xarray netCDF4 packaging \
                         ${{ matrix.optional-packages }} \
-                        coverage[toml] dvc ipython make \
-                        pytest-cov pytest-mpl pytest>=6.0 \
-                        sphinx-gallery
+                        coverage[toml] dvc make pytest>=6.0 \
+                        pytest-cov pytest-mpl sphinx-gallery
 
       # Show installed pkg information for postmortem diagnostic
       - name: List installed packages

pygmt/src/inset.py

@@ -119,7 +119,7 @@ def inset(self, **kwargs):
     ...
     >>> # Map elements outside the "with" block are plotted in the main figure
     >>> fig.logo(position="jBR+o0.2c+w3c")
-    >>> fig.show()
+    >>> fig.show()  # doctest: +SKIP
     <IPython.core.display.Image object>
     """
     kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access

pygmt/tests/test_figure.py

@@ -5,11 +5,17 @@
 """
 import os
 
+try:
+    import IPython
+except ModuleNotFoundError:
+    IPython = None  # pylint: disable=invalid-name
+
+
 import numpy as np
 import numpy.testing as npt
 import pytest
 from pygmt import Figure, set_display
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTError, GMTInvalidInput
 from pygmt.helpers import GMTTempFile
 
 
@@ -52,6 +58,23 @@ def test_figure_region_country_codes():
     npt.assert_allclose(fig.region, np.array([0.0, 360.0, -90.0, 90.0]))
 
 
+def test_figure_repr():
+    """
+    Make sure that figure output's PNG and HTML printable representations look
+    ok.
+    """
+    fig = Figure()
+    fig.basemap(region=[0, 1, 2, 3], frame=True)
+    # Check that correct PNG 8-byte file header is produced
+    # https://en.wikipedia.org/wiki/Portable_Network_Graphics#File_header
+    repr_png = fig._repr_png_()  # pylint: disable=protected-access
+    assert repr_png.hex().startswith("89504e470d0a1a0a")
+    # Check that correct HTML image tags are produced
+    repr_html = fig._repr_html_()  # pylint: disable=protected-access
+    assert repr_html.startswith('<img src="data:image/png;base64,')
+    assert repr_html.endswith('" width="500px">')
+
+
 def test_figure_savefig_exists():
     """
     Make sure the saved figure has the right name.
@@ -159,6 +182,7 @@ def mock_psconvert(*args, **kwargs):  # pylint: disable=unused-argument
     )
 
 
+@pytest.mark.skipif(IPython is None, reason="run when IPython is installed")
 def test_figure_show():
     """
     Test that show creates the correct file name and deletes the temp dir.
@@ -199,6 +223,27 @@ def test_figure_show_invalid_method():
         fig.show(method="test")
 
 
+@pytest.mark.skipif(IPython is not None, reason="run without IPython installed")
+def test_figure_show_notebook_error_without_ipython():
+    """
+    Test to check if an error is raised when display method is 'notebook', but
+    IPython is not installed.
+    """
+    fig = Figure()
+    fig.basemap(region=[0, 1, 2, 3], frame=True)
+    with pytest.raises(GMTError):
+        fig.show(method="notebook")
+
+
+def test_figure_display_external():
+    """
+    Test to check that a figure can be displayed in an external window.
+    """
+    fig = Figure()
+    fig.basemap(region=[0, 3, 6, 9], projection="X1c", frame=True)
+    fig.show(method="external")
+
+
 def test_figure_set_display_invalid():
     """
     Test to check if an error is raised when an invalid method is passed to

pygmt/tests/test_sphinx_gallery.py

@@ -8,15 +8,15 @@
 from pygmt.figure import SHOWED_FIGURES, Figure
 
 pygmt_sphinx_gallery = pytest.importorskip(
-    "pygmt.sphinx_gallery", reason="requires sphinx-gallery to be installed"
+    "pygmt.sphinx_gallery", reason="Requires sphinx-gallery to be installed"
 )
+pytest.importorskip("IPython", reason="Requires IPython to be installed")
 
 
 def test_pygmtscraper():
     """
     Make sure the scraper finds the figures and removes them from the pool.
     """
-
     showed = SHOWED_FIGURES.copy()
     for _ in range(len(SHOWED_FIGURES)):
         SHOWED_FIGURES.pop()