merge master into gufunc-signature-modification2

3 files changed, 59 insertions, 19 deletions

diff --git a/doc/neps/nep-0018-array-function-protocol.rst b/doc/neps/nep-0018-array-function-protocol.rst
index e7d433e37..e0f1113f6 100644
--- a/doc/neps/nep-0018-array-function-protocol.rst
+++ b/doc/neps/nep-0018-array-function-protocol.rst
@@ -7,10 +7,9 @@ NEP 18 — A dispatch mechanism for NumPy's high level array functions
 :Author: Marten van Kerkwijk <mhvk@astro.utoronto.ca>
 :Author: Hameer Abbasi <hameerabbasi@yahoo.com>
 :Author: Eric Wieser <wieser.eric@gmail.com>
-:Status: Accepted
+:Status: Draft
 :Type: Standards Track
 :Created: 2018-05-29
-:Resolution: https://mail.python.org/pipermail/numpy-discussion/2018-August/078493.html
 
 Abstact
 -------
@@ -85,6 +84,16 @@ instance and method.
 A prototype implementation can be found in
 `this notebook <https://nbviewer.jupyter.org/gist/shoyer/1f0a308a06cd96df20879a1ddb8f0006>`_.
 
+.. warning::
+
+  The ``__array_function__`` protocol, and its use on particular functions,
+  is *experimental*. We plan to retain an interface that makes it possible
+  to override NumPy functions, but the way to do so for particular functions
+  **can and will change** with little warning. If such reduced backwards
+  compatibility guarantees are not accepted to you, do not rely upon overrides
+  of NumPy functions for non-NumPy arrays. See "Non-goals" below for more
+  details.
+
 The interface
 ~~~~~~~~~~~~~
 
@@ -97,8 +106,9 @@ We propose the following signature for implementations of
 
 -  ``func`` is an arbitrary callable exposed by NumPy's public API,
    which was called in the form ``func(*args, **kwargs)``.
--  ``types`` is a ``frozenset`` of unique argument types from the original NumPy
-   function call that implement ``__array_function__``.
+-  ``types`` is a `collection <https://docs.python.org/3/library/collections.abc.html#collections.abc.Collection>`_
+   of unique argument types from the original NumPy function call that
+   implement ``__array_function__``.
 -  The tuple ``args`` and dict ``kwargs`` are directly passed on from the
    original call.
 
@@ -109,11 +119,12 @@ implementing the array API.
 As a convenience for ``__array_function__`` implementors, ``types`` provides all
 argument types with an ``'__array_function__'`` attribute. This
 allows downstream implementations to quickly determine if they are likely able
-to support the operation. A ``frozenset`` is used to ensure that
-``__array_function__`` implementations cannot rely on the iteration order of
-``types``, which would facilitate violating the well-defined "Type casting
-hierarchy" described in
-`NEP-13 <https://www.numpy.org/neps/nep-0013-ufunc-overrides.html>`_.
+to support the operation. The type of ``types`` is intentionally vague:
+``frozenset`` would most closely match intended use, but we may use ``tuple``
+instead for performance reasons. In any case, ``__array_function__``
+implementations should not rely on the iteration order of ``types``, which
+would violate a well-defined "Type casting hierarchy" (as described in
+`NEP-13 <https://www.numpy.org/neps/nep-0013-ufunc-overrides.html>`_).
 
 Example for a project implementing the NumPy API
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -494,7 +505,10 @@ wait for an optimal implementation. The price of moving fast is that for
 now **this protocol should be considered strictly experimental**. We
 reserve the right to change the details of this protocol and how
 specific NumPy functions use it at any time in the future -- even in
-otherwise bug-fix only releases of NumPy.
+otherwise bug-fix only releases of NumPy. In practice, once initial
+issues with ``__array_function__`` are worked out, we will use abbreviated
+deprecation cycles as short as a single major NumPy release (e.g., as
+little as four months).
 
 In particular, we don't plan to write additional NEPs that list all
 specific functions to overload, with exactly how they should be
@@ -512,11 +526,13 @@ own protocols:
 -  dispatch for methods of any kind, e.g., methods on
    ``np.random.RandomState`` objects.
 
