[SciPy-dev] mlabwrap high-level user interface

[Alexander Schmolck]

[Moving this to scipy-dev]

"Brian Hawthorne" <brian.lee.hawthorne at gmail.com> writes:

> Hello,
> I'm hoping to get feedback from you all on some suggestions for what a
> cleaner mlabwrap API might look like.
>
>>>> from scikits.mlab import engine  # engine is an instance of MlabEngine
> (or simply Engine)

This is simply about renaming scikits.mlabwrap to scikits.mlab, MlabWrap to
MlabEngine and mlab to engine, right?

I agree that mlabwrap is not necessarily the most elegant name (pymat is
better, but was already taken), but I'm not sure I'd prefer engine to mlab --
it's more generic and more to type; it's also slightly the wrong emphasis for
my taste (I don't want people to focus on the fact that they're doing
something that involves using the matlab engine; the abstraction level offered
by mlabwrap is above that of matlab's engine protocol).

Anyway, my suggestion is that we first deal with the meat (sorting out hybrid
proxying, scikits and testing infrastructure etc.) and worry about cosmetic
issues like renamings afterwards -- I don't think naming issues are
unimportant but they can be dealt with once the functionality we want is
there; conversely changes in the core design can render cosmetic decisions
obsolete.

>>>> engine.X = [[1,2,3],[4,5,6],[7,8,9]]  # raw put, implement __setattr__
>>>> engine["X"] = [[1,2,3],[4,5,6],[7,8,9]]  # raw put, implement __setitem__
>>>> X = engine.X  # raw get, implement __getattr__
>>>> X = engine["X"]  # raw get, implement __getitem__

Do I understand you correctly that you want 1&2 and 3&4 to be equivalent
(javscript-style)? If so I'm against it -- in python there's ideally one and
only one obvious way. I propose using ``.X`` for function calls and ``.["X"]``
for variable access (yup, there *is* a reason why I think one wants to
seperate these, see my reply to your other post).

>>>> Y = engine("matlab code")  # raw eval, implement __call__

Using ``engine["x"]`` viz. ``mlab["x"]`` for variable access and ``mlab("do
something")`` for raw evaluation looks pretty attractive to me. The only
reason I can see why one might want to reserve ``__call__`` is that it could
also mkae for a convenient customization syntax, e.g::

 mlab(flatten_row_vecs=True).sin([1,2,3])

which might be more important than having a shorter way to spell 
``mlab._do("do something")``. With python2.5 one could also use the with
syntax for that, but the syntax above could still be slightly more convenient
for single calls with non-default options.

>>>> a = engine.some_matlab_object_with_nested_attributes  # return an
> ObjectProxy
>>>> a.b.c  # in matlab, call (a.subsref("b")).subsref("c")
>>>> a["b.c"]  # bypas "normal" indexing to call a.subsref("b.c")
>
> Regarding packaging, the code currently in _mlabwrap.py could move into the
> __init__.py file (since it's imported into there anyway), then we could
> delete
> _mlabwrap.py.  

_mlabwrap.py is there for a purpose, albeit a fairly egotistical one: it makes
switching buffers in emacs easier (i.e. generic names like __init__.py are
inconvenient if you got a UI that lets you switch to the desired buffer (viz
opened file for non-emacs users) by entering some unique substring). I'd be
happy to get rid of _mlabwrap.py if there are any downsides associated with
having it, but I'm currently not aware of any.

> Also, the ctypes version Taylor is working on won't require any non-python
> extension code (I believe), so mlabrawmodule.so will disappear too, 

Yup.

> and the package directory will be left with nothing but awmsmeta.py and
> awmstools.py. Taylor also mentioned that the ctypes version currently relies
> on some small C utilities, but that they can probably be done away with
> (please correct me if I'm wrong here).

No, I'd indeed like to get rid of all C(++) code.

> I also suggest moving the tests dir under the scikits.mlab package so it can
> be found by numpytest.

IIRC the current directory structure (and the position of ``tests/``)
corresponds to what Robert Kern suggested -- I'm not really familiar with
numpytest yet, but I suppose if it expects tests to be in the location you
say that's presumably an oversight. I'm about to write a scikits related email
to the list anyway, so I'll ask in there.

> As far as changing mlabwrap to mlab, it's not super important, but it would
> be a bit easier to type, and I think in general python wrappers don't
> use the word "wrap" in their names.  

I don't think the typing argument matters much, since unlike e.g. ``os``
``mlabwrap`` is not meant to be to be used as a qualifying prefix -- the
standard idiom is ``from mlabwrap import mlab``, so mlabwrap only needs to get
type once per file/session.

> If we did that, it would also make sense for the project itself to be called
> mlab (the fewer names the better).

It's common in python, but IMO stuff like ``StringIO.StringIO`` is piss-poor
design in a language where both the use of unqualified names and qualified
names is common (and importing module handles later on is often required for
reloading and other interactive shell use). I've been frequently annoyed and
even once or twice been bitten by this so I'd really rather not have
``mlab.mlab`` even if it would mean fewer names. OTOH now we've got the
additional leading ``scikits.`` anyway, the respective ``mlab``s are
presumably sufficiently disambiguated... so I guess I'm open to this renaming,
but I suggest we deal with other things first, as mentioned above.

cheers,

alex