TST, DOC: enable refguide_check

* ported the refguide_check module from SciPy for usage
in NumPy docstring execution/ verification; added the
refguide_check run to Azure Mac OS CI

* adjusted NumPy docstrings such that refguide_check passes

1 files changed, 97 insertions, 102 deletions

diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
index 8768cbe56..8a8efddf3 100644
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -160,9 +160,9 @@ def zeros_like(a, dtype=None, order='K', subok=True):
 
     >>> y = np.arange(3, dtype=float)
     >>> y
-    array([ 0.,  1.,  2.])
+    array([0., 1., 2.])
     >>> np.zeros_like(y)
-    array([ 0.,  0.,  0.])
+    array([0.,  0.,  0.])
 
     """
     res = empty_like(a, dtype=dtype, order=order, subok=subok)
@@ -205,19 +205,19 @@ def ones(shape, dtype=None, order='C'):
     Examples
     --------
     >>> np.ones(5)
-    array([ 1.,  1.,  1.,  1.,  1.])
+    array([1., 1., 1., 1., 1.])
 
     >>> np.ones((5,), dtype=int)
     array([1, 1, 1, 1, 1])
 
     >>> np.ones((2, 1))
-    array([[ 1.],
-           [ 1.]])
+    array([[1.],
+           [1.]])
 
     >>> s = (2,2)
     >>> np.ones(s)
-    array([[ 1.,  1.],
-           [ 1.,  1.]])
+    array([[1.,  1.],
+           [1.,  1.]])
 
     """
     a = empty(shape, dtype, order)
@@ -280,9 +280,9 @@ def ones_like(a, dtype=None, order='K', subok=True):
 
     >>> y = np.arange(3, dtype=float)
     >>> y
-    array([ 0.,  1.,  2.])
+    array([0., 1., 2.])
     >>> np.ones_like(y)
-    array([ 1.,  1.,  1.])
+    array([1.,  1.,  1.])
 
     """
     res = empty_like(a, dtype=dtype, order=order, subok=subok)
@@ -323,8 +323,8 @@ def full(shape, fill_value, dtype=None, order='C'):
     Examples
     --------
     >>> np.full((2, 2), np.inf)
-    array([[ inf,  inf],
-           [ inf,  inf]])
+    array([[inf, inf],
+           [inf, inf]])
     >>> np.full((2, 2), 10)
     array([[10, 10],
            [10, 10]])
@@ -385,13 +385,13 @@ def full_like(a, fill_value, dtype=None, order='K', subok=True):
     >>> np.full_like(x, 0.1)
     array([0, 0, 0, 0, 0, 0])
     >>> np.full_like(x, 0.1, dtype=np.double)
-    array([ 0.1,  0.1,  0.1,  0.1,  0.1,  0.1])
+    array([0.1, 0.1, 0.1, 0.1, 0.1, 0.1])
     >>> np.full_like(x, np.nan, dtype=np.double)
-    array([ nan,  nan,  nan,  nan,  nan,  nan])
+    array([nan, nan, nan, nan, nan, nan])
 
     >>> y = np.arange(6, dtype=np.double)
     >>> np.full_like(y, 0.1)
-    array([ 0.1,  0.1,  0.1,  0.1,  0.1,  0.1])
+    array([0.1,  0.1,  0.1,  0.1,  0.1,  0.1])
 
     """
     res = empty_like(a, dtype=dtype, order=order, subok=subok)
@@ -620,8 +620,8 @@ def ascontiguousarray(a, dtype=None):
     --------
     >>> x = np.arange(6).reshape(2,3)
     >>> np.ascontiguousarray(x, dtype=np.float32)
-    array([[ 0.,  1.,  2.],
-           [ 3.,  4.,  5.]], dtype=float32)
+    array([[0., 1., 2.],
+           [3., 4., 5.]], dtype=float32)
     >>> x.flags['C_CONTIGUOUS']
     True
 
@@ -802,7 +802,7 @@ def isfortran(a):
     >>> np.isfortran(a)
     False
 
