Merge branch 'master' into deprecate-float-order

5 files changed, 150 insertions, 32 deletions

diff --git a/doc/DISTUTILS.rst.txt b/doc/DISTUTILS.rst.txt
index 515fc871b..3cb812176 100644
--- a/doc/DISTUTILS.rst.txt
+++ b/doc/DISTUTILS.rst.txt
@@ -300,8 +300,72 @@ in writing setup scripts:
 Template files
 --------------
 
-XXX: Describe how files with extensions ``.f.src``, ``.pyf.src``,
-``.c.src``, etc. are pre-processed by the ``build_src`` command.
+NumPy Distutils preprocesses C source files (extension: :file:`.c.src`) written
+in a custom templating language to generate C code. The :c:data:`@` symbol is
+used to wrap macro-style variables to empower a string substitution mechansim
+that might describe (for instance) a set of data types.
+
+As a more detailed scenario, a loop in the NumPy C source code may
+have a :c:data:`@TYPE@` variable, targeted for string substitution,
+which is preprocessed to a number of otherwise identical loops with
+several strings such as :c:data:`INT, LONG, UINT, ULONG`. The :c:data:`@TYPE@`
+style syntax thus reduces code duplication and maintenance burden by
+mimicking languages that have generic type support. By convention,
+and as required by the preprocessor, generically typed blocks are preceded
+by comment blocks that enumerate the intended string substitutions.
+
+The template language blocks are delimited by :c:data:`/**begin repeat`
+and :c:data:`/**end repeat**/` lines, which may also be nested using
+consecutively numbered delimiting lines such as :c:data:`/**begin repeat1`
+and :c:data:`/**end repeat1**/`. String replacement specifications are started
+and terminated using :c:data:`#`. This may be clearer in the following
+template source example:
+
+.. code-block:: C
+   :linenos:
+   :emphasize-lines: 3, 13, 29, 31
+
+    /* TIMEDELTA to non-float types */
+
+    /**begin repeat
+     *
+     * #TOTYPE = BYTE, UBYTE, SHORT, USHORT, INT, UINT, LONG, ULONG,
+     *           LONGLONG, ULONGLONG, DATETIME,
+     *           TIMEDELTA#
+     * #totype = npy_byte, npy_ubyte, npy_short, npy_ushort, npy_int, npy_uint,
+     *           npy_long, npy_ulong, npy_longlong, npy_ulonglong,
+     *           npy_datetime, npy_timedelta#
+     */
+
+    /**begin repeat1
+     *
+     * #FROMTYPE = TIMEDELTA#
+     * #fromtype = npy_timedelta#
+     */
+    static void
+    @FROMTYPE@_to_@TOTYPE@(void *input, void *output, npy_intp n,
+            void *NPY_UNUSED(aip), void *NPY_UNUSED(aop))
+    {
+        const @fromtype@ *ip = input;
+        @totype@ *op = output;
+
+        while (n--) {
+            *op++ = (@totype@)*ip++;
+        }
+    }
+    /**end repeat1**/
+
+    /**end repeat**/
+
+The preprocessing of generically typed C source files (whether in NumPy
+proper or in any third party package using NumPy Distutils) is performed
+by `conv_template.py`_.
+The type specific C files generated (extension: :file:`.c`) by these modules
+during the build process are ready to be compiled. This form
+of generic typing is also supported for C header files (preprocessed to
+produce :file:`.h` files).
+
+.. _conv_template.py: https://github.com/numpy/numpy/blob/master/numpy/distutils/conv_template.py
 
 Useful functions in ``numpy.distutils.misc_util``
 -------------------------------------------------
diff --git a/doc/release/1.17.0-notes.rst b/doc/release/1.17.0-notes.rst
index 6440cdd60..b9b27da79 100644
--- a/doc/release/1.17.0-notes.rst
+++ b/doc/release/1.17.0-notes.rst
@@ -27,6 +27,12 @@ deprecated, and in future will raise a ``TypeError``.
 Similarly, passing a float like ``0.5`` in place of an integer will now raise a
 ``TypeError`` instead of the previous ``ValueError``.
 
+Deprecate ``numpy.distutils.exec_command`` and ``numpy.distutils.temp_file_name``
+---------------------------------------------------------------------------------
+The internal use of these functions has been refactored and there are better
+alternatives. Relace ``exec_command`` with `subprocess.Popen` and
+``temp_file_name`` with `tempfile.mkstemp`.
+
 
 Future Changes
 ==============
