matlab-proxy 0.18.2__py3-none-any.whl → 0.20.0__py3-none-any.whl

matlab_proxy/matlab/startup.m

@@ -1,25 +1,5 @@
 % Copyright 2020-2024 The MathWorks, Inc.
 
-% Configure logged in user if possible
-if ~isempty(getenv('MW_LOGIN_USER_ID'))
-    user_id = getenv('MW_LOGIN_USER_ID');
-    first_name = getenv('MW_LOGIN_FIRST_NAME');
-    last_name = getenv('MW_LOGIN_LAST_NAME');
-    email_address = getenv('MW_LOGIN_EMAIL_ADDRESS');
-    profile_id = getenv('MW_LOGIN_PROFILE_ID');
-    display_name = getenv('MW_LOGIN_DISPLAY_NAME');
-
-    li = com.mathworks.matlab_login.MatlabLogin.isUserLoggedIn(2, 'DESKTOP');
-    token = li.getToken();
-    login_level = 2;
-    remember_me = true;
-    li = com.mathworks.matlab_login.MatlabLogin.saveCacheLoginInfo(first_name, ...
-        last_name, email_address, user_id, token, profile_id, login_level, ...
-        remember_me, email_address, display_name);
-    % Clear all local variables from users workspace.
-    clear li login_level user_id first_name last_name email_address profile_id display_name token remember_me
-end
-
 if (strlength(getenv('MWI_BASE_URL')) > 0)
     connector.internal.setConfig('contextRoot', getenv('MWI_BASE_URL'));
 end

matlab_proxy/settings.py

@@ -194,6 +194,7 @@ def get_dev_settings(config):
         "mwa_login": f"https://login{ws_env_suffix}.mathworks.com",
         "mwi_custom_http_headers": mwi.custom_http_headers.get(),
         "env_config": mwi.validators.validate_env_config(config),
+        "integration_name": "MATLAB Desktop",
         "ssl_context": None,
         "mwi_logs_root_dir": get_mwi_logs_root_dir(dev=True),
         "mw_context_tags": get_mw_context_tags(matlab_proxy.get_default_config_name()),
@@ -209,6 +210,7 @@ def get_dev_settings(config):
         ),
         "warnings": [],
         "is_xvfb_available": False,
+        "mwi_idle_timeout": None,
     }
 
 
@@ -301,6 +303,14 @@ def get_server_settings(config_name):
     # log file validation check is already done in logger.py
     mwi_log_file = os.getenv(mwi_env.get_env_name_log_file(), None)
 
+    env_config = mwi.validators.validate_env_config(config_name)
+    short_desc = env_config["extension_name_short_description"]
+    integration_name = (
+        short_desc
+        if env_config["extension_name"] == matlab_proxy.get_default_config_name()
+        else f"{short_desc} - MATLAB Integration"
+    )
+
     return {
         "create_xvfb_cmd": create_xvfb_cmd,
         "base_url": mwi.validators.validate_base_url(
@@ -312,7 +322,8 @@ def get_server_settings(config_name):
         "app_port": mwi.validators.validate_app_port_is_free(
             os.getenv(mwi_env.get_env_name_app_port())
         ),
-        "env_config": mwi.validators.validate_env_config(config_name),
+        "env_config": env_config,
+        "integration_name": integration_name,
         "mwapikey": str(uuid.uuid4()),
         "matlab_protocol": "https",
         "matlab_config_file": mwi_config_folder / "proxy_app_config.json",
@@ -334,6 +345,10 @@ def get_server_settings(config_name):
             os.getenv(mwi_env.get_env_name_mwi_use_existing_license(), "")
         ),
         "ssl_context": _validate_ssl_files_and_get_ssl_context(mwi_config_folder),
+        # validate_idle_timeout converts the timeout from minutes to seconds
+        "mwi_idle_timeout": mwi.validators.validate_idle_timeout(
+            os.getenv(mwi_env.get_env_name_shutdown_on_idle_timeout())
+        ),
     }
 
 

matlab_proxy/util/__init__.py

@@ -1,6 +1,6 @@
 # Copyright 2020-2024 The MathWorks, Inc.
-
 import argparse
+import inspect
 import os
 import socket
 import time
