[SciPy-dev] Technology Previews and Sphinx Docstring Annotations

[jh at physics.ucf.edu]

"Damian Eads" <eads at soe.ucsc.edu> wrote:

> Technology preview code is new code incorporated into the trunk of
> SciPy ... considered production grade and well-tested ... no
> guarantees of a stable API to enable further improvements based on
> community feedback.

Sorry, but I feel this is a poor idea.  Scipy is supposed to be
stable.  We got rid of the sandbox for a reason.  We have too many API
problems in scipy and even in numpy (median, FFT, and many others) to
introduce a sanctioned mechanism for breaking APIs.

If code is production-grade, *it has a stable API*.  If not, release a
separate package, get some use experience, and let the API mature.  If
the code is add-on code to an existing package in scipy, your package
can monkeypatch it into the relevant scipy package as you and
interested others test it, or you can import it separately.  Then
propose to bring it into SciPy as a mature package once it's ready.  I
would certainly favor a section of the web site devoted to promoting
such tests (scipy.org/nursery?  scipy.org/testbed?
scipy.org/greenhouse?).

Putting a markup in the documentation is not nearly sufficient warning
since many people exchange code (e.g., Cookbook) without reading the
docs for all the functions and classes the code contains.  Also,
having "Technology Demonstration" labels all over the place will only
serve to shake people's faith in the stability of the package, and
prevent it from ever getting a reputation for reliability.

Numpy and scipy should never be places for experimentation.

--jh--