Note
Go to the endto download the full example code. or to run this example in your browser via JupyterLite or Binder
Capturing output representations#
This example demonstrates how the configurationcapture_repr(Controlling what output is captured) works. The defaultcapture_repr setting iscapture_repr:('_repr_html_','__repr__') and was used when building theSphinx-Gallery documentation. The output that is captured with this settingis demonstrated in this example. Differences in outputs that would be capturedwith othercapture_repr settings is also explained.
Nothing is captured for the code block below because no data is directed tostandard output and the last statement is an assignment, not an expression.
If you did wish to capture the value ofb, you would need to use:
10
Sphinx-Gallery first attempts to capture the_repr_html_ ofb as thisis the first ‘representation’ method in thecapture_repr tuple. As thismethod does not exist forb, Sphinx-Gallery moves on and tries to capturethe__repr__ method, which is second in the tuple. This does exist forb so it is captured and the output is seen above.
A pandas dataframe is used in the code block below to provide an example ofan expression with a_repr_html_ method.
# example 3importpandasaspddf=pd.DataFrame(data={"col1":[1,2],"col2":[3,4]})df
| col1 | col2 | |
|---|---|---|
| 0 | 1 | 3 |
| 1 | 2 | 4 |
The pandas dataframedf has both a__repr__ and_repr_html_method. As_repr_html_ appears first in thecapture_repr tuple, the_repr_html_ is captured in preference to__repr__.
For the example below, there is data directed to standard output and the laststatement is an expression.
Hello world12
Statsmodels tables should also be styled appropriately:
# example 5importnumpyasnpimportstatsmodels.iolib.tablestatsmodels.iolib.table.SimpleTable(np.zeros((3,3)))
| 0.0 | 0.0 | 0.0 |
| 0.0 | 0.0 | 0.0 |
| 0.0 | 0.0 | 0.0 |
print() outputs to standard output, which is always captured. Thestring'Helloworld' is thus captured. A ‘representation’ of the lastexpression is also captured. Again, since this expressiona+b does nothave a_repr_html_ method, the__repr__ method is captured.
Matplotlib output#
Matplotlib function calls generally return a Matplotlib object as well asoutputting the figure. For code blocks where the last statement is aMatplotlib expression, a ‘representation’ of the object will be captured, aswell as the plot. This is because Matplotlib objects have a__repr__method and ourcapture_repr tuple contains__repr__. Note thatMatplotlib objects also have a__str__ method.
In the example below,matplotlib.pyplot.plot() returns a list ofLine2D objects representing the plotted data and the__repr__ of thelist is captured as well as the figure:
importmatplotlib.pyplotaspltplt.plot([1,2,3])
[<matplotlib.lines.Line2D object at 0x7fcd961e5240>]
To avoid capturing the text representation, you can assign the last Matplotlibexpression to a temporary variable:
Alternatively, you can addplt.show(), which does not return anything,to the end of the code block:
Thecapture_repr configuration#
Thecapture_repr configuration is('_repr_html_','__repr__') bydefault. This directs Sphinx-Gallery to capture ‘representations’ of the laststatement of a code block, if it is an expression. Sphinx-Gallery doesthis according to the order ‘representations’ appear in the tuple. With thedefaultcapture_repr setting,_repr_html_ is attempted to be capturedfirst. If this method does not exist, the__repr__ method would becaptured. If the__repr__ also does not exist (unlikely for non-userdefined objects), nothing would be captured. For example, if the theconfiguration was set to'capture_repr':('_repr_html_') nothing would becaptured for example 2 asb does not have a_repr_html_.You can change the ‘representations’ in thecapture_repr tuple to finelytune what is captured in your example.py files.
To only capture data directed to standard output you can setcapture_reprto be an empty tuple:capture_repr:(). With this setting, only datadirected to standard output is captured. For the examples above, output wouldonly be captured for example 4. Although the last statement is an expressionfor examples 2, 3 and 4 no ‘representation’ of the last expression would beoutput. You would need to addprint() to the last expression to capturea ‘representation’ of it. The empty tuple setting imitates the behaviour ofSphinx-Gallery prior to v0.5.0, when this configuration was introduced.
Total running time of the script: (0 minutes 2.700 seconds)
Estimated memory usage: 199 MB
