arokem/python-matlab-bridge — pull request #63 by hbristow (2014-04-07 09:49:34+00:00)
Title: Pythonic API

This pull request introduces a new pythonic API to Matlab. The functionality is experimental at the moment. If you like this direction, let me know and I can solidify the implementation and remove deprecated code. **Don't merge this pull request in its current state**. I want to know what you think before I spend any sizable amount of time on it.

### Features

##### Matlab functions are Python functions

```python
# call matlab functions
matlab.sqrt(5) --> 2.23606797749979
matlab.min([5, 4]) --> 4

# bind matlab functions to local variables
sqrt = matlab.sqrt

# matlab functions are real functions
callable(matlab.sqrt) --> True
type(matlab.sqrt) --> instancemethod
print(matlab.sqrt) -->
```

This allows us to use a bunch of builtin Matlab functionality natively rather than rewrite it ourselves

```python
# get version info
matlab.version() --> '7.13.0.564 (R2011b)'

# run a script
matlab.run('/path/to/script.m')

# call a function not currently on the matlab path
matlab.addpath('/path/to/func')
matlab.func(args)

# evaluate an arbitrary expression
matlab.eval('svd([5 4; 2 1])')
```

##### Keyword Arguments

Functions that take optional named arguments using Matlab's name, value hack (plotting, etc) can use Python's native keyword arguments syntax

```python
matlab.plot(x, y, '--', LineWidth=2, MarkerSize=10)
```

##### Number of Output Arguments

The behaviour of many Matlab functions changes depending on how many output arguments are provided (seriously, who thought of that...). An option `nout` argument can be supplied to indicate how many outputs are desired

```python
matlab.min([5, 4]) --> 4
matlab.min([5, 4], nout=2) --> (4, 2)
```

##### Native Python docstrings

Help is provided via Python's builtin `help()` function.

```python
help(matlab.sqrt)
```

docstrings are cached, so they are only fetched from Matlab once.

##### Exceptions

Matlab exceptions are captured and re-raised as Python exceptions to indicate errors

```python
# non-existent function
matlab.asdkfjhasdlfjn() --> raises AttributeError: 'Matlab' object has no attribute 'asdkfjhasdlfjn'

# bad inputs
matlab.min() --> raises RuntimeError: MATLAB:minrhs: Not enough input arguments.
```

If a non-existent function name is called, that function name is blacklisted so subsequent attempts to call that function immediately throw an exception.