
.. 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

        Click :ref:`here <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:: python3


    # 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:: python3


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





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

 Out:

 .. code-block:: none


    10



.. 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:: python3


    # example 3
    import pandas as pd

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






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>col1</th>
          <th>col2</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>1</td>
          <td>3</td>
        </tr>
        <tr>
          <th>1</th>
          <td>2</td>
          <td>4</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. 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:: python3


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





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

 Out:

 .. code-block:: none

    Hello world

    12



.. GENERATED FROM PYTHON SOURCE LINES 60-61

Statsmodels tables should also be styled appropriately:

.. GENERATED FROM PYTHON SOURCE LINES 61-67

.. code-block:: python3


    # example 5
    import numpy as np
    import statsmodels.iolib.table
    statsmodels.iolib.table.SimpleTable(np.zeros((3, 3)))






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <table class="simpletable">
    <tr>
      <td>0.0</td> <td>0.0</td> <td>0.0</td>
    </tr>
    <tr>
      <td>0.0</td> <td>0.0</td> <td>0.0</td>
    </tr>
    <tr>
      <td>0.0</td> <td>0.0</td> <td>0.0</td>
    </tr>
    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 68-86

``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 86-91

.. code-block:: python3


    import matplotlib.pyplot as plt

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




.. image:: /auto_examples/images/sphx_glr_plot_3_capture_repr_001.png
    :alt: plot 3 capture repr
    :class: sphx-glr-single-img


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

 Out:

 .. code-block:: none


    [<matplotlib.lines.Line2D object at 0x7fb03a728220>]



.. GENERATED FROM PYTHON SOURCE LINES 92-94

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

.. GENERATED FROM PYTHON SOURCE LINES 94-97

.. code-block:: python3


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




.. image:: /auto_examples/images/sphx_glr_plot_3_capture_repr_002.png
    :alt: plot 3 capture repr
    :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 98-100

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

.. GENERATED FROM PYTHON SOURCE LINES 100-104

.. code-block:: python3


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




.. image:: /auto_examples/images/sphx_glr_plot_3_capture_repr_003.png
    :alt: plot 3 capture repr
    :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 105-129

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.

**Estimated memory usage:**  12 MB


.. _sphx_glr_download_auto_examples_plot_3_capture_repr.py:


.. only :: html

 .. container:: sphx-glr-footer
    :class: 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-python

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



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

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


.. only:: html

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

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