@@ -15,6 +15,11 @@ from matlab_proxy.util.mwi.exceptions import (
     UIVisibleFatalError,
 )
 
+from matlab_proxy.util.mwi.exceptions import (
+    LockAcquisitionError,
+)
+
+
 logger = mwi.logger.get()
 
 # Global value to detect whether interrupt signal handler has been triggered or not.
@@ -276,3 +281,98 @@ def is_valid_path(path: Path):
     """
     path = Path(path)
     return path.is_dir() or path.is_file()
+
+
+def get_caller_name() -> str:
+    """Utility function that uses the `inspect` module to access the call stack and returns the name
+    of the function that is two levels above in the stack. This is typically the function
+    that called the function that invoked `get_caller_name`.
+
+    Ex: start_matlab() -> set_matlab_state() -> get_caller_name()
+    The return value from get_caller_name() would be `start_matlab`
+
+    Returns:
+        str: Name of the parent function.
+    """
+    try:
+        return inspect.stack()[2][3]
+
+    except Exception as err:
+        logger.error(f"Failed to get caller name with err:{err}")
+        stack = inspect.stack()
+        return stack[len(stack) - 1][3]
+
+
+class TrackingLock:
+    """A class which provides the same features as asyncio.Lock
+    and additionally tracks which function acquired the lock.
+    """
+
+    def __init__(self, purpose):
+        self._acquired_by = None
+        self._lock = asyncio.Lock()
+        if not purpose:
+            logger.warn("Provide a purpose for this instance of TrackingLock")
+        self._purpose = purpose
+
+    @property
+    def acquired_by(self):
+        return self._acquired_by
+
+    @property
+    def purpose(self):
+        return self._purpose
+
+    def locked(self):
+        return self._lock.locked()
+
+    async def acquire(self):
+        """Acquires the lock"""
+        await self._lock.acquire()
+        # Store the current task or function information when the lock is acquired
+        self._acquired_by = get_caller_name()
+        logger.debug(f"Lock acquired by '{self.acquired_by}()'")
+
+    async def release(self):
+        """Releases the lock."""
+        if self.locked():
+            # Clear the owner information when the lock is released
+            self._lock.release()
+            logger.debug(f"Lock released by '{self.acquired_by}()'")
+            self._acquired_by = None
+
+        else:
+            logger.warn(f"Trying to release {self._purpose} lock before acquiring it.")
+
+    def validate_lock_for_caller(self, caller):
+        """Checks if the specified caller is the current holder of the lock.
+
+        This method first verifies that the lock is currently held. If it is,
+        it then compares the holder's name with the provided caller's name
+        to ensure they match.
+
+        This function should be used by setter methods for verification, before they modify critical sections.
+
+        Args:
+        caller (str): The name of the function to be matched with the lock holder.
+
+        Returns:
+            bool: True if the caller currently holds the lock, False otherwise.
+        """
+        if not self._lock.locked():
+            logger.error(
+                LockAcquisitionError(
+                    f"Lock needs to be acquired by '{caller}()' before modifying {self._purpose}"
+                )
+            )
+            return False
+
+        if self._acquired_by != caller:
+            logger.error(
+                LockAcquisitionError(
+                    f"Lock was acquired by {self._acquired_by} but {self._purpose} is being modified by {caller}."
+                )
+            )
+            return False
+
+        return True

matlab_proxy/util/event_loop.py

@@ -1,8 +1,10 @@
-# Copyright 2020-2022 The MathWorks, Inc.
+# Copyright 2020-2024 The MathWorks, Inc.
+
+from typing import Dict, Set, Union
+from contextlib import suppress
 
 import asyncio
 
-from matlab_proxy import util
 from matlab_proxy.util import mwi, system, windows
 
 logger = mwi.logger.get()
@@ -30,16 +32,32 @@ def get_event_loop():
     return loop
 
 
-async def cancel_tasks(tasks):
+async def cancel_tasks(tasks: Union[Dict[str, asyncio.Task], Set[asyncio.Task]]):
     """Cancels asyncio tasks.
 
     Args:
