How MATLAB Handles Datetime and Duration Types in Python

When you use MATLAB^® functionality in Python^® and work with datetime or duration values, MATLAB Engine API for Python automatically converts your data between the equivalent MATLAB and Python data types.

Convert from MATLAB Data Type to Python Data Type

When you pass MATLAB datetime or duration values to Python, the MATLAB engine automatically converts the values to the equivalent Python data type, as shown in this table. An array contains either zero elements or more than one.

MATLAB Data Type	Resulting Python Data Type
`datetime` scalar	`datetime.datetime` object
`duration` scalar	`datetime.timedelta` object
`datetime` array	`numpy.datetime64` array If the NumPy package is not available in the Python environment, MATLAB converts the `datetime` array to `matlab.object`.
`duration` array	`numpy.timedelta64` array If the NumPy package is not available in the Python environment, MATLAB converts the `duration` array to `matlab.object`.

Convert from Python Data Type to MATLAB Data Type

When you pass Python data to MATLAB in Python, the MATLAB engine automatically converts the data into the equivalent MATLAB data type, as shown in this table.

Python Data Type	Resulting MATLAB Data Type
`datetime.datetime` scalar	`datetime` scalar
`datetime.timedelta` scalar	`duration` scalar
`numpy.datetime64` scalar	`datetime` scalar
`numpy.timedelta64` scalar	`duration` scalar
`numpy.datetime64` array	`datetime` array
`numpy.timedelta64` array	`duration` array

Use MATLAB Datetime Scalar in Python

First, import the datetime module and start the MATLAB engine in Python.

import datetime
import matlab.engine
eng = matlab.engine.start_matlab('-desktop')

Create a datetime value in MATLAB.

mwdt = datetime("2022-11-04 03:15:35.12345", ...
                Format="uuuu-MM-dd HH:mm:ss.SSSSS");

Then, in Python, pass the MATLAB datetime value as an argument to a Python function, such as the list constructor. The MATLAB engine converts the value to a Python datetime.datetime object.

pyldt = list(eng.workspace["mwdt"])
pyldt

[datetime.datetime(2022, 11, 4, 3, 15, 35, 123450)]

When a MATLAB function called from Python returns a datetime scalar, the MATLAB engine automatically converts the MATLAB function output to a datetime.datetime object in Python. For example, in Python, view the data type returned by the MATLAB dateshift function.

type(eng.dateshift(eng.datetime('today'),'start','year'))

<class 'datetime.datetime'>

The MATLAB engine can convert MATLAB datetime scalar values with a time zone to Python datetime.datetime objects with the same time zone. On machines that do not have a system Internet Assigned Numbers Authority time zone database, such as Windows^® computers, you can install the Python tzdata module from the Python Package Index.

Using MATLAB datetime scalar values in Python has these limitations:

When you pass a MATLAB datetime value with nanosecond precision to Python, the MATLAB engine truncates the value because Python datetime objects support only microsecond precision.
You cannot pass MATLAB datetime scalars with the special time zone UTCLeapSeconds to Python.
You cannot pass MATLAB datetime scalars with a value of NaT to Python.

Use MATLAB Duration Scalar in Python

Similarly, you can create a duration value in MATLAB and then pass the value to a function in Python. The MATLAB engine converts the value to a Python datetime.timedelta object. While MATLAB duration values support millisecond precision, Python timedelta objects support microsecond precision.

For example, create a duration value in MATLAB.

mwd = duration("01:02:34.56789", ...
      "Format","hh:mm:ss.SSSSS");

Then, in Python, pass the MATLAB duration value as an argument to a Python function, such as the list constructor. Then display the Python list.

pyld = list(eng.workspace["mwd"])
pyld

[datetime.timedelta(seconds=3754, microseconds=567890)]

Use MATLAB Datetime Array in Python

You can access data in MATLAB datetime arrays in Python with or without the NumPy package.

With NumPy

If you have NumPy installed, you can convert between MATLAB datetime arrays and NumPy datetime64 arrays.

For example, create a MATLAB datetime array in MATLAB.

mwdtarr = datetime(2024,10:12,4,3,15,35);

