Introducing support for MATLAB R2023b

fixes #50

Author: rashedmyt

limitations.md

@@ -22,11 +22,11 @@ This package has some constraints and limitations:
     |![truncation-issue](https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/truncation-issue.png)|
     |-|
 
-* Handles for graphics objects are scoped to a single cell. For example:
+* Handles for graphics objects are scoped to a single cell in MATLAB versions <= R2023a. For example:
     |![invalid-handle](https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/invalid-handle.png)|
     |-|
 
-* Graphics functions like `gca, gcf, gco, gcbo, gcbf, clf, cla`, which access `current` handles, are scoped to a single notebook cell. The following example illustrates this:
+* Graphics functions like `gca, gcf, gco, gcbo, gcbf, clf, cla`, which access `current` handles, are scoped to a single notebook cell in MATLAB versions <= R2023a. The following example illustrates this:
     |![gca-issue](https://github.com/mathworks/jupyter-matlab-proxy/raw/main/img/gca-issue.png)|
     |-|
 

src/jupyter_matlab_kernel/kernel.py

@@ -293,7 +293,7 @@ def do_execute(
             # Perform execution and categorization of outputs in MATLAB. Blocks
             # until execution results are received from MATLAB.
             outputs = mwi_comm_helpers.send_execution_request_to_matlab(
-                self.murl, self.headers, code
+                self.murl, self.headers, code, self.ident
             )
 
             # Clear the output area of the current cell. This removes any previous
@@ -399,7 +399,9 @@ def do_history(
         )
 
     def do_shutdown(self, restart):
-        # TODO: Implement clean-up
+        mwi_comm_helpers.send_shutdown_request_to_matlab(
+            self.murl, self.headers, self.ident
+        )
         return super().do_shutdown(restart)
 
     # Helper functions

src/jupyter_matlab_kernel/matlab/+jupyter/execute.m

@@ -3,7 +3,7 @@
 % change without any prior notice. Usage of these undocumented APIs outside of
 % these files is not supported.
 
-function result = execute(code)
+function result = execute(code, kernelId)
 % EXECUTE A helper function for handling execution of MATLAB code and post-processing
 % the outputs to conform to Jupyter API. We use the Live Editor API for majority
 % of the work.
@@ -17,13 +17,13 @@
 % Embed user MATLAB code in a try-catch block for MATLAB versions less than R2022b.
 % This is will disable inbuilt ErrorRecovery mechanism. Any exceptions created in
 % user code would be handled by +jupyter/getOrStashExceptions.m
-if verLessThan('matlab', '9.13')
+if isMATLABReleaseOlderThan("R2022b")
     code = sprintf(['try\n'...
-                    '%s\n'...
-                    'catch JupyterKernelME\n'...
-                    'jupyter.getOrStashExceptions(JupyterKernelME)\n'...
-                    'clear JupyterKernelME\n'...
-                    'end'], code);
+        '%s\n'...
+        'catch JupyterKernelME\n'...
+        'jupyter.getOrStashExceptions(JupyterKernelME)\n'...
+        'clear JupyterKernelME\n'...
+        'end'], code);
 end
 
 % Value that needs to be shown in the error message when a particular error
@@ -32,17 +32,16 @@
 fileToShowErrors = 'Notebook';
 
 % Prepare the input for the Live Editor API.
-jsonedRegionList = jsonencode(struct(...
-    'regionLineNumber',1,...
-    'regionString',code,...
-    'regionNumber',0,...
-    'endOfSection',true,...
-    'sectionNumber',1));
+% 'requestId'   - char array - UUID
+% 'editorId'    - char array - unique identifier usually corresponding to a file.
 request = struct('requestId', 'jupyter_matlab_kernel',...
-    'regionArray', jsonedRegionList,...
+    'editorId', kernelId,...
     'fullText', code,...
     'fullFilePath', fileToShowErrors);
 
+% Update additional fields in the request based on MATLAB and LiveEditor API version.
+request = updateRequest(request, code);
+
 % Disable Hotlinks in the output captured. The hotlinks do not have a purpose
 % in Jupyter notebooks.
 hotlinksPreviousState = feature('hotlinks','off');
