# -*- coding: utf-8 -*-
"""
Capturing output representations
================================

This example demonstrates how the `capture_repr` configuration option
([Controlling what output is captured](https://sphinx-gallery.github.io/stable/configuration.html#capture-repr))
 works. The default `capture_repr` setting is
`('_repr_html_', '__repr__')` and was used to build this
Mkdocs-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 are also explained.
"""
#%%
# 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.

# example 1
a = 2
b = 10

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

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

#%%
# Mkdocs-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`, Mkdocs-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.

# example 3
import pandas as pd

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

#%%
# 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__`.
#
# Statsmodels tables should also be styled appropriately:

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

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

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

#%%
# `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:

import matplotlib.pyplot as plt

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

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

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

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

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

#%%
# The `capture_repr` configuration
# --------------------------------
#
# The `capture_repr` configuration is `('_repr_html_', '__repr__')` by
# default. This directs Mkdocs-Gallery to capture 'representations' of the last
# statement of a code block, if it is an expression. Mkdocs-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.
