捕获输出表示

此示例演示了配置 capture_repr (控制捕获的输出) 的工作原理。默认的 capture_repr 设置是 capture_repr: ('_repr_html_', '__repr__')，并在构建 Sphinx-Gallery 文档时使用。本示例演示了使用此设置捕获的输出。还解释了使用其他 capture_repr 设置时捕获的输出之间的差异。

下面的代码块没有捕获任何内容，因为没有数据被定向到标准输出，并且最后一个语句是赋值语句，而不是表达式。

# example 1
a = 2
b = 10

如果您确实希望捕获 b 的值，您需要使用

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

10

Sphinx-Gallery 首先尝试捕获 b 的 _repr_html_，因为这是 capture_repr 元组中的第一个“表示”方法。由于此方法对于 b 不存在，Sphinx-Gallery 会继续并尝试捕获 __repr__ 方法，该方法在元组中排第二。此方法对于 b 存在，因此它被捕获，并且上面的输出可见。

下面的代码块中使用 pandas 数据框来提供一个具有 _repr_html_ 方法的表达式的示例。

# example 3
import pandas as pd

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

	col1	col2
0	1	3
1	2	4

pandas 数据框 df 同时具有 __repr__ 和 _repr_html_ 方法。由于 _repr_html_ 在 capture_repr 元组中排在前面，因此 _repr_html_ 会优先于 __repr__ 被捕获。

对于下面的示例，有数据被定向到标准输出，并且最后一个语句是表达式。

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

Hello world

12

Statsmodels 表格也应该被适当地设置样式

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

statsmodels.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() 输出到标准输出，标准输出始终被捕获。因此，字符串 'Hello world' 被捕获。最后一个表达式的“表示”也被捕获。同样，由于此表达式 a + b 不具有 _repr_html_ 方法，因此捕获了 __repr__ 方法。

Matplotlib 输出

Matplotlib 函数调用通常会返回一个 Matplotlib 对象，并输出图形。对于最后一个语句是 Matplotlib 表达式的代码块，会捕获对象的“表示”，以及图形。这是因为 Matplotlib 对象具有 __repr__ 方法，并且我们的 capture_repr 元组包含 __repr__。请注意，Matplotlib 对象还具有 __str__ 方法。

在下面的示例中，matplotlib.pyplot.plot() 返回一个表示绘制数据的 Line2D 对象列表，以及列表的 __repr__ 和图形。

import matplotlib.pyplot as plt

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

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

要避免捕获文本表示，您可以将最后一个 Matplotlib 表达式赋值给一个临时变量

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

或者，您可以在代码块的末尾添加 plt.show()，该方法不会返回任何内容

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

capture_repr 配置

capture_repr 配置默认情况下为 ('_repr_html_', '__repr__')。这会指示 Sphinx-Gallery 捕获代码块最后一个语句的“表示”（如果它是表达式）。Sphinx-Gallery 会根据“表示”在元组中出现的顺序来执行此操作。使用默认的 capture_repr 设置，首先尝试捕获 _repr_html_。如果此方法不存在，则会捕获 __repr__ 方法。如果 __repr__ 也不存在（对于非用户定义的对象来说不太可能），则不会捕获任何内容。例如，如果配置被设置为 'capture_repr': ('_repr_html_')，则示例 2 将不会捕获任何内容，因为 b 不具有 _repr_html_。您可以更改 capture_repr 元组中的“表示”，以微调在示例 .py 文件中捕获的内容。

要仅捕获定向到标准输出的数据，您可以将 capture_repr 设置为空元组：capture_repr: ()。使用此设置，仅捕获定向到标准输出的数据。对于上面的示例，仅捕获示例 4 的输出。尽管最后一个语句对于示例 2、3 和 4 都是表达式，但不会输出最后一个表达式的“表示”。您需要在最后一个表达式中添加 print() 来捕获它的“表示”。空元组设置模仿了 Sphinx-Gallery 在 v0.5.0 之前（引入此配置时）的行为。

估计内存使用量：181 MB