Use MATLAB datetime Types with Python

These examples show how MATLAB^® converts between MATLAB datetime values and Python^® datetime or NumPy datetime64 values.

Pass MATLAB datetime Scalar to Python Function

When you pass a MATLAB datetime object as an argument to a Python function, the interface converts it to a Python datetime object. For example, create a MATLAB datetime scalar. This value is precise enough to include microseconds.

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

mwdt = 
  datetime
   2022-11-04 03:15:35.12345

Then pass it as an argument to a Python function, such as the list constructor. The interface converts mwdt to a Python datetime scalar.

pyListOfDatetime = py.list({mwdt})

pyListOfDatetime = 
  Python list with values:

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

Handle Python datetime Scalar Returned from Python Function

When a Python function returns a datetime object, the interface converts it to a MATLAB datetime object. The converted datetime scalar always has the default format. To change its format, set its Format property. In this example, set the format to display microseconds.

mwdtConverted = pyListOfDatetime{1};
mwdtConverted.Format = "uuuu-MM-dd HH:mm:ss.SSSSS"

mwdtConverted = 
  datetime
   2022-11-04 03:15:35.12345

Pass datetime Arrays

To store a MATLAB datetime array as a list of Python datetime values, first convert it to a cell array.

mwdt = datetime(2022,11:12,4,3,15,35);
mwdt = num2cell(mwdt)

mwdt =
  1×2 cell array
    {[04-Nov-2022 03:15:35]}    {[04-Dec-2022 03:15:35]}

Then pass the cell array as an argument to a Python function. The interface converts the cell array to a list of Python datetime values.

py.print(mwdt)

(datetime.datetime(2022, 11, 4, 3, 15, 35), datetime.datetime(2022, 12, 4, 3, 15, 35))

Pass NumPy datetime64 Arrays

You can convert between MATLAB datetime arrays and NumPy datetime64 arrays. For example, create a MATLAB datetime array.

mwdt = datetime(2022,11:12,4,3,15,35)

mwdt = 
  1×2 datetime array
   04-Nov-2022 03:15:35   04-Dec-2022 03:15:35

If you have NumPy installed, then the interface converts the array to a NumPy datetime64 array.

py.print(mwdt)

[['2022-11-04T03:15:35.000000' '2022-12-04T03:15:35.000000']]

py.print(py.type(mwdt))

<class 'numpy.ndarray'>

To convert a NumPy datetime64 array to a MATLAB datetime array, use the datetime function.

pyDatetimes = py.numpy.array(mwdt)

pyDatetimes = 
  Python ndarray with properties:

           T: [1×1 py.numpy.ndarray]
        base: [1×1 py.NoneType]
      ctypes: [1×1 py.numpy.core._internal._ctypes]
       dtype: [1×1 py.numpy.dtype[datetime64]]
       flags: [1×1 py.numpy.core.multiarray.flagsobj]
        flat: [1×1 py.numpy.flatiter]
        imag: [1×1 py.numpy.ndarray]
    itemsize: [1×1 py.int]
      nbytes: [1×1 py.int]
        ndim: [1×1 py.int]
        real: [1×1 py.numpy.ndarray]
       shape: [1×2 py.tuple]
        size: [1×1 py.int]
     strides: [1×2 py.tuple]
    [['2022-11-04T03:15:35.000000' '2022-12-04T03:15:35.000000']]

mwdtConverted = datetime(pyDatetimes)

mwdtConverted = 
  1×2 datetime array
   04-Nov-2022 03:15:35   04-Dec-2022 03:15:35

Handle Multiple Python datetime Objects Returned from Python Function

A Python function might return multiple datetime objects as a list or a tuple of Python datetime objects. Use the MATLAB datetime function to convert the list or tuple to a MATLAB datetime array. The list or tuple must contain Python datetime.datetime types only.

All elements of the array must contain scalar TimeZone values. MATLAB does not support converting a list or tuple with different time zone values. MATLAB ignores the Python datetime.datetime.fold attribute.

Suppose that a function returns a list, pyListOfDatetime. For the purpose of this example, create pyListOfDatetime with this code:

pdt1 = py.datetime.datetime.now()
pdt2 = py.datetime.datetime(year=int32(2022),month=int32(12),day=int32(28))
pyListOfDatetime = py.list({pdt1, pdt2})

pyListOfDatetime = 
  Python list with values:

    [datetime.datetime(2023, 5, 3, 13, 13, 16, 980815), datetime.datetime(2022, 12, 28, 0, 0)]

    Use string, double, datetime or cell function to convert to a MATLAB array.

Calculate the time difference between the two datetime objects:

mwdt = datetime(pyListOfDatetime);
caldiff(mwdt)

ans = 
   -4mo -6d -13h -13m -16.9808149999953s