In Python, import the NumPy package and pass the MATLAB datetime array to the Python type function. The MATLAB engine converts the data to a numpy.datetime64 array.

import numpy
type(eng.workspace["mwdtarr"])

<class 'numpy.ndarray'>

When the MATLAB engine converts a zoned MATLAB datetime array to a NumPy datetime64 array, it first converts the time zone to UTC and then removes the time zone before constructing the NumPy datetime64 array. For example, in MATLAB, create a zoned MATLAB datetime array.

mwdtarrtz = datetime(1984,12,07,2,59,0, ...
    TimeZone="America/Los_Angeles") ...
    + calyears(0:5);

Pass the MATLAB datetime array to Python and display it. The dates have been adjusted to UTC.

npdtarrtz = eng.workspace["mwdtarrtz"]
npdtarrtz

array(['1984-12-07T10:59:00.000000000', '1985-12-07T10:59:00.000000000',
       '1986-12-07T10:59:00.000000000', '1987-12-07T10:59:00.000000000',
       '1988-12-07T10:59:00.000000000', '1989-12-07T10:59:00.000000000'],
      dtype='datetime64[ns]')

The MATLAB engine ignores the Python datetime.fold attribute.

Without NumPy

You can also pass MATLAB datetime arrays to Python without the NumPy package. In this case, the data converts to data of type matlab.object. However, if you want to store a MATLAB datetime array as a list of Python datetime values, you can first convert it to a cell array.

For example, in MATLAB, convert a MATLAB datetime array to a cell array.

mwdtcell = num2cell(mwdtarr);

Then, in Python, pass the cell array as an argument to a Python function. The MATLAB engine converts the cell array to a list of Python datetime values.

len(eng.workspace["mwdtcell"])

Use MATLAB Duration Array in Python

You can access data in MATLAB duration arrays in Python with or without the NumPy package.

With NumPy

If you have NumPy installed, you can convert between MATLAB duration arrays and NumPy timedelta64 arrays.

For example, create a MATLAB duration array in MATLAB.

mwdarr = duration(1:2,2,34);

In Python, import the NumPy package and pass the MATLAB duration array to the Python type function. The MATLAB engine converts the data to a numpy.timedelta64 array.

import numpy
type(eng.workspace["mwdarr"])

<class 'numpy.ndarray'>

You can convert a NumPy timedelta64 array to a MATLAB duration array using the same method. In Python, pass the NumPy array back to MATLAB.

eng.workspace['mwdarr2'] = npdarr

In MATLAB, display the MATLAB array.

mwdarr2

mwdarr2 = 

  1×2 duration array

   01:02:34   02:02:34

Without NumPy

You can also pass MATLAB duration arrays to Python without the NumPy package. To store a MATLAB duration array as a list of Python timedelta values, first convert it to a cell array.

For example, in MATLAB, convert a MATLAB duration array to a cell array.

mwdcell = num2cell(mwdarr);

Then, in Python, pass the cell array as an argument to a Python function. The MATLAB engine converts the cell array to a list of Python timedelta values.

len(eng.workspace["mwdcell"])

Pass Python Datetime Scalar to MATLAB

When you pass a Python datetime or NumPy datetime64 object to MATLAB, the MATLAB engine converts it to a MATLAB datetime value. For example, create a Python datetime object and pass it to MATLAB.

pydt = datetime.datetime(2019, 5, 18, 15, 17, 8, 132263)
eng.workspace['mwdt2'] = pydt

In MATLAB, display the MATLAB datetime value.

mwdt2

mwdt2 = 

  datetime

   2019-05-18T15:17:08.132Z

Pass Python Duration Scalar to MATLAB

When you pass a Python timedelta or NumPy timedelta64 object to MATLAB, the MATLAB engine converts it to a MATLAB duration value. For example, create a Python timedelta object and pass it to MATLAB.

pyd = datetime.timedelta(15, 12, 31, 23, 59, 59, 1)
eng.workspace['mwd2'] = pyd

In MATLAB, display the MATLAB duration value.

mwd2

mwd2 = 

  duration

   587:59:12

When you pass a Python timedelta value with microsecond precision to MATLAB, the MATLAB engine truncates the value because MATLAB duration values support only millisecond precision.