1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
"""
Handlers for IPythonDirective's @doctest pseudo-decorator.
The Sphinx extension that provides support for embedded IPython code provides
a pseudo-decorator @doctest, which treats the input/output block as a
doctest, raising a RuntimeError during doc generation if the actual output
(after running the input) does not match the expected output.
An example usage is:
.. code-block:: rst
.. ipython::
In [1]: x = 1
@doctest
In [2]: x + 2
Out[3]: 3
One can also provide arguments to the decorator. The first argument should be
the name of a custom handler. The specification of any other arguments is
determined by the handler. For example,
.. code-block:: rst
.. ipython::
@doctest float
In [154]: 0.1 + 0.2
Out[154]: 0.3
allows the actual output ``0.30000000000000004`` to match the expected output
due to a comparison with `np.allclose`.
This module contains handlers for the @doctest pseudo-decorator. Handlers
should have the following function signature::
handler(sphinx_shell, args, input_lines, found, submitted)
where `sphinx_shell` is the embedded Sphinx shell, `args` contains the list
of arguments that follow: '@doctest handler_name', `input_lines` contains
a list of the lines relevant to the current doctest, `found` is a string
containing the output from the IPython shell, and `submitted` is a string
containing the expected output from the IPython shell.
Handlers must be registered in the `doctests` dict at the end of this module.
"""
def str_to_array(s):
"""
Simplistic converter of strings from repr to float NumPy arrays.
If the repr representation has ellipsis in it, then this will fail.
Parameters
----------
s : str
The repr version of a NumPy array.
Examples
--------
>>> s = "array([ 0.3, inf, nan])"
>>> a = str_to_array(s)
"""
import numpy as np
# Need to make sure eval() knows about inf and nan.
# This also assumes default printoptions for NumPy.
from numpy import inf, nan
if s.startswith(u'array'):
# Remove array( and )
s = s[6:-1]
if s.startswith(u'['):
a = np.array(eval(s), dtype=float)
else:
# Assume its a regular float. Force 1D so we can index into it.
a = np.atleast_1d(float(s))
return a
def float_doctest(sphinx_shell, args, input_lines, found, submitted):
"""
Doctest which allow the submitted output to vary slightly from the input.
Here is how it might appear in an rst file:
.. code-block:: rst
.. ipython::
@doctest float
In [1]: 0.1 + 0.2
Out[1]: 0.3
"""
import numpy as np
if len(args) == 2:
rtol = 1e-05
atol = 1e-08
else:
# Both must be specified if any are specified.
try:
rtol = float(args[2])
atol = float(args[3])
except IndexError:
e = ("Both `rtol` and `atol` must be specified "
"if either are specified: {0}".format(args))
raise IndexError(e)
try:
submitted = str_to_array(submitted)
found = str_to_array(found)
except:
# For example, if the array is huge and there are ellipsis in it.
error = True
else:
found_isnan = np.isnan(found)
submitted_isnan = np.isnan(submitted)
error = not np.allclose(found_isnan, submitted_isnan)
error |= not np.allclose(found[~found_isnan],
submitted[~submitted_isnan],
rtol=rtol, atol=atol)
TAB = ' ' * 4
directive = sphinx_shell.directive
if directive is None:
source = 'Unavailable'
content = 'Unavailable'
else:
source = directive.state.document.current_source
# Add tabs and make into a single string.
content = '\n'.join([TAB + line for line in directive.content])
if error:
e = ('doctest float comparison failure\n\n'
'Document source: {0}\n\n'
'Raw content: \n{1}\n\n'
'On input line(s):\n{TAB}{2}\n\n'
'we found output:\n{TAB}{3}\n\n'
'instead of the expected:\n{TAB}{4}\n\n')
e = e.format(source, content, '\n'.join(input_lines), repr(found),
repr(submitted), TAB=TAB)
raise RuntimeError(e)
# dict of allowable doctest handlers. The key represents the first argument
# that must be given to @doctest in order to activate the handler.
doctests = {
'float': float_doctest,
}
|
