Add support for capturing svg, png, and jpeg and _repr_mimebundle_

doc/advanced.rst

@@ -143,12 +143,16 @@ Write a custom image scraper
 By default, Sphinx-Gallery supports image scraping for Matplotlib
 (:func:`~sphinx_gallery.scrapers.matplotlib_scraper`). If you wish to capture
 output from other python packages, first determine if the object you wish to
-capture has a ``_repr_html_`` method. If so, you can use the configuration
-``capture_repr`` (:ref:`capture_repr`) to control the display of the object,
-without the need to write a custom scraper. This configuration allows capture
-of the raw html output, in a process similar to other html-based displays such
-as `jupyter <https://jupyter.org/>`_. If the first option does not work,
-this section describes how to write a custom scraper.
+capture has any of the other supported capture methods: ``_repr_html_``,
+``_repr_png_``, ``_repr_jpeg_``, and ``_repr_svg_``. If so, you can use the
+configuration ``capture_repr`` (:ref:`capture_repr`) to control the display of
+the object, without the need to write a custom scraper. This configuration allows
+capture of the raw html/png/jpeg/svg output, in a process similar to other enriched
+displays such as `jupyter <https://jupyter.org/>`_. If the object supports
+``_repr_mimebundle_``, adding, e.g., ``_repr_svg_`` to ``capture_repr`` will also
+look for SVG in the returned MIME-bundle.
+
+If the first option does not work, this section describes how to write a custom scraper.
 
 Image scrapers are functions (or callable class instances) that do the following
 things:

doc/conf.py

@@ -327,6 +327,7 @@ def setup(app):
     'sklearn': ('https://scikit-learn.org/stable', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
+    'ipython': ('https://ipython.readthedocs.io/en/stable/', None),
 }
 
 examples_dirs = ['../examples', '../tutorials']

doc/configuration.rst

@@ -1856,8 +1856,21 @@ are:
 * ``__str__`` - returns a string containing a nicely printable representation
   of an object. This is what is used when you ``print()`` an object or pass it
   to ``format()``.
-* ``_repr_html_`` - returns a HTML version of the object. This method is only
-  present in some objects, for example, pandas dataframes.
+* ``_repr_html_`` - returns an HTML version of the object.
+* ``_repr_png_`` - returns a PNG version of the object.
+* ``_repr_jpeg_`` - returns a JPEG version of the object.
+* ``_repr_svg_`` - returns an SVG version of the object.
+
+Note that the last four methods are only available for some objects. For example,
+Pandas dataframes, SymPy expressions, and GraphViz graphs, support one or more of
+these formats.
+
+.. note::
+
+    Some objects support :py:meth:`~MyObject._repr_mimebundle_`, which is the preferred
+    way to access enriched representations. By specifying, e.g., ``_repr_svg_``,
+    Sphinx-Gallery will first look for an SVG in the MIME bundle.
+    If not, it will call ``_repr_svg_`` if available.
 
 Output capture can be controlled globally by the ``capture_repr`` configuration
 setting or file-by-file by adding a comment to the example file, which overrides

examples/no_output/just_code.py

@@ -4,7 +4,7 @@
 
 This demonstrates an example ``.py`` file that is not executed when gallery is
 generated (see :ref:`build_pattern`) but nevertheless gets included as an
