Merge pull request #4905 from juliantaylor/doc-update

documentation updates

12 files changed, 117 insertions, 39 deletions

diff --git a/.gitignore b/.gitignore
index abba1fdc0..3952be1fe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,12 @@
 *.tmp
 *.vim
 tags
+cscope.out
+# gnu global
+GPATH
+GRTAGS
+GSYMS
+GTAGS
 
 # Compiled source #
 ###################
@@ -123,7 +129,7 @@ numpy/core/src/private/npy_partition.h
 numpy/core/src/private/scalarmathmodule.h
 numpy/core/src/scalarmathmodule.c
 numpy/core/src/umath/funcs.inc
-numpy/core/src/umath/loops.c
+numpy/core/src/umath/loops.[ch]
 numpy/core/src/umath/operand_flag_tests.c
 numpy/core/src/umath/simd.inc
 numpy/core/src/umath/struct_ufunc_test.c
diff --git a/doc/HOWTO_DOCUMENT.rst.txt b/doc/HOWTO_DOCUMENT.rst.txt
index 2854b6b90..650f7d35c 100644
--- a/doc/HOWTO_DOCUMENT.rst.txt
+++ b/doc/HOWTO_DOCUMENT.rst.txt
@@ -30,14 +30,14 @@ A Guide to NumPy/SciPy Documentation
 
 Overview
 --------
-In general, we follow the standard Python style conventions as described here:
- * `Style Guide for C Code <http://www.python.org/peps/pep-0007.html>`_
- * `Style Guide for Python Code <http://www.python.org/peps/pep-0008.html>`_
- * `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
+We mostly follow the standard Python style conventions as described here:
+ * `Style Guide for C Code <http://python.org/dev/peps/pep-0007/>`_
+ * `Style Guide for Python Code <http://python.org/dev/peps/pep-0008/>`_
+ * `Docstring Conventions <http://python.org/dev/peps/pep-0257/>`_
 
 Additional PEPs of interest regarding documentation of code:
- * `Docstring Processing Framework <http://www.python.org/peps/pep-0256.html>`_
- * `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
+ * `Docstring Processing Framework <http://python.org/dev/peps/pep-0256/>`_
+ * `Docutils Design Specification <http://python.org/dev/peps/pep-0258/>`_
 
 Use a code checker:
  * `pylint <http://www.logilab.org/857>`_
diff --git a/doc/release/1.9.0-notes.rst b/doc/release/1.9.0-notes.rst
index 8d6308046..89acd353e 100644
--- a/doc/release/1.9.0-notes.rst
+++ b/doc/release/1.9.0-notes.rst
@@ -35,6 +35,8 @@ Future Changes
 * String version checks will break because, e.g., '1.9' > '1.10' is True. A
   NumpyVersion class has been added that can be used for such comparisons.
 * The diagonal and diag functions will return writeable views in 1.10.0
+* The `S` and/or `a` dtypes may be changed to represent Python strings
+  instead of bytes, in Python 3 these two types are very different.
 
 
 Compatibility notes
@@ -176,6 +178,11 @@ introduced in advanced indexing operations:
 
 * Indexing with more then one ellipsis (``...``) is deprecated.
 
+Non-integer reduction axis indexes are deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Non-integer axis indexes to reduction ufuncs like `add.reduce` or `sum` are
+deprecated.
+
 ``promote_types`` and string dtype
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ``promote_types`` function now returns a valid string length when given an
diff --git a/doc/source/reference/c-api.types-and-structures.rst b/doc/source/reference/c-api.types-and-structures.rst
index 4e32ab7be..95272c151 100644
--- a/doc/source/reference/c-api.types-and-structures.rst
+++ b/doc/source/reference/c-api.types-and-structures.rst
@@ -244,7 +244,7 @@ PyArrayDescr_Type
         Indicates that items of this data-type must be reference
         counted (using :cfunc:`Py_INCREF` and :cfunc:`Py_DECREF` ).
 
-    .. cvar:: NPY_ITEM_LISTPICKLE
+    .. cvar:: NPY_LIST_PICKLE
 
         Indicates arrays of this data-type must be converted to a list
         before pickling.
diff --git a/doc/source/reference/routines.array-manipulation.rst b/doc/source/reference/routines.array-manipulation.rst
index ca97bb479..81af0a315 100644
--- a/doc/source/reference/routines.array-manipulation.rst
+++ b/doc/source/reference/routines.array-manipulation.rst
@@ -54,6 +54,8 @@ Changing kind of array
    asmatrix
    asfarray
    asfortranarray