-        tasks (asyncio.Task): Asyncio task
+        tasks: If a Dict[str, asyncio.Task], contains (task_name, task) as entries.
+               If a Set[asyncio.Task], contains a set of asyncio.Task objects.
+    """
+    if isinstance(tasks, dict):
+        for name, task in list(tasks.items()):
+            if task:
+                await __cancel_task(task)
+                logger.debug(f"{name} task stopped successfully")
+
+    elif isinstance(tasks, set):
+        for task in tasks:
+            if task:
+                await __cancel_task(task)
+                logger.debug(f"Task stopped successfully")
+
+
+async def __cancel_task(task):
+    """Cancels a given asyncio task, suppressing CancelledError.
+
+    Args:
+        task (asyncio.Task): The asyncio task to be cancelled.
     """
-    for task in tasks:
-        logger.debug(f"Calling cancel on task: {task}")
+    with suppress(asyncio.CancelledError):
         task.cancel()
-        try:
-            await task
-        except asyncio.CancelledError:
-            pass
+        await task

matlab_proxy/util/mwi/embedded_connector/__init__.py

@@ -1,4 +1,4 @@
 # Copyright (c) 2020-2022 The MathWorks, Inc.
 
 from . import helpers
-from .request import get_state, send_request
+from .request import get_busy_state, send_request

matlab_proxy/util/mwi/embedded_connector/helpers.py

@@ -46,6 +46,15 @@ def get_data_for_ping_request():
     return {"messages": {"Ping": [{}]}}
 
 
+def get_data_for_matlab_busy_status_request():
+    """Returns data required to send in the payload for a MATLAB busy/idle status request to the embedded connector
+
+    Returns:
+        dict: Payload data
+    """
+    return {"messages": {"GetMatlabStatus": [{}]}}
+
+
 def get_data_to_eval_mcode(m_code):
     """Returns the data required to send in the payload for evaluating mcode using eval function to the embedded connector.
 

matlab_proxy/util/mwi/embedded_connector/request.py

@@ -12,7 +12,11 @@ from matlab_proxy.util import mwi
 
 logger = mwi.logger.get()
 
-from .helpers import get_data_for_ping_request, get_ping_endpoint
+from .helpers import (
+    get_data_for_ping_request,
+    get_data_for_matlab_busy_status_request,
+    get_ping_endpoint,
+)
 
 
 async def send_request(url: str, data: dict, method: str, headers: dict = None) -> dict:
@@ -84,30 +88,56 @@ async def get_state(mwi_server_url, headers=None):
             headers=headers,
         )
 
-        # Additional assert statements to catch any changes in response from embedded connector
-        # Tested from R2020b to R2023a
-        assert (
-            "messages" in resp
-        ), '"messages" key missing in response from embedded connector'
-        assert (
-            "PingResponse" in resp["messages"]
-        ), '"PingResponse" key missing in response from embedded connector'
-        assert (
-            type(resp["messages"]["PingResponse"]) == list
-        ), 'Was expecting an array in the "PingResponse" field in response'
-        assert (
-            len(resp["messages"]["PingResponse"]) == 1
-        ), 'Was expecting an array of length 1 in the "PingResponse" field in response'
-        assert (
-            "messageFaults" in resp["messages"]["PingResponse"][0]
-        ), 'Was expecting "messageFaults" field in response'
-
+        # Any changes in response from embedded connector would be caught by KeyError
         if not resp["messages"]["PingResponse"][0]["messageFaults"]:
             return "up"
+
+    except KeyError as key_err:
+        logger.error(f"Invalid Key Usage Detected! Check key: {key_err}")
+
     except Exception as err:
         logger.debug(
-            f"{err}: Embedded connector is currently not responding to ping requests."
+            f"{err}: Embbeded connector is currently not responding to ping requests."
         )
-        pass
 
     return "down"
+
+
+async def get_busy_state(mwi_server_url, headers=None):
+    """Returns the state of MATLAB's Embedded Connector.
+
+    Args:
+        port (int): The port on which the embedded connector is running at
+        headers: Headers to include with the request
+    Returns:
+        str: Either "idle" or "busy" when a valid response is received. Else None is returned.
+    """
+    data = get_data_for_matlab_busy_status_request()
+    url = get_ping_endpoint(mwi_server_url)
+
+    busy_status = None
+
+    try:
+        resp = await send_request(
+            url=url,
+            data=data,
+            method="POST",
+            headers=headers,
+        )
+
+        busy_status = resp["messages"]["GetMatlabStatusResponse"][0]["status"].lower()
+
+        assert busy_status in [
+            "idle",
+            "busy",
+        ], f"Was expecting MATLAB busy status to be either 'idle' or 'busy', but received {busy_status} instead."
+
+    except KeyError as key_err:
+        logger.error(f"Invalid Key Usage Detected! Check key: {key_err}")
+
+    except Exception as err:
+        logger.debug(
+            f"{err}: Embedded connector is currently not responding to ping requests."
+        )
+
+    return busy_status