@@ -47,7 +53,6 @@ now be rounded up instead of down, changing the last bit (ULP) of the result.
 
 Signed zero when using divmod
 -----------------------------
-
 Starting in version 1.12.0, numpy incorrectly returned a negatively signed zero
 when using the ``divmod`` and ``floor_divide`` functions when the result was
 zero. For example::
@@ -61,6 +66,13 @@ zero::
    >>> np.zeros(10)//1
    array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0.])
 
+Do not lookup ``__buffer__`` attribute in `numpy.frombuffer`
+------------------------------------------------------------
+Looking up ``__buffer__`` attribute in `numpy.frombuffer` was undocumented and
+non-functional. This code was removed. If needed, use
+``frombuffer(memoryview(obj), ...)`` instead.
+
+
 C API changes
 =============
 
@@ -97,7 +109,6 @@ available bits add zero padding. Negative counts trim bits off the end instead
 of counting from the beginning. None counts implement the existing behavior of
 unpacking everything.
 
-
 ``np.linalg.svd`` and ``np.linalg.pinv`` can be faster on hermitian inputs
 --------------------------------------------------------------------------
 These functions now accept a ``hermitian`` argument, matching the one added
@@ -122,7 +133,6 @@ tolerances.
 
 Replacement of the `fftpack`-based FFT module by the `pocketfft` library
 ------------------------------------------------------------------------
-
 Both implementations have the same ancestor (Fortran77 `FFTPACK` by Paul N.
 Swarztrauber), but `pocketfft` contains additional modifications which
 improve both accuracy and performance in some circumstances. For FFT lengths
@@ -172,7 +182,6 @@ Changes
 
 ``median`` and ``percentile`` family of functions no longer warn about ``nan``
 ------------------------------------------------------------------------------
-
 `numpy.median`, `numpy.percentile`, and `numpy.quantile` used to emit a
 ``RuntimeWarning`` when encountering an `numpy.nan`. Since they return the
 ``nan`` value, the warning is redundant and has been removed.
@@ -189,4 +198,8 @@ of NumPy functions on non-NumPy arrays, as described in `NEP 18`_. The feature
 was available for testing with NumPy 1.16 if appropriate environment variables
 are set, but is now always enabled.
 
+``__array_interface__`` offset now works as documented
+------------------------------------------------------
+The interface may use an ``offset`` value that was mistakenly ignored.
+
 .. _`NEP 18` : http://www.numpy.org/neps/nep-0018-array-function-protocol.html
diff --git a/doc/scipy-sphinx-theme b/doc/scipy-sphinx-theme
-Subproject d990ab9134199f6496b9ac8567f10791f04a720
+Subproject f0d96ae2bf3b010ce53adadde1e38997497a513
diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst
index 1a3592781..ee2be9e07 100644
--- a/doc/source/reference/c-api.array.rst
+++ b/doc/source/reference/c-api.array.rst
@@ -821,17 +821,17 @@ Dealing with types
 General check of Python Type
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. c:function:: PyArray_Check(op)
+.. c:function:: PyArray_Check(PyObject *op)
 
     Evaluates true if *op* is a Python object whose type is a sub-type
     of :c:data:`PyArray_Type`.
 
-.. c:function:: PyArray_CheckExact(op)
+.. c:function:: PyArray_CheckExact(PyObject *op)
 
     Evaluates true if *op* is a Python object with type
     :c:data:`PyArray_Type`.
 
-.. c:function:: PyArray_HasArrayInterface(op, out)
+.. c:function:: PyArray_HasArrayInterface(PyObject *op, PyObject *out)
 
     If ``op`` implements any part of the array interface, then ``out``
     will contain a new reference to the newly created ndarray using
@@ -3261,19 +3261,19 @@ Memory management
     Macros to allocate, free, and reallocate memory. These macros are used
     internally to create arrays.
 
-.. c:function:: npy_intp*  PyDimMem_NEW(nd)
+.. c:function:: npy_intp*  PyDimMem_NEW(int nd)
 
-.. c:function:: PyDimMem_FREE(npy_intp* ptr)
+.. c:function:: PyDimMem_FREE(char* ptr)
 
-.. c:function:: npy_intp* PyDimMem_RENEW(npy_intp* ptr, npy_intp newnd)
+.. c:function:: npy_intp* PyDimMem_RENEW(void* ptr, size_t newnd)
 
     Macros to allocate, free, and reallocate dimension and strides memory.
 
