/usr/lib/python2.7/dist-packages/IPython/sphinxext/custom_doctests.py is in python-ipython 5.1.0-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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,
}
|