Pythonic API

LICENSE

@@ -1,10 +1,24 @@
-Copyright (c) 2013. See "Contributors". MATLAB (R) is copyright of the Mathworks. 
+Copyright (c) 2014. See "CONTRIBUTORS.md".
+MATLAB (R) is copyright of the Mathworks.
 
 All rights reserved.
 
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
 
-- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- -Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+- Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+ -Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
 
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pymatbridge/matlab/matlabserver.m

@@ -1,41 +1,95 @@
 function matlabserver(socket_address)
-% This function takes a socket address as input and initiates a ZMQ session
-% over the socket. I then enters the listen-respond mode until it gets an
-% "exit" command
+% MATLABSERVER Run a Matlab server to handle requests from Python over ZMQ
+%
+% MATLABSERVER(SOCKET_ADDRESS) initiates a ZMQ session over the provided
+% SOCKET_ADDRESS. Once started, it executes client requests and returns
+% the response.
+%
+% The recognized requests are:
+%   'ping': Elicit a response from the server
+%   'exit': Request the server to shutdown
+%   'call': Call a Matlab function with the provdided arguments
 
-json.startup
-messenger('init', socket_address);
+    json.startup
+    messenger('init', socket_address);
+
+    while true
+        % don't let any errors escape (and crash the server)
+        try
+            msg_in = messenger('listen');
+            req = json.load(msg_in);
 
-while(1)
-    msg_in = messenger('listen');
-    req = json.load(msg_in);
+            switch(req.cmd)
+                case {'ping'}
+                    messenger('respond', 'pong');
 
-    switch(req.cmd)
-        case {'connect'}
-            messenger('respond', 'connected');
+                case {'exit'}
+                    messenger('exit');
+                    clear mex;
+                    break;
 
-        case {'exit'}
-            messenger('exit');
-            clear mex;
-            break;
+                case {'call'}
+                    resp = call(req);
+                    json_resp = json.dump(resp);
+                    messenger('respond', json_resp);
 
-        case {'run_function'}
-            fhandle = str2func('pymat_feval');
-            resp = feval(fhandle, req);
-            messenger('respond', resp);
+                otherwise
+                    throw(MException('MATLAB:matlabserver', ['Unrecognized command ' req.cmd]))
+            end
 
-        case {'run_code'}
-            fhandle = str2func('pymat_eval');
-            resp = feval(fhandle, req);
-            messenger('respond', resp);
+        catch exception
+            % format the exception and pass it back to the client
+            resp.success = false;
+            resp.result  = exception.identifier;
+            resp.message = exception.message;
 
-        case {'get_var'}
-            fhandle = str2func('pymat_get_variable');
-            resp = feval(fhandle, req);
-            messenger('respond', resp);
+            json_resp = json.dump(resp);
+            messenger('respond', json_resp);
+        end
+    end
+end
+
+
+function resp = call(req)
+% CALL Call a Matlab function
+%
+% RESPONSE = CALL(REQUEST) calls Matlab's FEVAL function, intelligently
+% handling the number of input and output arguments so that the argument
+% spec is satisfied.
+%
+% The REQUEST is a struct with three fields: 
+%   'func': The name of the function to execute
+%   'args': A cell array of args to expand into the function arguments
+%   'nout': The number of output arguments requested
+
+    % function of no arguments
+    if ~isfield(req, 'args')
+        req.args = {}
+    end
+
+    % determine the number of output arguments
+    % TODO: What should the default behaviour be?
+    func = str2func(req.func);
+    nout = req.nout;
+    if isempty(nout)
+        try
+            nout = min(abs(nargout(func)), 1);
+        catch
+            nout = 1;
+        end
+    end
 
+    % call the function, taking care of broadcasting outputs
+    switch nout
+        case 0
+            func(req.args{:});
+        case 1
+            resp.result = func(req.args{:});
         otherwise
-            messenger('respond', 'i dont know what you want');
+            [resp.result{1:nout}] = func(req.args{:});
     end
 
+    % build the response
+    resp.success = true;
+    resp.message = 'Successfully completed request';
 end

pymatbridge/matlab/util/pymat_eval.m

@@ -6,7 +6,7 @@
 %
 %   This allows you to run any matlab code. To be used with webserver.m.
 %   HTTP POST to /web_eval.m with the following parameters:
-%       code: a string which contains the code to be run in the matlab session
+%       expr: a string which contains the expression to evaluate in the matlab session
 %
 %   Should return a json object containing the result
 %
@@ -17,26 +17,26 @@
 
 response.content = '';
 
-code_check = false;
+expr_check = false;
 if size(field_names)
-	if isfield(req, 'code')
-		code_check = true;
+	if isfield(req, 'expr')
+		expr_check = true;
 	end
 end
 
-if ~code_check
-	response.message = 'No code provided as POST parameter';
+if ~expr_check
+	response.message = 'No expression provided as POST parameter';
 	json_response = json.dump(response);
 	return;
 end
 
-code = req.code;
+expr = req.expr;
 
 try
 	% tempname is less likely to get bonked by another process.
 	diary_file = [tempname() '_diary.txt'];
 	diary(diary_file);
-	evalin('base', code);
+	evalin('base', expr);
 	diary('off');
 
 	datadir = fullfile(tempdir(),'MatlabData');
@@ -69,7 +69,7 @@
 	response.content.stdout = ME.message;
 end
 
-response.content.code = code;
+response.content.expr = expr;
 
 json_response = json.dump(response);
 

pymatbridge/matlab/util/pymat_feval.m

@@ -1,7 +1,19 @@
-% Max Jaderberg 2011
-
 function json_response = matlab_feval(req)
 
+    if ~isfield(req, 'func_path')
+        response.success = false;
+        response.message = 'No function given as func_path POST parameter';
+        json_response = json.dump(response);
+    end
+
+    if ~isfield(req, 'func_args')
+        req.func_args = {}
+    end
+
+    [dir, func_name, ext] = fileparts(req.func_path);
+    try
+        response.result = 
+
     response.success = 'false';
     field_names = fieldnames(req);
 

pymatbridge/matlab/util/pymat_get_variable.m

@@ -2,31 +2,16 @@
 % Reach into the current namespace get a variable in json format that can
 % be returned as part of a response
 
-response.success = 'false';
-
-field_names = fieldnames(req);
-
-response.content = '';
-
-varname_check = false;
-if size(field_names)
-    if isfield(req, 'varname')
-        varname_check = true;
+    try
+        response.result  = evalin('base', req.varname);
+        response.success = true;
+    catch exception
+        response.success = false;
+        response.result  = exception.identifier;
+        response.message = exception.message;
     end
-end
 
-if ~varname_check
-    response.message = 'No variable name provided as input argument';
     json_response = json.dump(response);
     return
-end
-
-
-varname = req.varname;
-
-response.var = evalin('base', varname);
-
-json_response = json.dump(response);
 
-return
 end

pymatbridge/publish.py

@@ -132,3 +132,20 @@ def convert_mfile(mfile, outfile=None):
     nbformat.write(nb, nbfile, format='ipynb')
     nbfile.close()
 
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description='Publish a matlab file (.m) as an interactive notebook (.ipynb)')
+
+    parser.add_argument('mfile', action='store', metavar='File', help='Matlab m-file (.m)')
+    parser.add_argument('--outfile', action='store', metavar='File',
+        help='Output notebook (.ipynb). Default: same name and location as the input file ', default=None)
+
+    params = parser.parse_args()
+
+    convert_mfile(params.mfile, params.outfile)
+
+if __name__ == '__main__':
+    main()