-    >>> b = np.array([[1, 2, 3], [4, 5, 6]], order='FORTRAN')
+    >>> b = np.array([[1, 2, 3], [4, 5, 6]], order='F')
     >>> b
     array([[1, 2, 3],
            [4, 5, 6]])
@@ -987,11 +987,11 @@ def correlate(a, v, mode='valid'):
     Examples
     --------
     >>> np.correlate([1, 2, 3], [0, 1, 0.5])
-    array([ 3.5])
+    array([3.5])
     >>> np.correlate([1, 2, 3], [0, 1, 0.5], "same")
-    array([ 2. ,  3.5,  3. ])
+    array([2. ,  3.5,  3. ])
     >>> np.correlate([1, 2, 3], [0, 1, 0.5], "full")
-    array([ 0.5,  2. ,  3.5,  3. ,  0. ])
+    array([0.5,  2. ,  3.5,  3. ,  0. ])
 
     Using complex sequences:
 
@@ -1087,20 +1087,20 @@ def convolve(a, v, mode='full'):
     before "sliding" the two across one another:
 
     >>> np.convolve([1, 2, 3], [0, 1, 0.5])
-    array([ 0. ,  1. ,  2.5,  4. ,  1.5])
+    array([0. , 1. , 2.5, 4. , 1.5])
 
     Only return the middle values of the convolution.
     Contains boundary effects, where zeros are taken
     into account:
 
     >>> np.convolve([1,2,3],[0,1,0.5], 'same')
-    array([ 1. ,  2.5,  4. ])
+    array([1. ,  2.5,  4. ])
 
     The two arrays are of the same length, so there
     is only one position where they completely overlap:
 
     >>> np.convolve([1,2,3],[0,1,0.5], 'valid')
-    array([ 2.5])
+    array([2.5])
 
     """
     a, v = array(a, copy=False, ndmin=1), array(v, copy=False, ndmin=1)
@@ -1176,11 +1176,11 @@ def outer(a, b, out=None):
            [-2., -1.,  0.,  1.,  2.]])
     >>> im = np.outer(1j*np.linspace(2, -2, 5), np.ones((5,)))
     >>> im
-    array([[ 0.+2.j,  0.+2.j,  0.+2.j,  0.+2.j,  0.+2.j],
-           [ 0.+1.j,  0.+1.j,  0.+1.j,  0.+1.j,  0.+1.j],
-           [ 0.+0.j,  0.+0.j,  0.+0.j,  0.+0.j,  0.+0.j],
-           [ 0.-1.j,  0.-1.j,  0.-1.j,  0.-1.j,  0.-1.j],
-           [ 0.-2.j,  0.-2.j,  0.-2.j,  0.-2.j,  0.-2.j]])
+    array([[0.+2.j, 0.+2.j, 0.+2.j, 0.+2.j, 0.+2.j],
+           [0.+1.j, 0.+1.j, 0.+1.j, 0.+1.j, 0.+1.j],
+           [0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j],
+           [0.-1.j, 0.-1.j, 0.-1.j, 0.-1.j, 0.-1.j],
+           [0.-2.j, 0.-2.j, 0.-2.j, 0.-2.j, 0.-2.j]])
     >>> grid = rl + im
     >>> grid
     array([[-2.+2.j, -1.+2.j,  0.+2.j,  1.+2.j,  2.+2.j],
@@ -1193,9 +1193,9 @@ def outer(a, b, out=None):
 
     >>> x = np.array(['a', 'b', 'c'], dtype=object)
     >>> np.outer(x, [1, 2, 3])
-    array([[a, aa, aaa],
-           [b, bb, bbb],
-           [c, cc, ccc]], dtype=object)
+    array([['a', 'aa', 'aaa'],
+           ['b', 'bb', 'bbb'],
+           ['c', 'cc', 'ccc']], dtype=object)
 
     """
     a = asarray(a)
@@ -1264,11 +1264,11 @@ def tensordot(a, b, axes=2):
     >>> c.shape
     (5, 2)
     >>> c
