The full-text of the NEP is quoted below, apologies for not including it
earlier:
NEP 31 — Context-local and global overrides of the NumPy API
:Author: Hameer Abbasi
:Author: Ralf Gommers
:Author: Peter Bell
:Status: Draft
:Type: Standards Track
:Created: 2019-08-22
Abstract
This NEP proposes to make all of NumPy's public API overridable via an
extensible backend mechanism, using a library called ``uarray`` `[1]`_
``uarray`` provides global and context-local overrides, as well as a dispatch
mechanism similar to NEP-18 `[2]`_. First experiences with
``__array_function__``
show that it is necessary to be able to override NumPy functions that
*do not take an array-like argument*, and hence aren't overridable via
``__array_function__``. The most pressing need is array creation and coercion
functions - see e.g. NEP-30 `[9]`_.
This NEP proposes to allow, in an opt-in fashion, overriding any part of the
NumPy API.
It is intended as a comprehensive resolution to NEP-22 `[3]`_, and obviates the
need to
add an ever-growing list of new protocols for each new type of function or
object that needs
to become overridable.
Motivation and Scope
The motivation behind ``uarray`` is manyfold: First, there have been several
attempts to allow
dispatch of parts of the NumPy API, including (most prominently), the
``__array_ufunc__`` protocol
in NEP-13 `[4]`_, and the ``__array_function__`` protocol in NEP-18 `[2]`_, but
this has shown the
need for further protocols to be developed, including a protocol for coercion
(see `[5]`_). The reasons
these overrides are needed have been extensively discussed in the references,
and this NEP will not
attempt to go into the details of why these are needed. Another pain point
requiring yet another
protocol is the duck-array protocol (see `[9]`_).
This NEP takes a more holistic approach: It assumes that there are parts of the
API that need to be
overridable, and that these will grow over time. It provides a general
framework and a mechanism to
avoid a design of a new protocol each time this is required.
This NEP proposes the following: That ``unumpy`` `[8]`_ becomes the
recommended override mechanism
for the parts of the NumPy API not yet covered by ``__array_function__`` or
``__array_ufunc__``,
and that ``uarray`` is vendored into a new namespace within NumPy to give users
and downstream dependencies
access to these overrides. This vendoring mechanism is similar to what SciPy
decided to do for
making ``scipy.fft`` overridable (see `[10]`_).
Detailed description
**Note:** *This section will not attempt to explain the specifics or the
mechanism of ``uarray``,
that is explained in the ``uarray`` documentation.* `[1]`_ *However, the NumPy
community
will have input into the design of ``uarray``, and any backward-incompatible
changes
will be discussed on the mailing list.*
The way we propose the overrides will be used by end users is::
import numpy.overridable as np
with np.set_backend(backend):
x = np.asarray(my_array, dtype=dtype)
And a library that implements a NumPy-like API will use it in the following
manner (as an example)::
import numpy.overridable as np
_ua_implementations = {}
__ua_domain__ = "numpy"
def __ua_function__(func, args, kwargs):
fn = _ua_implementations.get(func, None)
return fn(*args, **kwargs) if fn is not None else NotImplemented
def implements(ua_func):
def inner(func):
_ua_implementations[ua_func] = func
return func
return inner
@implements(np.asarray)
def asarray(a, dtype=None, order=None):
# Code here
# Either this method or __ua_convert__ must
# return NotImplemented for unsupported types,
# Or they shouldn't be marked as dispatchable.
# Provides a default implementation for ones and zeros.
@implements(np.full)
def full(shape, fill_value, dtype=None, order='C'):
# Code here
The only change this NEP proposes at its acceptance, is to make ``unumpy`` the
officially recommended
way to override NumPy. ``unumpy`` will remain a separate repository/package
(which we propose to vendor
to avoid a hard dependency, and use the separate ``unumpy`` package only if it
is installed)
rather than depend on for the time being), and will be developed
primarily with the input of duck-array authors and secondarily, custom dtype
authors, via the usual
GitHub workflow. There are a few reasons for this:
* Faster iteration in the case of bugs or issues.
* Faster design changes, in the case of needed functionality.
* ``unumpy`` will work with older versions of NumPy as well.
* The user and l
