[Numpy-discussion] numarray repackaging... as it turned out

[Todd Miller]

Our efforts to repackage numarray as a package rather than a collection
of modules have taken form, so I'm looking for a (final) final round of
comments before we declare this to be the "new interface". 

=================
basic repackaging
=================

The core numarray routines will be distributed as the package "numarray"
and because the new package __init__.py imports the contents of
the old numarray.py module, simple import phrases involving numarray
will continue to work like they always did:

import numarray            # These will continue to work unchanged
from numarray import *

For everything else, a "numarray." prefix and possibly a new name are
required:

recarray  --> numarray.records 
chararray --> numarray.strings 
ndarray   --> numarray.generic
numtestall --> numarray.testall
*         --> numarray.* 

The 4 standard add-on packages have been renamed and will be distributed
as a single unit called "numarray-addons" and will install directly in
the numarray package.  This has most effect for Windows binary users who
should now be able to install with two clicks: one for numarray, the
other for the addons.  UNIX users still have the setupall one liner or
the option to use the two independent setups however they like.

FFT2           --> numarray.fft     
LinearAlgebra2 --> numarray.linear_algebra 
Convolve       --> numarray.convolve 
Convolve.Image --> numarray.image 

=======
numcomp
=======

There is a new "compatibility distribution" called "numcomp" which
installs backward compatibility modules in a directory separate from
numarray.  Install numcomp if you want to run numarray-0.6 without
changing your existing numarray applications for the new naming scheme
(and if you directly import anything other than numarray itself, e.g.
recarray or FFT2).  We need numcomp at STSCI as a pragmatic issue, to
prevent needing simultaneous changes of numarray and software depending
on it.  numcomp issues a single deprecation warning when
you import your first compatibility module.  numcomp is a sort of
veneer, not a complete distribution;  you still need the numarray-0.6
package in order to use numcomp.  The plan is to phase numcomp out of
existence at the release of numarray-1.0.   The warning can be
eliminated either by a simple hack of numcomp's repackage.py module, or
from the Python command line.

Thus, without numcomp but with numarray-0.6:

>>> import recarray           # can't do this anymore
...
ImportError

>>> import numarray.records   # have to do this now
>>>

but with numcomp:

>>> import recarray           # this still works, but with a warning
...NumarrayRepackagingWarning...     # too big a mouthful for email

================
numarray.numeric
================

There is now a submodule of numarray,  numarray.numeric, which is more
Numeric compatbile than numarray itself.  It is part of the main
numarray distribution.  numarray.numeric contains everything the (old)
numarray module does, but also redefines things for better
compatibility.   Currently, it just redefines nonzero()
to handle 1D arrays the same as Numeric does.  numarray.nonzero()
remains unchanged.  Any future Numeric compatibility changes will be
added to numarray.numeric as well.  So... if you've already written
numarray code using nonzero() and it works, you're done.  If you want to
port Numeric code to numarray, consider importing numarray.numeric
instead of numarray.  The current plan is to maintain numarray.numeric
indefinitely.

>>> import numarray
>>> import numarray.numeric
>>> a=numarray.arange(5)
>>> numarray.nonzero(a)         
(array([1, 2, 3, 4]),)           # this format handles multi-D arrays
>>> numarray.numeric.nonzero(a)
array([1, 2, 3, 4])              # this format doesn't

Comments?

Todd


-- 
Todd Miller 			jmiller at stsci.edu
STSCI / ESS / SSB