matlab_proxy/util/mwi/environment_variables.py

@@ -167,6 +167,11 @@ def get_env_name_custom_matlab_code():
     return "MWI_MATLAB_STARTUP_SCRIPT"
 
 
+def get_env_name_shutdown_on_idle_timeout():
+    """User specified timeout in minutes for shutdown on idle of matlab-proxy"""
+    return "MWI_SHUTDOWN_ON_IDLE_TIMEOUT"
+
+
 class Experimental:
     """This class houses functions which are undocumented APIs and Environment variables.
     Note: Never add any state to this class. Its only intended for use as an abstraction layer

matlab_proxy/util/mwi/exceptions.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2020-2023 The MathWorks, Inc.
+# Copyright 2020-2024 The MathWorks, Inc.
 
 
 class AppError(Exception):
@@ -165,6 +165,21 @@ class InvalidTokenError(AppError):
     pass
 
 
+class LockAcquisitionError(Exception):
+    """Exception raised when a lock is not properly acquired before modifying a variable.
+
+    This error is thrown in scenarios where:
+    1) A lock must be acquired before modifying a shared resource, but it wasn't.
+    2) The lock for a shared resource was acquired by one function, but another function attempts to modify the resource without holding the lock.
+
+
+    Args:
+        Exception : Python's inbuilt Exception Class.
+    """
+
+    pass
+
+
 def log_error(logger, err: Exception):
     """Logs any error to stdout.
 

matlab_proxy/util/mwi/logger.py

@@ -1,4 +1,4 @@
-# Copyright 2020-2023 The MathWorks, Inc.
+# Copyright 2020-2024 The MathWorks, Inc.
 """Functions to access & control the logging behavior of the app
 """
 
@@ -52,7 +52,17 @@ def __set_logging_configuration():
     # query for user specified environment variables
     log_level = os.getenv(
         mwi_env.get_env_name_logging_level(), __get_default_log_level()
-    )
+    ).upper()
+
+    valid = __is_valid_log_level(log_level)
+
+    if not valid:
+        default_log_level = __get_default_log_level()
+        logging.warn(
+            f"Unknown log level '{log_level}' set. Defaulting to log level '{default_log_level}'..."
+        )
+        log_level = default_log_level
+
     log_file = os.getenv(mwi_env.get_env_name_log_file(), None)
 
     ## Set logging object
@@ -110,3 +120,13 @@ def __get_default_log_level():
         String: The default logging level
     """
     return "INFO"
+
+
+def __is_valid_log_level(log_level):
+    """Helper to check if the log level is valid.
+
+    Returns:
+        Boolean: Whether log level  exists
+    """
+
+    return hasattr(logging, log_level)

matlab_proxy/util/mwi/validators.py

@@ -12,6 +12,7 @@ Exceptions are thrown to signal failure.
 """
 
 import errno
+import math
 import os
 import socket
 from pathlib import Path
@@ -344,3 +345,35 @@ def validate_matlab_root_path(matlab_root: Path, is_custom_matlab_root: bool):
         return None
 
     return matlab_root
+
+
+def validate_idle_timeout(timeout):
+    """Validate if IDLE timeout for matlab-proxy
+
+    Args:
+        timeout (None | int): IDLE timeout for shutdown of matlab-proxy.
+
+    Raises:
+        ValueError: If a non-numerical value is supplied other than None.
+
+    Returns:
+        None | int : The timeout value.
+    """
+    if not timeout:
+        return timeout
+
+    try:
+        # Convert timeout to seconds
+        timeout = math.ceil(float(timeout) * 60)
+
+        if timeout <= 0:
+            raise ValueError
+
+        logger.info(f"MATLAB IDLE timeout set to {timeout} seconds")
+        return timeout
+
+    except ValueError:
+        logger.warn(
+            f"Invalid value supplied for {mwi_env.get_env_name_shutdown_on_idle_timeout()}: {timeout}. Continuing without any IDLE timeout."
+        )
+        return None

