%PYRUNFILE Run a Python script file with command line arguments, if any.
%
%   PYRUNFILE(FILE) executes a Python script file, FILE, which can be provided as a
%   scalar string, cellstr or a char array. The FILE must specify absolute path or relative
%   path, with respect to the current working directory, to a file with '.py' extension.
%   Some command-line arguments can be passed, if the script file is expecting any, by providing
%   them in FILE after path to the file to be executed, seperated by whitespace characters.
%
%   [ OUTVARS ] = PYRUNFILE(FILE, OUTPUTS) executes the FILE and returns any variable
%   generated by Python to MATLAB, by specifying the names of the Python variables
%   in the OUTPUTS and capturing the returned values in OUTVARS. OUTPUTS can be provided
%   as a string, cellstr or a char array.
%
%   [ OUTVARS ] = PYRUNFILE(FILE, OUTPUTS, varargin<INPUTS>) executes the FILE and returns
%   OUTPUTS and assigns them to OUTVARS, using the MATLAB data passed by varargin<INPUTS>.
%   varargin<INPUTS> can be used to pass MATLAB data to the Python expression as
%   name-value pairs, where name is the name of the Python variable to be assigned and
%   the value is the MATLAB data or a variable name in an accessible workspace.
%   The varargin<INPUTS> can only be used to pass data that can automatically be converted
%   to a Python type.
%
%   Example 1:
%   % Contents of test.py file: %
%   a = x
%   b = a + y
%   % EOF test.py %
%
%   meaning = 42;
%   [ma, mb] = pyrunfile("test.py", ["a", "b"], x = 4, y = meaning);
%
%   In the above example, the value 4 and 42 are assigned to Python variables 'x' and 'y'
%   respectively. Once the script test.py is executed by Python two new variables are
%   generated, 'a' with the value of 4 and 'b' with the value of 46. The 'a' and 'b' are returned
%   to MATLAB and assigned to 'ma' and 'mb' respectively.
%
%   Example 2:
%   % Contents of test2.py file: %
%   import sys
%   a = int(sys.argv[1]) + 3
%   % EOF test2.py %
%
%   meaning = pyrunfile("test2.py 2", "a")
%
%   In the above example the value 2 is passed as a command-line argument to the script, test2.py,
%   where it is converted to a Python int and used for the creation of variable 'a'. The 'a' is then
%   returned to MATLAB as a Python int object with value 5.
%
%   Variables generated on the Python side using pyrunfile will NOT be persistent
%   across different pyrunfile calls.

% Copyright 2021 The MathWorks, Inc.