-    array([[ 4400.,  4730.],
-           [ 4532.,  4874.],
-           [ 4664.,  5018.],
-           [ 4796.,  5162.],
-           [ 4928.,  5306.]])
+    array([[4400., 4730.],
+           [4532., 4874.],
+           [4664., 5018.],
+           [4796., 5162.],
+           [4928., 5306.]])
     >>> # A slower but equivalent way of computing the same...
     >>> d = np.zeros((5,2))
     >>> for i in range(5):
@@ -1294,40 +1294,40 @@ def tensordot(a, b, axes=2):
             [3, 4]],
            [[5, 6],
             [7, 8]]])
-    array([[a, b],
-           [c, d]], dtype=object)
+    array([['a', 'b'],
+           ['c', 'd']], dtype=object)
 
     >>> np.tensordot(a, A) # third argument default is 2 for double-contraction
-    array([abbcccdddd, aaaaabbbbbbcccccccdddddddd], dtype=object)
+    array(['abbcccdddd', 'aaaaabbbbbbcccccccdddddddd'], dtype=object)
 
     >>> np.tensordot(a, A, 1)
-    array([[[acc, bdd],
-            [aaacccc, bbbdddd]],
-           [[aaaaacccccc, bbbbbdddddd],
-            [aaaaaaacccccccc, bbbbbbbdddddddd]]], dtype=object)
+    array([[['acc', 'bdd'],
+            ['aaacccc', 'bbbdddd']],
+           [['aaaaacccccc', 'bbbbbdddddd'],
+            ['aaaaaaacccccccc', 'bbbbbbbdddddddd']]], dtype=object)
 
     >>> np.tensordot(a, A, 0) # tensor product (result too long to incl.)