+   ascontiguousarray
+   asarray_chkfinite
    asscalar
    require
 
diff --git a/doc/source/reference/routines.ma.rst b/doc/source/reference/routines.ma.rst
index 5cb38e83f..66bcb1f1c 100644
--- a/doc/source/reference/routines.ma.rst
+++ b/doc/source/reference/routines.ma.rst
@@ -65,6 +65,8 @@ Inspecting the array
    ma.nonzero
    ma.shape
    ma.size
+   ma.is_masked
+   ma.is_mask
 
    ma.MaskedArray.data
    ma.MaskedArray.mask
@@ -141,6 +143,7 @@ Joining arrays
 
    ma.column_stack
    ma.concatenate
+   ma.append
    ma.dstack
    ma.hstack
    ma.vstack
diff --git a/doc/source/reference/routines.maskna.rst b/doc/source/reference/routines.maskna.rst
deleted file mode 100644
index 2910acbac..000000000
--- a/doc/source/reference/routines.maskna.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-NA-Masked Array Routines
-========================
-
-.. currentmodule:: numpy
-
-NA Values
----------
-.. autosummary::
-   :toctree: generated/
-
-   isna
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 86ea4b8b6..09311a536 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -4459,12 +4459,12 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('tolist',
 
 
 tobytesdoc = """
-    a.tostring(order='C')
+    a.{name}(order='C')
 
-    Construct a Python string containing the raw data bytes in the array.
+    Construct Python bytes containing the raw data bytes in the array.
 
-    Constructs a Python string showing a copy of the raw contents of
-    data memory. The string can be produced in either 'C' or 'Fortran',
+    Constructs Python bytes showing a copy of the raw contents of
+    data memory. The bytes object can be produced in either 'C' or 'Fortran',
     or 'Any' order (the default is 'C'-order). 'Any' order means C-order
     unless the F_CONTIGUOUS flag in the array is set, in which case it
     means 'Fortran' order.
@@ -4479,29 +4479,31 @@ tobytesdoc = """
 
     Returns
     -------
-    s : str
-        A Python string exhibiting a copy of `a`'s raw data.
+    s : bytes
+        Python bytes exhibiting a copy of `a`'s raw data.
 
     Examples
     --------
     >>> x = np.array([[0, 1], [2, 3]])
     >>> x.tobytes()
-    '\\x00\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x02\\x00\\x00\\x00\\x03\\x00\\x00\\x00'
+    b'\\x00\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x02\\x00\\x00\\x00\\x03\\x00\\x00\\x00'
     >>> x.tobytes('C') == x.tobytes()
     True
     >>> x.tobytes('F')
-    '\\x00\\x00\\x00\\x00\\x02\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x03\\x00\\x00\\x00'
+    b'\\x00\\x00\\x00\\x00\\x02\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x03\\x00\\x00\\x00'
 
     """
 
 add_newdoc('numpy.core.multiarray', 'ndarray',
-           ('tostring', tobytesdoc.format(deprecated=
+           ('tostring', tobytesdoc.format(name='tostring',
+                                          deprecated=
                                           'This function is a compatibility '
                                           'alias for tobytes. Despite its '
                                           'name it returns bytes not '
                                           'strings.')))
 add_newdoc('numpy.core.multiarray', 'ndarray',
-           ('tobytes', tobytesdoc.format(deprecated='.. versionadded:: 1.9.0')))
+           ('tobytes', tobytesdoc.format(name='tobytes',
+                                         deprecated='.. versionadded:: 1.9.0')))
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('trace',
     """
@@ -5519,6 +5521,8 @@ add_newdoc('numpy.core', 'ufunc', ('reduce',
         in the result as dimensions with size one. With this option,
         the result will broadcast correctly against the original `arr`.
 
+        .. versionadded:: 1.7.0
+
     Returns
     -------
     r : ndarray
diff --git a/numpy/core/tests/test_ufunc.py b/numpy/core/tests/test_ufunc.py
index b08f1e249..eacc266be 100644
--- a/numpy/core/tests/test_ufunc.py
+++ b/numpy/core/tests/test_ufunc.py
@@ -651,7 +651,6 @@ class TestUfunc(TestCase):
         a = np.array(1).view(MyArray)
         assert_(type(np.any(a)) is MyArray)
 
-
     def test_casting_out_param(self):
         # Test that it's possible to do casts on output
         a = np.ones((200, 100), np.int64)
@@ -1066,5 +1065,64 @@ class TestUfunc(TestCase):
         self.assertRaises(TypeError, np.add.at, values, [0, 1], 1)
         assert_array_equal(values, np.array(['a', 1], dtype=np.object))
 
+    def test_reduce_arguments(self):
+        f = np.add.reduce
+        d = np.ones((5,2), dtype=int)
+        o = np.ones((2,), dtype=d.dtype)
+        r = o * 5
+        assert_equal(f(d), r)
+        # a, axis=0, dtype=None, out=None, keepdims=False
+        assert_equal(f(d, axis=0), r)
+        assert_equal(f(d, 0), r)
+        assert_equal(f(d, 0, dtype=None), r)
+        assert_equal(f(d, 0, dtype='i'), r)
+        assert_equal(f(d, 0, 'i'), r)
+        assert_equal(f(d, 0, None), r)
+        assert_equal(f(d, 0, None, out=None), r)
+        assert_equal(f(d, 0, None, out=o), r)
+        assert_equal(f(d, 0, None, o), r)
+        assert_equal(f(d, 0, None, None), r)
+        assert_equal(f(d, 0, None, None, keepdims=False), r)
+        assert_equal(f(d, 0, None, None, True), r.reshape((1,) + r.shape))
+        # multiple keywords
+        assert_equal(f(d, axis=0, dtype=None, out=None, keepdims=False), r)
+        assert_equal(f(d, 0, dtype=None, out=None, keepdims=False), r)
+        assert_equal(f(d, 0, None, out=None, keepdims=False), r)
+
+        # too little
+        assert_raises(TypeError, f)
+        # too much
+        assert_raises(TypeError, f, d, 0, None, None, False, 1)
+        # invalid axis
+        assert_raises(TypeError, f, d, "invalid")
+        assert_raises(TypeError, f, d, axis="invalid")
+        assert_raises(TypeError, f, d, axis="invalid", dtype=None,
+                      keepdims=True)
+        # invalid dtype
+        assert_raises(TypeError, f, d, 0, "invalid")
+        assert_raises(TypeError, f, d, dtype="invalid")
+        assert_raises(TypeError, f, d, dtype="invalid", out=None)
+        # invalid out
+        assert_raises(TypeError, f, d, 0, None, "invalid")
+        assert_raises(TypeError, f, d, out="invalid")
+        assert_raises(TypeError, f, d, out="invalid", dtype=None)
+        # keepdims boolean, no invalid value
+        # assert_raises(TypeError, f, d, 0, None, None, "invalid")
+        # assert_raises(TypeError, f, d, keepdims="invalid", axis=0, dtype=None)
+        # invalid mix
+        assert_raises(TypeError, f, d, 0, keepdims="invalid", dtype="invalid",
+                     out=None)
+
+        # invalid keyord
+        assert_raises(TypeError, f, d, 0, keepdims=True, invalid="invalid",
+                      out=None)
+        assert_raises(TypeError, f, d, invalid=0)
+        assert_raises(TypeError, f, d, axis=0, dtype=None, keepdims=True,
+                      out=None, invalid=0)
+        assert_raises(TypeError, f, d, axis=0, dtype=None,
+                      out=None, invalid=0)
+        assert_raises(TypeError, f, d, axis=0, dtype=None, invalid=0)
+
+
 if __name__ == "__main__":
     run_module_suite()
diff --git a/numpy/ma/core.py b/numpy/ma/core.py
index 5684bf8fd..00164b851 100644
--- a/numpy/ma/core.py
+++ b/numpy/ma/core.py
@@ -5021,6 +5021,10 @@ class MaskedArray(ndarray):
     endwith : {True, False}, optional
         Whether missing values (if any) should be forced in the upper indices
         (at the end of the array) (True) or lower indices (at the beginning).
+        When the array contains unmasked values of the largest (or smallest if
+        False) representable value of the datatype the ordering of these values
+        and the masked values is undefined.  To enforce the masked values are
+        at the end (beginning) in this case one must sort the mask.
     fill_value : {var}, optional
         Value used internally for the masked values.
         If ``fill_value`` is not None, it supersedes ``endwith``.
diff --git a/numpy/testing/utils.py b/numpy/testing/utils.py
index 13c3e4610..bd184d922 100644
--- a/numpy/testing/utils.py
+++ b/numpy/testing/utils.py
@@ -222,7 +222,7 @@ def build_err_msg(arrays, err_msg, header='Items are not equal:',
 
 def assert_equal(actual,desired,err_msg='',verbose=True):
     """
-    Raise an assertion if two objects are not equal.
+    Raises an AssertionError if two objects are not equal.
 
     Given two objects (scalars, lists, tuples, dictionaries or numpy arrays),
     check that all elements of these objects are equal. An exception is raised
@@ -374,7 +374,8 @@ def print_assert_equal(test_string, actual, desired):
 
 def assert_almost_equal(actual,desired,decimal=7,err_msg='',verbose=True):
     """
-    Raise an assertion if two items are not equal up to desired precision.
+    Raises an AssertionError if two items are not equal up to desired
+    precision.
 
     .. note:: It is recommended to use one of `assert_allclose`,
               `assert_array_almost_equal_nulp` or `assert_array_max_ulp`
@@ -491,7 +492,8 @@ def assert_almost_equal(actual,desired,decimal=7,err_msg='',verbose=True):
 
 def assert_approx_equal(actual,desired,significant=7,err_msg='',verbose=True):
     """
-    Raise an assertion if two items are not equal up to significant digits.
+    Raises an AssertionError if two items are not equal up to significant
+    digits.
 
     .. note:: It is recommended to use one of `assert_allclose`,
               `assert_array_almost_equal_nulp` or `assert_array_max_ulp`
@@ -672,7 +674,7 @@ def assert_array_compare(comparison, x, y, err_msg='', verbose=True,
 
 def assert_array_equal(x, y, err_msg='', verbose=True):
     """
-    Raise an assertion if two array_like objects are not equal.
+    Raises an AssertionError if two array_like objects are not equal.
 
     Given two array_like objects, check that the shape is equal and all
     elements of these objects are equal. An exception is raised at
@@ -738,7 +740,8 @@ def assert_array_equal(x, y, err_msg='', verbose=True):
 
 def assert_array_almost_equal(x, y, decimal=6, err_msg='', verbose=True):
     """
-    Raise an assertion if two objects are not equal up to desired precision.
+    Raises an AssertionError if two objects are not equal up to desired
+    precision.
 
     .. note:: It is recommended to use one of `assert_allclose`,
               `assert_array_almost_equal_nulp` or `assert_array_max_ulp`
@@ -841,7 +844,8 @@ def assert_array_almost_equal(x, y, decimal=6, err_msg='', verbose=True):
 
 def assert_array_less(x, y, err_msg='', verbose=True):
     """
-    Raise an assertion if two array_like objects are not ordered by less than.
+    Raises an AssertionError if two array_like objects are not ordered by less
+    than.
 
     Given two array_like objects, check that the shape is equal and all
     elements of the first object are strictly smaller than those of the
@@ -1243,7 +1247,8 @@ def _assert_valid_refcount(op):
 def assert_allclose(actual, desired, rtol=1e-7, atol=0,
                     err_msg='', verbose=True):
     """
-    Raise an assertion if two objects are not equal up to desired tolerance.
+    Raises an AssertionError if two objects are not equal up to desired
+    tolerance.
 
     The test is equivalent to ``allclose(actual, desired, rtol, atol)``.
     It compares the difference between `actual` and `desired` to
diff --git a/site.cfg.example b/site.cfg.example
index 714ab6311..4a59f10e2 100644
--- a/site.cfg.example
+++ b/site.cfg.example
@@ -126,7 +126,7 @@
 # better performance.  Note that the AMD library has nothing to do with AMD
 # (Advanced Micro Devices), the CPU company.
 #
-# UMFPACK is not needed for numpy or scipy.
+# UMFPACK is not used by numpy.
 #
 #   http://www.cise.ufl.edu/research/sparse/umfpack/
 #   http://www.cise.ufl.edu/research/sparse/amd/
@@ -141,7 +141,7 @@
 # FFT libraries
 # -------------
 # There are two FFT libraries that we can configure here: FFTW (2 and 3) and djbfft.
-# Note that these libraries are not needed for numpy or scipy.
+# Note that these libraries are not used by for numpy or scipy.
 #
 #   http://fftw.org/
 #   http://cr.yp.to/djbfft.html