pyargs

Create keyword arguments for Python function

Syntax

kwa = pyargs(argKey,argValue)

Description

kwa = pyargs(argKey,argValue) creates one or more keyword arguments to pass to a Python^® function. A Python keyword argument is a value preceded by an identifier. Place pyargs as the final input argument to a Python function. For example:

py.print('a','b',pyargs('sep',','))

You cannot pass a keyword argument created by pyargs as a key argument to the MATLAB^® dictionary function or as input to the keyMatch function.

Examples

Call Python complex Function Using Keyword Arguments

The Python complex function has keyword arguments real and imag. When you call this function in MATLAB, use either the pyargs function or name=value syntax. Do not mix the two calling formats.

Call the function with a pyargs argument.

py.complex(pyargs('real',1,'imag',2))

ans = 

  Python complex with properties:

    imag: 2
    real: 1

    (1+2j)

Alternatively, call the function with name=value syntax.

py.complex(real=1,imag=2);

Input Arguments

argKey,argValue — Python function arguments

keyword and value arguments

Python function keyword arguments specified as one or more comma-separated pairs of argKey,argValue arguments. argKey is the Python function key name and is a string or character vector. argValue is the argument value, represented by any valid Python type. Use the Python function argument list to identify argKey and argValue. You can specify several key and value pair arguments in any order as argKey1,argValue1,...,argKeyN,argValueN.

Example: 'length',int32(2)

Limitations

• Do not combine pyargs and name=value syntax when passing keyword arguments to Python functions.

• MATLAB does not support name,value syntax for passing keyword arguments to Python functions. Use name=value syntax instead.

Alternative Functionality

You can pass Python keyword arguments using MATLAB name=value syntax. For more information, see Call Python complex Function Using Keyword Arguments.

Version History

Introduced in R2014b

R2022b: Display Python keyword arguments

The pyargs function displays keyword (key-value pair) arguments.

pyargs(A=1,B=2)

ans = 

  'pyargs' with pairs:

    A: 1
    B: 2

pyargs("A",1,"B",2)

ans = 

  'pyargs' with pairs:

    A: 1
    B: 2

R2021b: name=value syntax errors for calls to Python functions using py. prefix

In R2021b, MATLAB errors when you use name=value syntax for passing keyword arguments to Python functions using the py. prefix. In R2021a, MATLAB silently gives the wrong answer or throws a Python error. Use pyargs to pass keyword arguments.

For example, the Python print function has a keyword argument sep. This Python statement sets the sep argument to a comma followed by a space:

print('comma','separated','values',sep=', ')

When you call this statement in MATLAB, MATLAB interprets sep=', ' as a name=value argument:

py.print('comma','separated','values',sep=', ')

R2021a Behavior	R2021b Behavior	How to Update Your Code
py.print(... 'comma','separated','values',... sep=', ') Silent wrong answer: comma separated values sep ,	py.print(... 'comma','separated','values',... sep=', ') Error: Error using py.print Using name=value format is not supported. Use pyargs to pass keyword arguments	py.print(... 'comma','separated','values',... pyargs(sep=', ')) comma, separated, values