@@ -54,6 +53,49 @@
 % Post-process the outputs to conform to Jupyter API.
 result = processOutputs(resp.outputs);
 
+% Helper function to update fields in the request based on MATLAB and LiveEditor
+% API version.
+function request = updateRequest(request, code)
+% Support for MATLAB version <= R2023a.
+if isMATLABReleaseOlderThan("R2023b")
+    request = updateRequestFromBefore23b(request, code);
+else
+    % Support for MATLAB version >= R2023b.
+    
+    % To maintain backwards compatibility, each case in the switch
+    % encodes conversion from the version number in the case
+    % to the current version.
+    switch matlab.internal.editor.getApiVersion('synchronous')
+        case 1
+            request = updateRequestFromVersion1(request, code);
+        otherwise
+            error("Invalid API version. Create an issue at https://github.com/mathworks/jupyter-matlab-proxy for further support.");
+    end
+end
+
+% Helper function to update fields in the request for MATLAB versions less than
+% R2023b
+function request = updateRequestFromBefore23b(request, code)
+jsonedRegionList = jsonencode(struct(...
+    'regionLineNumber',1,...
+    'regionString',code,...
+    'regionNumber',0,...
+    'endOfSection',true,...
+    'sectionNumber',1));
+request.regionArray = jsonedRegionList;
+
+% Helper function to update fields in the request when LiveEditor API version is 1.
+function request = updateRequestFromVersion1(request, code)
+request.sectionBoundaries = [];
+request.startLine = 1;
+request.endLine = numel(splitlines(code));
+
+% Allow figures to be used across Notebook cells. Cleanup needs to be
+% done explicitly when the kernel shutsdown.
+request.shouldResetState = false;
+request.shouldDoFullCleanup = false;
+
+% Helper function to process different types of outputs given by LiveEditor API.
 function result = processOutputs(outputs)
 result =cell(1,length(outputs));
 figureTrackingMap = containers.Map;
@@ -137,11 +179,11 @@
 
 if isempty(webwindow)
     url = 'toolbox/matlab/codetools/liveeditor/index.html';
-
+    
     % MATLAB versions R2020b and R2021a requires specifying the base url.
     % Not doing so results in the URL not being loaded with the error
     %"Not found. Request outside of context root".
-    if verLessThan('matlab','9.11')
+    if isMATLABReleaseOlderThan("R2021b")
         url = strcat(getenv("MWI_BASE_URL"), '/', url);
     end
     webwindow = matlab.internal.cef.webwindow(connector.getUrl(url));

src/jupyter_matlab_kernel/matlab/+jupyter/shutdown.m

@@ -0,0 +1,19 @@
+% IMPORTANT NOTICE:
+% This file may contain calls to MathWorks internal APIs which are subject to
+% change without any prior notice. Usage of these undocumented APIs outside of
+% these files is not supported.
+
+function output = shutdown(kernelId)
+% SHUTDOWN A helper function to perform cleanup activities when a kernel shuts down.
+
+% Copyright 2023 The MathWorks, Inc.
+
+import matlab.internal.editor.SynchronousEvaluationOutputsService
+
+% Perform LiveEditor state cleanup of a given notebook in MATLAB versions >= R2023b
+if ~isMATLABReleaseOlderThan("R2023b")
+    SynchronousEvaluationOutputsService.cleanup(kernelId);
+end
+
+output = {};
+end

src/jupyter_matlab_kernel/matlab/processJupyterKernelRequest.m

@@ -11,9 +11,12 @@
 %                                   on value of input request_type
 %                                   - "execute"
 %                                      - string - MATLAB code to be executed
+%                                      - string - ID of the kernel
 %                                   - "complete"
 %                                      - string - MATLAB code
 %                                      - number - cursor position
+%                                   - "shutdown"
+%                                      - string - ID of the kernel
 %   Outputs:
 %       - cell array on struct
 %           - type      - string - jupyter output type. Supported values are
@@ -47,10 +50,14 @@
 try
     switch(request_type)
         case 'execute'