-As a concrete example of how we expect to break behavior in the future,
-some functions such as ``np.where`` are currently not NumPy universal
-functions, but conceivably could become universal functions in the
-future. When/if this happens, we will change such overloads from using
-``__array_function__`` to the more specialized ``__array_ufunc__``.
+We also expect that the mechanism for overriding specific functions
+that will initially use the ``__array_function__`` protocol can and will
+change in the future. As a concrete example of how we expect to break
+behavior in the future, some functions such as ``np.where`` are currently
+not NumPy universal functions, but conceivably could become universal
+functions in the future. When/if this happens, we will change such overloads
+from using ``__array_function__`` to the more specialized ``__array_ufunc__``.
 
 
 Backward compatibility
@@ -540,6 +556,17 @@ with ``__array_function__`` should switch to a new protocol instead,
 that is explicitly OK for as long as ``__array_function__`` retains its
 experimental status.
 
+Switching to a new protocol should use an abbreviated version of NumPy's
+normal deprecation cycle:
+
+- For a single major release, after checking for any new protocols, NumPy
+  should still check for ``__array_function__`` methods that implement the
+  given function. If any argument returns a value other than
+  ``NotImplemented`` from ``__array_function__``, a descriptive
+  ``FutureWarning`` should be issued.
+- In the next major release, the checks for ``__array_function__`` will be
+  removed.
+
 Separate namespace
 ~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/release/1.16.0-notes.rst b/doc/release/1.16.0-notes.rst
index e07c3c654..8d068079e 100644
--- a/doc/release/1.16.0-notes.rst
+++ b/doc/release/1.16.0-notes.rst
@@ -42,6 +42,11 @@ Future Changes
 
 * NumPy 1.17 will drop support for Python 2.7.
 
+Expired deprecations
+====================
+
+* NaT comparisons now return ``False`` without a warning, finishing a
+  deprecation cycle begun in NumPy 1.11.
 
 Compatibility notes
 ===================
@@ -54,6 +59,15 @@ whenever the ``Scripts`` directory is in the path. Folks needing compatibility
 with earler versions of Numpy should run ``f2py`` as a module: ``python -m
 numpy.f2py [...]``.
 
+NaT comparisons
+---------------
+Consistent with the behavior of NaN, all comparisons other than inequality
+checks with datetime64 or timedelta64 NaT ("not-a-time") values now always
+return ``False``, and inequality checks with NaT now always return ``True``.
+This includes comparisons beteween NaT values. For compatibility with the
+old behavior, use ``np.isnat`` to explicitly check for NaT or convert
+datetime64/timedelta64 arrays with ``.astype(np.int64)`` before making
+comparisons.
 
 C API changes
 =============
@@ -188,4 +202,3 @@ modules, they are now python wrappers to the single `np.core/_multiarray_math`
 c-extension module.
 
 .. _`NEP 15` : http://www.numpy.org/neps/nep-0015-merge-multiarray-umath.html
-
diff --git a/doc/source/reference/c-api.generalized-ufuncs.rst b/doc/source/reference/c-api.generalized-ufuncs.rst
index 59aa11d00..dce198013 100644
--- a/doc/source/reference/c-api.generalized-ufuncs.rst
+++ b/doc/source/reference/c-api.generalized-ufuncs.rst
@@ -163,13 +163,13 @@ Here are some examples of signatures:
 +-------------+----------------------------+-----------------------------------+
 | matmul      | ``(m?,n),(n,p?)->(m?,p?)`` | combination of the four above     |
 +-------------+----------------------------+-----------------------------------+
-| cross1d     | ``(3),(3)->(3)``           | cross product where the last      |
-|             |                            | dimension must be 3               |
-+-------------+----------------------------+-----------------------------------+
 | outer_inner | ``(i,t),(j,t)->(i,j)``     | inner over the last dimension,    |
 |             |                            | outer over the second to last,    |
 |             |                            | and loop/broadcast over the rest. |
 +-------------+----------------------------+-----------------------------------+
+| cross1d     | ``(3),(3)->(3)``           | cross product where the last      |
+|             |                            | dimension must be 3               |
++-------------+----------------------------+-----------------------------------+
 
 C-API for implementing Elementary Functions
 -------------------------------------------