-example. Note that no output is capture as this file is not executed.
+example. Note that no output is captured as this file is not executed.
 """
 
 # Code source: Óscar Nájera

examples/plot_3_capture_repr.py

@@ -111,7 +111,7 @@
 # default ``capture_repr`` setting, ``_repr_html_`` is attempted to be captured
 # first. If this method does not exist, the ``__repr__`` method would be
 # captured. If the ``__repr__`` also does not exist (unlikely for non-user
-# defined objects), nothing would be captured. For example, if the the
+# defined objects), nothing would be captured. For example, if the
 # configuration was set to ``'capture_repr': ('_repr_html_')`` nothing would be
 # captured for example 2 as ``b`` does not have a ``_repr_html_``.
 # You can change the 'representations' in the ``capture_repr`` tuple to finely

sphinx_gallery/directives.py

@@ -128,7 +128,7 @@ class ImageSg(images.Image):
                      /plot_types/basic/images/sphx_glr_bar_001_2_00x.png 2.00x
             :class: sphx-glr-single-img
 
-    The resulting html is::
+    The resulting HTML is::
 
         <img src="sphx_glr_bar_001_hidpi.png"
             srcset="_images/sphx_glr_bar_001.png,

sphinx_gallery/gen_gallery.py

@@ -171,7 +171,8 @@ def _fill_gallery_conf_defaults(sphinx_gallery_conf, app=None,
 
     # Check capture_repr
     capture_repr = gallery_conf['capture_repr']
-    supported_reprs = ['__repr__', '__str__', '_repr_html_']
+    supported_reprs = {'__repr__', '__str__', '_repr_html_', '_repr_png_',
+                       '_repr_svg_', '_repr_jpeg_'}
     if isinstance(capture_repr, tuple):
         for rep in capture_repr:
             if rep not in supported_reprs:
@@ -815,7 +816,7 @@ def _make_graph(fname, entries, gallery_conf):
 
 
 def write_api_entry_usage(app, docname, source):
-    """Write an html page describing which API entries are used and unused.
+    """Write an HTML page describing which API entries are used and unused.
 
     To document and graph only those API entries that are used by
     autodoc, we have to wait for autodoc to finish and hook into the

sphinx_gallery/gen_rst.py

@@ -30,12 +30,13 @@
 import sys
 import traceback
 import codeop
+from pathlib import PurePosixPath
 
 from sphinx.errors import ExtensionError
 import sphinx.util
 
 from .scrapers import (save_figures, ImagePathIterator, clean_modules,
-                       _find_image_ext)
+                       _find_image_ext, figure_rst)
 from .utils import (replace_py_ipynb, scale_image, get_md5sum, _replace_md5,
                     optipng, status_iterator)
 from . import glr_path_static
@@ -726,12 +727,40 @@ def _exec_and_get_memory(compiler, ast_Module, code_ast, gallery_conf,
     return is_last_expr, mem_max
 
 
+# Map _repr_*_ to MIME type present in _repr_mimebundle_
+MIME_MAPPING = {'_repr_svg_': 'image/svg+xml',
+                '_repr_jpeg_': 'image/jpeg',
+                '_repr_png_': 'image/png',
+                '_repr_html_': 'text/html'}
+MIME_MAPPING_REPR = set(MIME_MAPPING.keys())
+
+
 def _get_last_repr(capture_repr, ___):
-    """Get a repr of the last expression, using first method in 'capture_repr'
-    available for the last expression."""
+    """
+    Get a repr of the last expression, using first method in 'capture_repr'
+    available for the last expression.
+    """
+    # First try `_repr_mimebundle_`for those representations that may be there
+    capture_repr_set = set(capture_repr)
+    included_mime_types = {MIME_MAPPING[repr] for repr in
+                           capture_repr_set.intersection(MIME_MAPPING_REPR)}
+    excluded_mime_types = {MIME_MAPPING[repr] for repr in
+                           MIME_MAPPING_REPR.difference(capture_repr_set)}
+    mimebundle = {}
+    if included_mime_types and hasattr(___, '_repr_mimebundle_'):
+        try:
+            mimebundle = ___._repr_mimebundle_(include=included_mime_types,
+                                               exclude=excluded_mime_types)
+        except Exception:
+            pass
+
     for meth in capture_repr:
         try:
-            last_repr = getattr(___, meth)()
+            if meth in MIME_MAPPING and MIME_MAPPING[meth] in mimebundle:
+                # Already generated in _repr_mimebundle_
+                last_repr = mimebundle[MIME_MAPPING[meth]]
+            else:
+                last_repr = getattr(___, meth)()
             # for case when last statement is print()
             if last_repr is None or last_repr == 'None':
                 repr_meth = None
@@ -741,13 +770,13 @@ def _get_last_repr(capture_repr, ___):
             last_repr = None
             repr_meth = None
         else:
-            if isinstance(last_repr, str):
+            if isinstance(last_repr, (str, bytes)):
                 break
     return last_repr, repr_meth
 
 
 def _get_code_output(is_last_expr, example_globals, gallery_conf, logging_tee,
-                     images_rst, file_conf):
+                     images_rst, file_conf, script_vars):
     """Obtain standard output and html output in reST."""
     last_repr = None
     repr_meth = None
@@ -778,10 +807,19 @@ def _get_code_output(is_last_expr, example_globals, gallery_conf, logging_tee,
     captured_std = ansi_escape.sub('', captured_std)
 
     # give html output its own header
+    captured_html = ''
     if repr_meth == '_repr_html_':
         captured_html = HTML_HEADER.format(indent(last_repr, ' ' * 4))
-    else:
-        captured_html = ''
+    elif repr_meth in ('_repr_png_', '_repr_jpeg_', '_repr_svg_'):
+        image_path = next(script_vars['image_path_iterator'])
+        image_path = PurePosixPath(image_path)
+        if repr_meth in ('_repr_jpeg_', '_repr_svg_'):
+            suffix = '.svg' if repr_meth == '_repr_svg_' else ".jpg"
+            image_path = image_path.with_suffix(suffix)
+        mode = 'w' if repr_meth == '_repr_svg_' else 'wb'
+        with open(image_path, mode) as f:
+            f.write(last_repr)
+        images_rst += figure_rst([image_path], gallery_conf["src_dir"])
 
     code_output = f"\n{images_rst}\n\n{captured_std}\n{captured_html}\n\n"
     return code_output
@@ -882,7 +920,7 @@ def execute_code_block(compiler, block, example_globals, script_vars,
 
         code_output = _get_code_output(
             is_last_expr, example_globals, gallery_conf, logging_tee,
-            images_rst, file_conf
+            images_rst, file_conf, script_vars
         )
     finally:
         _reset_cwd_syspath(cwd, sys_path)

sphinx_gallery/tests/test_full.py

@@ -30,7 +30,7 @@
 
 # total number of plot_*.py files in tinybuild/examples + examples_rst_index
 # + examples_with_rst
-N_EXAMPLES = 15 + 3 + 2
+N_EXAMPLES = 19 + 3 + 2
 N_FAILING = 2
 N_GOOD = N_EXAMPLES - N_FAILING  # galleries that run w/o error
 # passthroughs examples_rst_index, examples_with_rst
@@ -334,6 +334,44 @@ def test_repr_html_classes(sphinx_app):
     assert 'gallery-rendered-html.css' in lines
 
 
+def test_repr_svg_classes(sphinx_app):
+    """Test appropriate _repr_svg_ classes."""
+    example_file = op.join(
+        sphinx_app.outdir, 'auto_examples', 'plot_svg_repr.html')
+    with codecs.open(example_file, 'r', 'utf-8') as fid:
+        lines = fid.read()
+    assert 'sphx_glr_plot_svg_repr_001.svg' in lines
+
+
+def test_repr_svg_from_mimebundle_classes(sphinx_app):
+    """Test appropriate _repr_mimebundle_ classes."""
+    example_file = op.join(
+        sphinx_app.outdir, 'auto_examples', 'plot_mime_bundle.html')
+    with codecs.open(example_file, 'r', 'utf-8') as fid:
+        lines = fid.read()
+    assert "This should actually print" in lines
+    for i in range(1, 4):
+        assert f'sphx_glr_plot_mime_bundle_00{i}.svg' in lines
+
+
+def test_capture_jpg(sphinx_app):
+    """Test capturing the JPG from _repr_jpeg_."""
+    example_file = op.join(
+        sphinx_app.outdir, 'auto_examples', 'plot_random_jpg.html')
+    with codecs.open(example_file, 'r', 'utf-8') as fid:
+        lines = fid.read()
+    assert 'sphx_glr_plot_random_jpg_001.jpg' in lines
+
+
+def test_capture_png(sphinx_app):
+    """Test capturing the PNG from _repr_png_ of a Pillow Image."""
+    example_file = op.join(
+        sphinx_app.outdir, 'auto_examples', 'plot_random_png.html')
+    with codecs.open(example_file, 'r', 'utf-8') as fid:
+        lines = fid.read()
+    assert 'sphx_glr_plot_random_png_001.png' in lines
+
+
 def test_embed_links_and_styles(sphinx_app):
     """Test that links and styles are embedded properly in doc."""
     out_dir = sphinx_app.outdir

sphinx_gallery/tests/test_gen_rst.py

@@ -830,6 +830,23 @@ def _repr_html_(self):
 
 """
 
