Pass Data to Python

MATLAB Type to Python Type Mapping

When you pass MATLAB® data as arguments to Python®, MATLAB converts the data into types that best represent the data to the Python language.

MATLAB Input Argument Type —
Scalar Values Only

Resulting Python py. Type

double
single

float

Complex single
Complex double

complex

int8
uint8
int16
uint16
int32

int

uint32
int64
uint64

int
long (version 2.7 only)

NaN

float(nan)

Inf

float(inf)

string scalar
char vector

str

<missing> value in string

None

logical

bool

Structure

dict

Python object — py.type

type

function handle @py.module.function, to Python functions only

module.function

MATLAB Vector to Python Mapping

MATLAB Input Argument Type —
1-by-N Vector

Resulting Python Type

double

array.array('d')

single

array.array('f')

int8

array.array('b')

uint8

array.array('B')

int16

array.array('h')

uint16

array.array('H')

int32

array.array('i')

uint32

array.array('I')

int64 (Not supported for Python 2.7 on Windows®)

array.array('q')

uint64 (Not supported for Python 2.7 on Windows)

array.array('Q')

char array containing values greater than 127 (version 2.7 only)

unicode

logical

memoryview

char vector
string scalar

str

cell vector

tuple

Passing Matrices and Multidimensional Arrays

When you pass real numeric or logical arrays to a Python function, MATLAB automatically converts the data to a Python memoryview object. If the output of a Python function implements the Python buffer protocol and is real numeric or logical, then MATLAB displays:

  • The actual Python type

  • The underlying data

  • The corresponding MATLAB conversion function. Use this function to fully convert the Python object to a MATLAB array.

For example, suppose that you call a Python function in a module pyModule that returns a variable of type pyType with these values:

p = 
  Python pyType:

     8     1     6
     3     5     7
     4     9     2

    Use details function to view the properties of the Python object.

    Use double function to convert to a MATLAB array.

To convert p to a MATLAB matrix P, type:

P = double(p)
P = 3×3    
     8     1     6
     3     5     7
     4     9     2

If you need specific information about the Python properties of p, type:

details(p)
  py.pyModule.pyType handle with properties:

           T: [1×1 py.pyModule.pyType]
        base: [1×1 py.NoneType]
      ctypes: [1×1 py.pyModule.core._internal._ctypes]
        data: [1×3 py.memoryview]
       dtype: [1×1 py.pyModule.dtype]
       flags: [1×1 py.pyModule.flagsobj]
        flat: [1×1 py.pyModule.flatiter]
        imag: [1×1 py.pyModule.pyType]
    itemsize: [1×1 py.int]
      nbytes: [1×1 py.int]
        ndim: [1×1 py.int]
        real: [1×1 py.pyModule.pyType]
       shape: [1×2 py.tuple]
        size: [1×1 py.int]
     strides: [1×2 py.tuple]

  Methods, Events, Superclasses

If the Python module provides content in its __doc__ attribute, then MATLAB links to that information.

Using Python memoryview objects allows Python to read the MATLAB data without making a copy of the MATLAB data. For information about memoryview objects and buffer protocol, search for these terms at https://www.python.org/doc/.

MATLAB complex and sparse arrays are not supported in Python. See Unsupported MATLAB Types.

Troubleshooting Argument Errors

If a Python function expects a specific Python multidimensional array type, then MATLAB displays a message with tips about how to proceed. If the problem might be due to passing a matrix or a multidimensional array as an argument, then do the following.

  1. Check the documentation for the Python function and find out the expected type for the argument.

  2. Create a Python object of that type in MATLAB and pass that to the Python function.

For example, suppose that the following code returns an error.

a = [1 2; 3 4];
py.pyfunc(a)

If the documentation of pyfunc specifies that the expected type is pyType, then try this conversion:

py.pyfunc(pyType(a))

If the error persists, then determine the root cause by checking for additional information in the Python exception.

Related Examples

More About