[Moving this to scipy-dev] "Brian Hawthorne" <brian.lee.hawthorne@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