[Numpy-discussion] How to handle a busted API?

[Robert Kern]

On Sun, Jul 13, 2008 at 00:44, Charles R Harris
<charlesr.harris at gmail.com> wrote:
> Hi All,
>
> This is apropos ticket #805. The reporter wants to change the signature of
> the functions PyArray_FromDims and PyArray_FromDimsAndDataAndDesc, which we
> really can't do at this point because they are part of the Numpy API. The
> problem can be seen in the current signatures:
>
> PyArray_FromDims(int nd, int *d, int type)
> PyArray_FromDimsAndDataAndDescr(int nd, int *d, PyArray_Descr *descr, char
> *data)
>
> where d points to the desired dimensions. On 64 bit architectures the int
> type can be too small to hold the dimensions. Now these functions are old
> and retained for compatibility; the user's problem turned up in num_utils,
> which is a C++ interface to Numeric. Quite possibly other programs use it
> also (BOOST?).
>
> So the question is, how do we go about dealing with this. Do we remove them
> at some point, breaking compatibility and the current API? If so, when do we
> do this?

The original vision was to remove numpy.oldnumeric and (I think)
numpy/oldnumeric.h at what was envisioned as "1.1" long ago when we
were still at 0.9 or so. That vision has been overcome by events, I
think.

Given the evidence of people's adoption, I don't quite think it's time
to remove the compatibility APIs wholesale, yet. However, for
problematic APIs like this one, I think we can issue a
DeprecationWarning (see below) in 1.2, and schedule them for removal
in 1.3. In 1.3 until the whole compatibility API is removed, we can
have these APIs just contain an #error such that they stop the build
at compile time.

> Should we issue a deprecation warning? If so, how do we do it from
> C? Should it show up at run time or compile time?

Compile-time warnings will be ignored if they aren't errors that stop
the build. Run-time DeprecationWarnings are feasible:

  http://docs.python.org/dev/c-api/exceptions.html#PyErr_WarnEx

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
 -- Umberto Eco