+code_repr_and_svg = """
+class repr_and_svg_class():
+    def __init__(self):
+        pass
+
+    def __repr__(self):
+        return "This is the __repr__"
+
+    def _repr_svg_(self):
+        return ("<svg viewBox='0 0 50 50' xmlns='http://www.w3.org/2000/svg'>"
+                "<line x1='0' y1='0' x2='50' y2='50' stroke='black' />"
+                "</svg>")
+
+class_inst = repr_and_svg_class()
+class_inst
+"""
+
 
 def _clean_output(output):
     is_text = '.. rst-class:: sphx-glr-script-out' in output
@@ -879,6 +896,8 @@ def _clean_output(output):
     pytest.param(('_repr_html_', '__repr__'), code_repr_only,
                  'This is the __repr__', id='repr_only,(html,repr)'),
     pytest.param(('_repr_html_',), code_plt, '', id='html_none'),
+    pytest.param(('__repr__', '_repr_svg_'), code_repr_and_svg,
+                 'This is the __repr__', id='repr_and_svg,(repr,svg)'),
 ])
 def test_capture_repr(gallery_conf, capture_repr, code, expected_out,
                       req_mpl, req_pil, script_vars):

sphinx_gallery/tests/tinybuild/examples/plot_mime_bundle.py

@@ -0,0 +1,72 @@
+"""
+Test using _repr_mimebundle_
+=====================================
+Test repr capturing via ``_repr_mimebundle_`` and make sure that the
+``capture_repr`` ordering is honored as well as ``_repr_mimebundle_``
+over other ``_repr_*_`` having precedence.
+"""
+# sphinx_gallery_capture_repr = ('_repr_svg_', '_repr_html_')
+# %%
+# First define a class with only an SVG in the MIME bundle
+
+
+class A:
+    def _repr_mimebundle_(self, **kwargs):
+        return {"image/svg+xml": """
+<svg viewBox="0 0 50 50" xmlns="http://www.w3.org/2000/svg">
+<line x1="0" y1="0" x2="50" y2="50" stroke="black" />
+</svg>
+"""}
+
+
+A()
+
+
+# %%
+# Then, only a HTML representation, but both ``_repr_html_`` and
+# ``_repr_mimebundle_``.
+class B:
+    def _repr_html_(self):
+        return '<p><b>This should not print</b></p>'
+
+    def _repr_mimebundle_(self, **kwargs):
+        # Breaking the string here, so one can use the sentence to
+        # check the correct HTML output
+        return {"text/html": '<p><b>This should'
+                             ' actually print</b></p>'}
+
+
+B()
+
+
+# %%
+# Then, both SVG and HTML. The SVG should be selected based on the order.
+class C:
+    def _repr_mimebundle_(self, **kwargs):
+        return {"image/svg+xml": """
+<svg viewBox="0 0 50 50" xmlns="http://www.w3.org/2000/svg">
+<line x1="0" y1="0" x2="50" y2="50" stroke="black" />
+</svg>
+""",
+                "text/html": '<p><b>This should not print</b></p>'}
+
+
+C()
+
+
+# %%
+# Finally, a separate ``_repr_svg_`` that should be selected since
+# ``_repr_mimebundle_`` only includes HTML.
+class D:
+    def _repr_svg_(self):
+        return """
+    <svg viewBox="0 0 50 50" xmlns="http://www.w3.org/2000/svg">
+    <line x1="0" y1="0" x2="50" y2="50" stroke="black" />
+    </svg>
+    """
+
+    def _repr_mimebundle_(self, **kwargs):
+        return {"text/html": '<p><b>This should not print</b></p>'}
+
+
+D()

sphinx_gallery/tests/tinybuild/examples/plot_random_jpg.py

@@ -0,0 +1,26 @@
+"""
+Capture JPG test
+================
+Test that it is possible to capture a JPG from a class with a ``_repr_jpeg__``
+method.
+"""
+
+
+# sphinx_gallery_capture_repr = ('_repr_jpeg_',)
+import io
+import numpy
+from PIL import Image
+
+
+class RandomImage:
+    def __init__(self):
+        imarray = numpy.random.rand(160, 160, 3) * 255
+        self._image = Image.fromarray(imarray.astype('uint8')).convert('RGB')
+
+    def _repr_jpeg_(self):
+        b = io.BytesIO()
+        self._image.save(b, "JPEG")
+        return b.getvalue()
+
+
+RandomImage()