-            output = jupyter.execute(code);
+            kernelId = varargin{2};
+            output = jupyter.execute(code, kernelId);
         case 'complete'
             cursorPosition = varargin{2};
             output = jupyter.complete(code, cursorPosition);
+        case 'shutdown'
+            kernelId = varargin{1};
+            output = jupyter.shutdown(kernelId);
     end
 catch ME
     % The code withing try block should be exception safe. In case anything we

src/jupyter_matlab_kernel/mwi_comm_helpers.py

@@ -52,23 +52,23 @@ def check_licensing_status(data):
     return licensing_status
 
 
-def send_execution_request_to_matlab(url, headers, code):
+def send_execution_request_to_matlab(url, headers, code, kernelid):
     """
     Evaluate MATLAB code and capture results.
 
     Args:
-        kernelid (string): A unique kernel identifier.
         url (string): Url of matlab-proxy server
         headers (dict): HTTP headers required for communicating with matlab-proxy
         code (string): MATLAB code to be evaluated
+        kernelid (string): A unique kernel identifier.
 
     Returns:
         List(dict): list of outputs captured during evaluation.
 
     Raises:
         HTTPError: Occurs when connection to matlab-proxy cannot be established.
     """
-    return _send_jupyter_request_to_matlab(url, headers, "execute", [code])
+    return _send_jupyter_request_to_matlab(url, headers, "execute", [code, kernelid])
 
 
 def send_completion_request_to_matlab(url, headers, code, cursor_pos):
@@ -101,6 +101,21 @@ def send_completion_request_to_matlab(url, headers, code, cursor_pos):
     return _send_jupyter_request_to_matlab(url, headers, "complete", [code, cursor_pos])
 
 
+def send_shutdown_request_to_matlab(url, headers, kernelid):
+    """
+    Perform cleanup tasks related to kernel shutdown.
+
+    Args:
+        url (string): Url of matlab-proxy server
+        headers (dict): HTTP headers required for communicating with matlab-proxy
+        kernelid (string): A unique kernel identifier.
+
+    Raises:
+        HTTPError: Occurs when connection to matlab-proxy cannot be established.
+    """
+    return _send_jupyter_request_to_matlab(url, headers, "shutdown", [kernelid])
+
+
 def send_interrupt_request_to_matlab(url, headers):
     req_body = {
         "messages": {

tests/unit/jupyter_matlab_kernel/test_mwi_comm_helpers.py

@@ -103,8 +103,9 @@ def mock_post(*args, **kwargs):
     url = ""
     headers = {}
     code = "placeholder for code"
+    kernelid = ""
     with pytest.raises(HTTPError) as exceptionInfo:
-        send_execution_request_to_matlab(url, headers, code)
+        send_execution_request_to_matlab(url, headers, code, kernelid)
     assert mock_exception_message in str(exceptionInfo.value)
 
 
@@ -133,8 +134,9 @@ def mock_post(*args, **kwargs):
     url = ""
     headers = {}
     code = "placeholder for code"
+    kernelid = ""
     with pytest.raises(HTTPError) as exceptionInfo:
-        send_execution_request_to_matlab(url, headers, code)
+        send_execution_request_to_matlab(url, headers, code, kernelid)
     assert str(exceptionInfo.value) == ""
 
 
@@ -175,8 +177,9 @@ def mock_post(*args, **kwargs):
     url = ""
     headers = {}
     code = "placeholder for code"
+    kernelid = ""
     with pytest.raises(Exception) as exceptionInfo:
-        send_execution_request_to_matlab(url, headers, code)
+        send_execution_request_to_matlab(url, headers, code, kernelid)
     assert "Operation may have interrupted by user" in str(exceptionInfo.value)
 
 
@@ -212,8 +215,9 @@ def mock_post(*args, **kwargs):
     url = ""
     headers = {}
     code = "placeholder for code"
+    kernelid = ""
     try:
-        outputs = send_execution_request_to_matlab(url, headers, code)
+        outputs = send_execution_request_to_matlab(url, headers, code, kernelid)
     except Exception as exceptionInfo:
         pytest.fail("Unexpected failured in execution request")