
.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/plot_3_capture_repr.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_plot_3_capture_repr.py>`
        to download the full example code. or to run this example in your browser via Binder

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_plot_3_capture_repr.py:


.. _capture_repr_examples:

Capturing output representations
================================

This example demonstrates how the configuration ``capture_repr``
(:ref:`capture_repr`) works. The default ``capture_repr`` setting is
``capture_repr: ('_repr_html_', '__repr__')`` and was used when building the
Sphinx-Gallery documentation. The output that is captured with this setting
is demonstrated in this example. Differences in outputs that would be captured
with other ``capture_repr`` settings is also explained.

.. GENERATED FROM PYTHON SOURCE LINES 16-18

Nothing is captured for the code block below because no data is directed to
standard output and the last statement is an assignment, not an expression.

.. GENERATED FROM PYTHON SOURCE LINES 18-23

.. code-block:: Python


    # example 1
    a = 2
    b = 10








.. GENERATED FROM PYTHON SOURCE LINES 24-25

If you did wish to capture the value of ``b``, you would need to use:

.. GENERATED FROM PYTHON SOURCE LINES 25-31

.. code-block:: Python


    # example 2
    a = 2
    b = 10
    b  # this is an expression








.. GENERATED FROM PYTHON SOURCE LINES 32-40

Sphinx-Gallery first attempts to capture the ``_repr_html_`` of ``b`` as this
is the first 'representation' method in the ``capture_repr`` tuple. As this
method does not exist for ``b``, Sphinx-Gallery moves on and tries to capture
the ``__repr__`` method, which is second in the tuple. This does exist for
``b`` so it is captured and the output is seen above.

A pandas dataframe is used in the code block below to provide an example of
an expression with a ``_repr_html_`` method.

.. GENERATED FROM PYTHON SOURCE LINES 40-47

.. code-block:: Python


    # example 3
    import pandas as pd

    df = pd.DataFrame(data={"col1": [1, 2], "col2": [3, 4]})
    df








.. GENERATED FROM PYTHON SOURCE LINES 48-54

The pandas dataframe ``df`` has both a ``__repr__`` and ``_repr_html_``
method. As ``_repr_html_`` appears first in the ``capture_repr`` tuple, the
``_repr_html_`` is captured in preference to ``__repr__``.

For the example below, there is data directed to standard output and the last
statement is an expression.

.. GENERATED FROM PYTHON SOURCE LINES 54-59

.. code-block:: Python


    # example 4
    print("Hello world")
    a + b





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Hello world




.. GENERATED FROM PYTHON SOURCE LINES 60-61

Statsmodels tables should also be styled appropriately:

.. GENERATED FROM PYTHON SOURCE LINES 61-68

.. code-block:: Python


    # example 5
    import numpy as np
    import statsmodels.iolib.table

    statsmodels.iolib.table.SimpleTable(np.zeros((3, 3)))








.. GENERATED FROM PYTHON SOURCE LINES 69-87

``print()`` outputs to standard output, which is always captured. The
string ``'Hello world'`` is thus captured. A 'representation' of the last
expression is also captured. Again, since this expression ``a + b`` does not
have a ``_repr_html_`` method, the ``__repr__`` method is captured.

Matplotlib output
##################

Matplotlib function calls generally return a Matplotlib object as well as
outputting the figure. For code blocks where the last statement is a
Matplotlib expression, a 'representation' of the object will be captured, as
well as the plot. This is because Matplotlib objects have a ``__repr__``
method and our ``capture_repr`` tuple contains ``__repr__``. Note that
Matplotlib objects also have a ``__str__`` method.

In the example below, ``matplotlib.pyplot.plot()`` returns a list of
``Line2D`` objects representing the plotted data and the ``__repr__`` of the
list is captured as well as the figure:

.. GENERATED FROM PYTHON SOURCE LINES 87-92

.. code-block:: Python


    import matplotlib.pyplot as plt

    plt.plot([1, 2, 3])




.. image-sg:: /auto_examples/images/sphx_glr_plot_3_capture_repr_001.png
   :alt: plot 3 capture repr
   :srcset: /auto_examples/images/sphx_glr_plot_3_capture_repr_001.png, /auto_examples/images/sphx_glr_plot_3_capture_repr_001_2_00x.png 2.00x
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 93-95

To avoid capturing the text representation, you can assign the last Matplotlib
expression to a temporary variable:

.. GENERATED FROM PYTHON SOURCE LINES 95-98

.. code-block:: Python


    _ = plt.plot([1, 2, 3])




.. image-sg:: /auto_examples/images/sphx_glr_plot_3_capture_repr_002.png
   :alt: plot 3 capture repr
   :srcset: /auto_examples/images/sphx_glr_plot_3_capture_repr_002.png, /auto_examples/images/sphx_glr_plot_3_capture_repr_002_2_00x.png 2.00x
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 99-101

Alternatively, you can add ``plt.show()``, which does not return anything,
to the end of the code block:

.. GENERATED FROM PYTHON SOURCE LINES 101-105

.. code-block:: Python


    plt.plot([1, 2, 3])
    plt.show()




.. image-sg:: /auto_examples/images/sphx_glr_plot_3_capture_repr_003.png
   :alt: plot 3 capture repr
   :srcset: /auto_examples/images/sphx_glr_plot_3_capture_repr_003.png, /auto_examples/images/sphx_glr_plot_3_capture_repr_003_2_00x.png 2.00x
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 106-130

The ``capture_repr`` configuration
##################################

The ``capture_repr`` configuration is ``('_repr_html_', '__repr__')`` by
default. This directs Sphinx-Gallery to capture 'representations' of the last
statement of a code block, if it is an expression. Sphinx-Gallery does
this according to the order 'representations' appear in the tuple. With the
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
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
tune what is captured in your example ``.py`` files.

To only capture data directed to standard output you can set ``capture_repr``
to be an empty tuple: ``capture_repr: ()``. With this setting, only data
directed to standard output is captured. For the examples above, output would
only be captured for example 4. Although the last statement is an expression
for examples 2, 3 and 4 no 'representation' of the last expression would be
output. You would need to add ``print()`` to the last expression to capture
a 'representation' of it. The empty tuple setting imitates the behaviour of
Sphinx-Gallery prior to v0.5.0, when this configuration was introduced.


.. _sphx_glr_download_auto_examples_plot_3_capture_repr.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: binder-badge

      .. image:: images/binder_badge_logo.svg
        :target: https://mybinder.org/v2/gh/sphinx-gallery/sphinx-gallery.github.io/master?urlpath=lab/tree/notebooks/auto_examples/plot_3_capture_repr.ipynb
        :alt: Launch binder
        :width: 150 px

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_3_capture_repr.ipynb <plot_3_capture_repr.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_3_capture_repr.py <plot_3_capture_repr.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_3_capture_repr.zip <plot_3_capture_repr.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_