matlab_proxy/util/windows.py

@@ -49,10 +49,13 @@ async def start_matlab(matlab_cmd, matlab_env):
     """
     import psutil
 
+    # The stdout is used to suppress the MATLAB outputs from being shown in the terminal.
+    # We set it to DEVNULL instead of PIPE because PIPE has a limited buffer size and can
+    # block the process if the output exceeds the buffer limit.
     intermediate_proc = await asyncio.create_subprocess_exec(
         *matlab_cmd,
         env=matlab_env,
-        stdout=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.DEVNULL,
         stderr=asyncio.subprocess.STDOUT,
     )
 

{matlab_proxy-0.18.2.dist-info → matlab_proxy-0.20.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: matlab-proxy
-Version: 0.18.2
+Version: 0.20.0
 Summary: Python® package enables you to launch MATLAB® and access it from a web browser.
 Home-page: https://github.com/mathworks/matlab-proxy/
 Author: The MathWorks, Inc.
@@ -17,24 +17,24 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Requires-Python: ~=3.8
 Description-Content-Type: text/markdown
-Requires-Dist: aiohttp >=3.7.4
+Requires-Dist: aiohttp>=3.7.4
 Requires-Dist: aiohttp-session[secure]
 Requires-Dist: importlib-metadata
 Requires-Dist: importlib-resources
 Requires-Dist: psutil
 Provides-Extra: dev
-Requires-Dist: aiohttp-devtools ; extra == 'dev'
-Requires-Dist: black ; extra == 'dev'
-Requires-Dist: pytest ; extra == 'dev'
-Requires-Dist: pytest-env ; extra == 'dev'
-Requires-Dist: pytest-cov ; extra == 'dev'
-Requires-Dist: pytest-timeout ; extra == 'dev'
-Requires-Dist: pytest-mock ; extra == 'dev'
-Requires-Dist: pytest-aiohttp ; extra == 'dev'
-Requires-Dist: psutil ; extra == 'dev'
-Requires-Dist: urllib3 ; extra == 'dev'
-Requires-Dist: requests ; extra == 'dev'
-Requires-Dist: pytest-playwright ; extra == 'dev'
+Requires-Dist: aiohttp-devtools; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-env; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: pytest-aiohttp; extra == "dev"
+Requires-Dist: psutil; extra == "dev"
+Requires-Dist: urllib3; extra == "dev"
+Requires-Dist: requests; extra == "dev"
+Requires-Dist: pytest-playwright; extra == "dev"
 
 # MATLAB Proxy
 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mathworks/matlab-proxy/run-tests.yml?branch=main&logo=github)](https://github.com/mathworks/matlab-proxy/actions)   [![PyPI badge](https://img.shields.io/pypi/v/matlab-proxy.svg?logo=pypi)](https://pypi.python.org/pypi/matlab-proxy)    [![codecov](https://codecov.io/gh/mathworks/matlab-proxy/branch/main/graph/badge.svg?token=ZW3SESKCSS)](https://codecov.io/gh/mathworks/matlab-proxy)   [![Downloads](https://static.pepy.tech/personalized-badge/matlab-proxy?period=month&units=international_system&left_color=grey&right_color=blue&left_text=PyPI%20downloads/month)](https://pepy.tech/project/matlab-proxy)
@@ -201,7 +201,7 @@ $ pip install --upgrade matlab-proxy>=0.5.0
 
 ### Windows Subsystem for Linux (WSL 2)
 
-To install `matlab-proxy` in WSL 2, follow the steps mentioned in the [Installation Guide for WSL 2](./installation/wsl2/README.md).
+To install `matlab-proxy` in WSL 2, follow the steps mentioned in the [Installation Guide for WSL 2](./install_guides/wsl2/README.md).
 
 ## Using an already activated MATLAB with matlab-proxy
 `matlab-proxy` version `v0.7.0` introduces support for using an existing MATLAB license. Use the Existing License option only if you have an activated MATLAB. This allows you to start MATLAB without authenticating every time.