-    array([[[[[a, b],
-              [c, d]],
+    array([[[[['a', 'b'],
+              ['c', 'd']],
               ...
 
     >>> np.tensordot(a, A, (0, 1))
-    array([[[abbbbb, cddddd],
-            [aabbbbbb, ccdddddd]],
-           [[aaabbbbbbb, cccddddddd],
-            [aaaabbbbbbbb, ccccdddddddd]]], dtype=object)
+    array([[['abbbbb', 'cddddd'],
+            ['aabbbbbb', 'ccdddddd']],
+           [['aaabbbbbbb', 'cccddddddd'],
+            ['aaaabbbbbbbb', 'ccccdddddddd']]], dtype=object)
 
     >>> np.tensordot(a, A, (2, 1))
-    array([[[abb, cdd],
-            [aaabbbb, cccdddd]],
-           [[aaaaabbbbbb, cccccdddddd],
-            [aaaaaaabbbbbbbb, cccccccdddddddd]]], dtype=object)
+    array([[['abb', 'cdd'],
+            ['aaabbbb', 'cccdddd']],
+           [['aaaaabbbbbb', 'cccccdddddd'],
+            ['aaaaaaabbbbbbbb', 'cccccccdddddddd']]], dtype=object)
 
     >>> np.tensordot(a, A, ((0, 1), (0, 1)))
-    array([abbbcccccddddddd, aabbbbccccccdddddddd], dtype=object)
+    array(['abbbcccccddddddd', 'aabbbbccccccdddddddd'], dtype=object)
 
     >>> np.tensordot(a, A, ((2, 1), (1, 0)))
-    array([acccbbdddd, aaaaacccccccbbbbbbdddddddd], dtype=object)
+    array(['acccbbdddd', 'aaaaacccccccbbbbbbdddddddd'], dtype=object)
 
     """
     try:
@@ -1780,7 +1780,7 @@ def cross(a, b, axisa=-1, axisb=-1, axisc=-1, axis=None):
     >>> x = [1,2]
     >>> y = [4,5]
     >>> np.cross(x, y)
-    -3
+    array(-3)
 
     Multiple vector cross-products. Note that the direction of the cross
     product vector is defined by the `right-hand rule`.
@@ -2097,10 +2097,10 @@ def isscalar(num):
     NumPy supports PEP 3141 numbers:
 
     >>> from fractions import Fraction
-    >>> isscalar(Fraction(5, 17))
+    >>> np.isscalar(Fraction(5, 17))
     True
     >>> from numbers import Number
-    >>> isscalar(Number())
+    >>> np.isscalar(Number())
     True
 
     """
@@ -2339,9 +2339,9 @@ def identity(n, dtype=None):
     Examples
     --------
     >>> np.identity(3)
-    array([[ 1.,  0.,  0.],
-           [ 0.,  1.,  0.],
-           [ 0.,  0.,  1.]])
+    array([[1.,  0.,  0.],
+           [0.,  1.,  0.],
+           [0.,  0.,  1.]])
 
     """
     from numpy import eye
@@ -2487,23 +2487,23 @@ def isclose(a, b, rtol=1.e-5, atol=1.e-8, equal_nan=False):
     Examples
     --------
     >>> np.isclose([1e10,1e-7], [1.00001e10,1e-8])
-    array([True, False])
+    array([ True, False])
     >>> np.isclose([1e10,1e-8], [1.00001e10,1e-9])
-    array([True, True])
+    array([ True, True])
     >>> np.isclose([1e10,1e-8], [1.0001e10,1e-9])
-    array([False, True])
+    array([False,  True])
     >>> np.isclose([1.0, np.nan], [1.0, np.nan])
-    array([True, False])
+    array([ True, False])
     >>> np.isclose([1.0, np.nan], [1.0, np.nan], equal_nan=True)
-    array([True, True])
+    array([ True, True])
     >>> np.isclose([1e-8, 1e-7], [0.0, 0.0])
-    array([ True, False], dtype=bool)
+    array([ True, False])
     >>> np.isclose([1e-100, 1e-7], [0.0, 0.0], atol=0.0)
-    array([False, False], dtype=bool)
+    array([False, False])
     >>> np.isclose([1e-10, 1e-10], [1e-20, 0.0])
-    array([ True,  True], dtype=bool)
+    array([ True,  True])
     >>> np.isclose([1e-10, 1e-10], [1e-20, 0.999999e-10], atol=0.0)
-    array([False,  True], dtype=bool)
+    array([False,  True])
     """
     def within_tol(x, y, atol, rtol):
         with errstate(invalid='ignore'):
@@ -2710,11 +2710,9 @@ def seterr(all=None, divide=None, over=None, under=None, invalid=None):
     --------
     >>> old_settings = np.seterr(all='ignore')  #seterr to known value
     >>> np.seterr(over='raise')
-    {'over': 'ignore', 'divide': 'ignore', 'invalid': 'ignore',
-     'under': 'ignore'}
+    {'divide': 'ignore', 'over': 'ignore', 'under': 'ignore', 'invalid': 'ignore'}
     >>> np.seterr(**old_settings)  # reset to default
-    {'over': 'raise', 'divide': 'ignore', 'invalid': 'ignore',
-     'under': 'ignore'}
+    {'divide': 'ignore', 'over': 'raise', 'under': 'ignore', 'invalid': 'ignore'}
 
     >>> np.int16(32000) * np.int16(3)
     30464
@@ -2724,11 +2722,11 @@ def seterr(all=None, divide=None, over=None, under=None, invalid=None):
       File "<stdin>", line 1, in <module>
     FloatingPointError: overflow encountered in short_scalars
 
+    >>> from collections import OrderedDict
     >>> old_settings = np.seterr(all='print')
-    >>> np.geterr()
-    {'over': 'print', 'divide': 'print', 'invalid': 'print', 'under': 'print'}
+    >>> OrderedDict(np.geterr())
+    OrderedDict([('divide', 'print'), ('over', 'print'), ('under', 'print'), ('invalid', 'print')])
     >>> np.int16(32000) * np.int16(3)
-    Warning: overflow encountered in short_scalars
     30464
 
     """
@@ -2779,18 +2777,17 @@ def geterr():
 
     Examples
     --------
-    >>> np.geterr()
-    {'over': 'warn', 'divide': 'warn', 'invalid': 'warn',
-    'under': 'ignore'}
+    >>> from collections import OrderedDict
+    >>> sorted(np.geterr().items())
+    [('divide', 'warn'), ('invalid', 'warn'), ('over', 'warn'), ('under', 'ignore')]
     >>> np.arange(3.) / np.arange(3.)
-    array([ NaN,   1.,   1.])
+    array([nan,  1.,  1.])
 
     >>> oldsettings = np.seterr(all='warn', over='raise')
-    >>> np.geterr()
-    {'over': 'raise', 'divide': 'warn', 'invalid': 'warn', 'under': 'warn'}
+    >>> OrderedDict(sorted(np.geterr().items()))
+    OrderedDict([('divide', 'warn'), ('invalid', 'warn'), ('over', 'raise'), ('under', 'warn')])
     >>> np.arange(3.) / np.arange(3.)
-    __main__:1: RuntimeWarning: invalid value encountered in divide
-    array([ NaN,   1.,   1.])
+    array([nan,  1.,  1.])
 
     """
     maskvalue = umath.geterrobj()[1]
@@ -2897,15 +2894,16 @@ def seterrcall(func):
 
     >>> saved_handler = np.seterrcall(err_handler)
     >>> save_err = np.seterr(all='call')
+    >>> from collections import OrderedDict
 
     >>> np.array([1, 2, 3]) / 0.0
     Floating point error (divide by zero), with flag 1
-    array([ Inf,  Inf,  Inf])
+    array([inf, inf, inf])
 
     >>> np.seterrcall(saved_handler)
     <function err_handler at 0x...>
-    >>> np.seterr(**save_err)
-    {'over': 'call', 'divide': 'call', 'invalid': 'call', 'under': 'call'}
+    >>> OrderedDict(sorted(np.seterr(**save_err).items()))
+    OrderedDict([('divide', 'call'), ('invalid', 'call'), ('over', 'call'), ('under', 'call')])
 
     Log error message:
 
@@ -2919,14 +2917,13 @@ def seterrcall(func):
     >>> save_err = np.seterr(all='log')
 
     >>> np.array([1, 2, 3]) / 0.0
-    LOG: Warning: divide by zero encountered in divide
-    <BLANKLINE>
-    array([ Inf,  Inf,  Inf])
+    LOG: Warning: divide by zero encountered in true_divide
+    array([inf, inf, inf])
 
     >>> np.seterrcall(saved_handler)
-    <__main__.Log object at 0x...>
-    >>> np.seterr(**save_err)
-    {'over': 'log', 'divide': 'log', 'invalid': 'log', 'under': 'log'}
+    <numpy.core.numeric.Log object at 0x...>
+    >>> OrderedDict(sorted(np.seterr(**save_err).items()))
+    OrderedDict([('divide', 'log'), ('invalid', 'log'), ('over', 'log'), ('under', 'log')])
 
     """
     if func is not None and not isinstance(func, collections_abc.Callable):
@@ -2975,7 +2972,7 @@ def geterrcall():
     >>> oldhandler = np.seterrcall(err_handler)
     >>> np.array([1, 2, 3]) / 0.0
     Floating point error (divide by zero), with flag 1
-    array([ Inf,  Inf,  Inf])
+    array([inf, inf, inf])
 
     >>> cur_handler = np.geterrcall()
     >>> cur_handler is err_handler
@@ -3023,15 +3020,14 @@ class errstate(object):
 
     Examples
     --------
+    >>> from collections import OrderedDict
     >>> olderr = np.seterr(all='ignore')  # Set error handling to known state.
 
     >>> np.arange(3) / 0.
-    array([ NaN,  Inf,  Inf])
+    array([nan, inf, inf])
     >>> with np.errstate(divide='warn'):
     ...     np.arange(3) / 0.
-    ...
-    __main__:2: RuntimeWarning: divide by zero encountered in divide
-    array([ NaN,  Inf,  Inf])
+    array([nan, inf, inf])
 
     >>> np.sqrt(-1)
     nan
@@ -3043,9 +3039,8 @@ class errstate(object):
 
     Outside the context the error handling behavior has not changed:
 
-    >>> np.geterr()
-    {'over': 'warn', 'divide': 'warn', 'invalid': 'warn',
-    'under': 'ignore'}
+    >>> OrderedDict(sorted(np.geterr().items()))
+    OrderedDict([('divide', 'ignore'), ('invalid', 'ignore'), ('over', 'ignore'), ('under', 'ignore')])
 
     """
     # Note that we don't want to run the above doctests because they will fail