|
| 1 | +# Copyright 2025 The MathWorks, Inc. |
| 2 | + |
| 3 | +import argparse |
| 4 | +import errno |
| 5 | +import json |
| 6 | +import pathlib |
| 7 | +import shutil |
| 8 | +import sys |
| 9 | +import tempfile |
| 10 | +from datetime import datetime |
| 11 | + |
| 12 | +from jupyter_client import kernelspec |
| 13 | + |
| 14 | +STANDARD_PYTHON_EXECUTABLE = "python3" |
| 15 | + |
| 16 | + |
| 17 | +def get_kernel_spec(executable=None) -> dict: |
| 18 | + """ |
| 19 | + Generate and return the kernelspec JSON for the MATLAB Kernel. |
| 20 | +
|
| 21 | + This function creates a dictionary containing the necessary configuration |
| 22 | + for the MATLAB Kernel to be used with Jupyter. The kernelspec includes |
| 23 | + information such as the command to start the kernel, display name, |
| 24 | + language, and other metadata. |
| 25 | +
|
| 26 | + For more information about kernelspecs, see: |
| 27 | + https://jupyter-client.readthedocs.io/en/latest/kernels.html#kernelspecs |
| 28 | +
|
| 29 | + Args: |
| 30 | + executable (str, optional): The Python executable to use. Defaults to python3. |
| 31 | +
|
| 32 | + Returns: |
| 33 | + dict: A dictionary containing the kernelspec configuration for the MATLAB Kernel. |
| 34 | + """ |
| 35 | + if not executable: |
| 36 | + executable = STANDARD_PYTHON_EXECUTABLE |
| 37 | + |
| 38 | + copyright_start_year = 2023 |
| 39 | + copyright_end_year = datetime.now().year |
| 40 | + |
| 41 | + kernelspec_json = { |
| 42 | + "argv": [ |
| 43 | + executable, |
| 44 | + "-m", |
| 45 | + "jupyter_matlab_kernel", |
| 46 | + "-f", |
| 47 | + "{connection_file}", |
| 48 | + ], |
| 49 | + "display_name": "MATLAB Kernel", |
| 50 | + "language": "matlab", |
| 51 | + "interrupt_mode": "message", |
| 52 | + "env": {}, |
| 53 | + "metadata": { |
| 54 | + "debugger": False, |
| 55 | + "copyright": f"Copyright {copyright_start_year}-{copyright_end_year} The MathWorks, Inc.", |
| 56 | + "description": "Jupyter kernelspec for MATLAB Kernel. For more information, please look at https://jupyter-client.readthedocs.io/en/stable/kernels.html#kernel-specs", |
| 57 | + }, |
| 58 | + } |
| 59 | + return kernelspec_json |
| 60 | + |
| 61 | + |
| 62 | +def install_kernel_spec( |
| 63 | + kernel_name: str, executable: str, kernelspec_dir, register_with_jupyter=True |
| 64 | +): |
| 65 | + """ |
| 66 | + Install the MATLAB Kernel kernelspec to the specified directory. |
| 67 | +
|
| 68 | + Args: |
| 69 | + kernel_name (str): The name of the kernel to be installed. |
| 70 | + executable (str): The Python executable path to use for the kernelspec. |
| 71 | + kernelspec_dir (Path | str): The directory to install the kernelspec. |
| 72 | + register_with_jupyter (bool): Whether to register the kernelspec with Jupyter. Defaults to True. If True, |
| 73 | + the kernelspec will be installed to <prefix>/share/jupyter/kernels/<kernel_name>. |
| 74 | +
|
| 75 | + Returns: |
| 76 | + tuple: A tuple containing the destination path of the installed kernelspec and the kernelspec dictionary. |
| 77 | + """ |
| 78 | + kernelspec_dict = get_kernel_spec(executable) |
| 79 | + kernel_json_path = pathlib.Path(kernelspec_dir) / "kernel.json" |
| 80 | + |
| 81 | + # Copy kernelspec resources to the target directory |
| 82 | + shutil.copytree(pathlib.Path(__file__).parent / "kernelspec", kernelspec_dir) |
| 83 | + |
| 84 | + # Write the kernelspec to the kernel.json file |
| 85 | + with kernel_json_path.open("w") as f: |
| 86 | + json.dump(kernelspec_dict, f, indent=4) |
| 87 | + |
| 88 | + if register_with_jupyter: |
| 89 | + dest = kernelspec.install_kernel_spec( |
| 90 | + str(kernelspec_dir), kernel_name, prefix=sys.prefix |
| 91 | + ) |
| 92 | + else: |
| 93 | + dest = str(kernelspec_dir) |
| 94 | + return dest, kernelspec_dict |
| 95 | + |
| 96 | + |
| 97 | +def main(): |
| 98 | + """ |
| 99 | + Main function for installing or resetting the Jupyter kernelspec for MATLAB Kernel. |
| 100 | +
|
| 101 | + This function parses command-line arguments to determine whether to install |
| 102 | + or reset the kernelspec. It then calls the appropriate functions to perform |
| 103 | + the requested action and prints the result. |
| 104 | +
|
| 105 | + The function supports the following options: |
| 106 | + --reset: Reset the kernelspec to use the standard Python executable. |
| 107 | +
|
| 108 | + If no option is provided, it installs the kernelspec using the current Python executable. |
| 109 | +
|
| 110 | + Raises: |
| 111 | + OSError: If there's a permission error during installation. |
| 112 | +
|
| 113 | + """ |
| 114 | + parser = argparse.ArgumentParser( |
| 115 | + prog="install-matlab-kernelspec", |
| 116 | + description="Install or Reset Jupyter kernelspec for MATLAB Kernel", |
| 117 | + ) |
| 118 | + parser.add_argument( |
| 119 | + "--reset", |
| 120 | + action="store_true", |
| 121 | + help="Reset the kernelspec to the default configuration", |
| 122 | + ) |
| 123 | + parser.add_argument( |
| 124 | + "--preview", |
| 125 | + action="store_true", |
| 126 | + help="Preview the changes made to kernelspec", |
| 127 | + ) |
| 128 | + args = parser.parse_args() |
| 129 | + |
| 130 | + kernel_name = str(pathlib.Path(__file__).parent.name) |
| 131 | + if args.reset: |
| 132 | + executable = STANDARD_PYTHON_EXECUTABLE |
| 133 | + else: |
| 134 | + executable = sys.executable |
| 135 | + |
| 136 | + register_kernelspec_with_jupyter = True |
| 137 | + if args.preview: |
| 138 | + register_kernelspec_with_jupyter = False |
| 139 | + |
| 140 | + try: |
| 141 | + kernelspec_dir = pathlib.Path(tempfile.mkdtemp()) / kernel_name |
| 142 | + dest, kernelspec_dict = install_kernel_spec( |
| 143 | + kernel_name=kernel_name, |
| 144 | + executable=executable, |
| 145 | + kernelspec_dir=kernelspec_dir, |
| 146 | + register_with_jupyter=register_kernelspec_with_jupyter, |
| 147 | + ) |
| 148 | + except OSError as e: |
| 149 | + if e.errno == errno.EACCES: |
| 150 | + print(e, file=sys.stderr) |
| 151 | + sys.exit(1) |
| 152 | + raise |
| 153 | + |
| 154 | + if args.preview: |
| 155 | + # Replace the destination path to be displayed to the user with the path where the kernelspec would be installed without the dry run mode. |
| 156 | + dest = str( |
| 157 | + pathlib.Path(sys.prefix) / "share" / "jupyter" / "kernels" / kernel_name |
| 158 | + ) |
| 159 | + print( |
| 160 | + f"The following kernelspec for {kernel_name} would be installed in {dest}\n{json.dumps(kernelspec_dict, indent=4)}" |
| 161 | + ) |
| 162 | + sys.exit(0) |
| 163 | + |
| 164 | + print( |
| 165 | + f"Installed the following kernelspec for {kernel_name} in {dest}\n{json.dumps(kernelspec_dict, indent=4)}" |
| 166 | + ) |
0 commit comments