-.. c:function:: PyArray_malloc(nbytes)
+.. c:function:: void* PyArray_malloc(size_t nbytes)
 
-.. c:function:: PyArray_free(ptr)
+.. c:function:: PyArray_free(void* ptr)
 
-.. c:function:: PyArray_realloc(ptr, nbytes)
+.. c:function:: void* PyArray_realloc(npy_intp* ptr, size_t nbytes)
 
     These macros use different memory allocators, depending on the
     constant :c:data:`NPY_USE_PYMEM`. The system malloc is used when
@@ -3475,31 +3475,31 @@ Other constants
 Miscellaneous Macros
 ^^^^^^^^^^^^^^^^^^^^
 
-.. c:function:: PyArray_SAMESHAPE(a1, a2)
+.. c:function:: PyArray_SAMESHAPE(PyArrayObject *a1, PyArrayObject *a2)
 
     Evaluates as True if arrays *a1* and *a2* have the same shape.
 
-.. c:function:: PyArray_MAX(a,b)
+.. c:macro:: PyArray_MAX(a,b)
 
     Returns the maximum of *a* and *b*. If (*a*) or (*b*) are
     expressions they are evaluated twice.
 
-.. c:function:: PyArray_MIN(a,b)
+.. c:macro:: PyArray_MIN(a,b)
 
     Returns the minimum of *a* and *b*. If (*a*) or (*b*) are
     expressions they are evaluated twice.
 
-.. c:function:: PyArray_CLT(a,b)
+.. c:macro:: PyArray_CLT(a,b)
 
-.. c:function:: PyArray_CGT(a,b)
+.. c:macro:: PyArray_CGT(a,b)
 
-.. c:function:: PyArray_CLE(a,b)
+.. c:macro:: PyArray_CLE(a,b)
 
-.. c:function:: PyArray_CGE(a,b)
+.. c:macro:: PyArray_CGE(a,b)
 
-.. c:function:: PyArray_CEQ(a,b)
+.. c:macro:: PyArray_CEQ(a,b)
 
-.. c:function:: PyArray_CNE(a,b)
+.. c:macro:: PyArray_CNE(a,b)
 
     Implements the complex comparisons between two complex numbers
     (structures with a real and imag member) using NumPy's definition
diff --git a/doc/source/reference/c-api.dtype.rst b/doc/source/reference/c-api.dtype.rst
index 9ac46b284..72e908861 100644
--- a/doc/source/reference/c-api.dtype.rst
+++ b/doc/source/reference/c-api.dtype.rst
@@ -308,13 +308,45 @@ to the front of the integer name.
 
     (unsigned) char
 
-.. c:type:: npy_(u)short
+.. c:type:: npy_short
 
-    (unsigned) short
+    short
 
-.. c:type:: npy_(u)int
+.. c:type:: npy_ushort
 
-    (unsigned) int
+    unsigned short
+
+.. c:type:: npy_uint
+
+    unsigned int
+
+.. c:type:: npy_int
+
+    int
+
+.. c:type:: npy_int16
+
+    16-bit integer
+
+.. c:type:: npy_uint16
+
+    16-bit unsigned integer
+
+.. c:type:: npy_int32
+
+    32-bit integer
+
+.. c:type:: npy_uint32
+
+    32-bit unsigned integer
+
+.. c:type:: npy_int64
+
+    64-bit integer
+
+.. c:type:: npy_uint64
+
+    64-bit unsigned integer
 
 .. c:type:: npy_(u)long
 
@@ -324,22 +356,31 @@ to the front of the integer name.
 
     (unsigned long long int)
 
-.. c:type:: npy_(u)intp
+.. c:type:: npy_intp
 
-    (unsigned) Py_intptr_t (an integer that is the size of a pointer on
+    Py_intptr_t (an integer that is the size of a pointer on
+    the platform).
+
+.. c:type:: npy_uintp
+
+    unsigned Py_intptr_t (an integer that is the size of a pointer on
     the platform).
 
 
 (Complex) Floating point
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. c:type:: npy_half
+
+    16-bit float
+
 .. c:type:: npy_(c)float
 
-    float
+    32-bit float
 
 .. c:type:: npy_(c)double
 
-    double
+    64-bit double
 
 .. c:type:: npy_(c)longdouble