Add IOP.Wrapper class for simplified Python module import with remote debugging support; update changelog and documentation

Author: grongierisc

CHANGELOG.md

@@ -6,6 +6,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [unreleased] - Unreleased
+### Added
+- New IOP.Wrapper class for simplified python module import into IRIS with remote debugging support and traceback handling
+ 
 ### Changed
 - Improve module loading and initialization for better performance in BusinessProcess by checking if the module is already loaded
 - Change OnMessage to MessageHandler in BusinessOperation for better performance and clarity

demo/python/non_production/my_script.py

@@ -0,0 +1,12 @@
+import os
+
+def main():
+    # Get the value of the environment variable
+    my_env_var = os.getenv('MY_ENV_VAR', 'default_value')
+    
+    # Print the value of the environment variable
+    print(f'MY_ENV_VAR: {my_env_var}')
+
+
+if __name__ == "__main__":
+    main()

docs/wrapper.md

@@ -0,0 +1,42 @@
+# IoP.Wrapper
+
+IoP.Wrapper is a class designed to simplify the import of Python modules into InterSystems IRIS, providing remote debugging support and handling tracebacks effectively. It is particularly useful for developers who want to integrate Python code with IRIS while maintaining a smooth debugging experience.
+
+## Features
+
+- **Simplified Module Import**: Easily import Python modules into IRIS without complex configurations.
+- **Remote Debugging Support**: Debug Python code running in IRIS from your local development environment.
+- **Traceback Handling**: Automatically capture and format Python tracebacks for easier debugging.
+
+## Usage
+
+To use IoP.Wrapper, simply use the helper method `Import` to import your Python module. The method will handle the rest, including setting up the necessary environment for remote debugging and managing tracebacks.
+
+```python
+# my_script.py
+import os
+
+def main():
+    # Get the value of the environment variable
+    my_env_var = os.getenv('MY_ENV_VAR', 'default_value')
+    
+    # Print the value of the environment variable
+    print(f'MY_ENV_VAR: {my_env_var}')
+
+
+if __name__ == "__main__":
+    main()
+```
+
+The ObjectScript code to import the Python module would look like this:
+
+```objectscript
+Set pythonModule = "my_script"
+Set pythonPath = "/path/to/your/python/scripts"
+Set debugPort = 5678  ; Set the port for remote debugging
+Set myModule = ##class(IoP.Wrapper).Import(pythonModule, pythonPath, debugPort)
+// The process will automatically handle the import and setup for remote debugging and wait for the client debugger to attach.
+// Once the client debugger is attached, you can run the main function of your Python module.
+do myModule.main()
+```
+

mkdocs.yml

@@ -18,6 +18,7 @@ nav:
     - Debugging: debug.md
     - Production Settings: prod-settings.md
     - Venv Support: venv.md
+    - Wrapper Support: wrapper.md
   - Contributing:
     - Contributing: contributing.md
     - Code of Conduct: code-of-conduct.md

src/iop/_debugpy.py

@@ -142,4 +142,46 @@ def debugpython(self, host_object: Any) -> None:
         else:
             self.log_alert(f"Debugpy connection timed out after {host_object._timeout} seconds")
     except Exception as e:
-        self.log_alert(f"Error enabling debugpy: {e}")
+        self.log_alert(f"Error enabling debugpy: {e}")
+
+def debugpy_in_iris(iris_dir, port) -> bool:
+
+    if not hasattr(os, '__file__'):
+        setattr(os, '__file__', __file__)
+
+    if not is_debugpy_installed():
+        print("debugpy is not installed.")
+        return False
+    if not iris_dir:
+        print("IRIS directory is not specified.")
+        return False
+    
+    import debugpy
+    python_path = _get_python_interpreter_path(mgr_dir_to_install_dir(iris_dir))
+    if not python_path:
+        return False
+    debugpy.configure(_get_debugpy_config(python_path))
+
+    try:
+        enable_debugpy(port=port)
+    except Exception as e:
+        print(f"Failed to enable debugpy: {e}")
+        return False
+
+    print(f"Debugpy is waiting for connection on port {port}...")
+    if wait_for_debugpy_connected(timeout=30, port=port):
+        print(f"Debugpy is connected on port {port}")
+        return True
+    else:
+        print(f"Debugpy connection timed out after 30 seconds on port {port}")
+        return False
+
+def mgr_dir_to_install_dir(mgr_dir: str) -> Optional[str]:
+    """Convert manager directory to install directory."""
+    import os
+    if not mgr_dir:
+        return None
+    install_dir = os.path.dirname(os.path.dirname(mgr_dir))
+    if os.path.exists(install_dir):
+        return install_dir
+    return None

src/iop/cls/IOP/Wrapper.cls

@@ -0,0 +1,58 @@
+Class IOP.Wrapper Extends %RegisteredObject
+{
+
+ClassMethod Import(
+	moduleName As %String,
+	path As %String = "",
+	debugPort As %Integer = 0) As %Status
+{
+    set tSC = $$$OK
+    Try {
+        do ##class(IOP.Common).SetPythonPath(path)
+        // For traceback debugging
+        do $system.Python.Debugging(1)
+        if debugPort > 0 {
+            
+            set debugpy = ##class(%SYS.Python).Import("iop._debugpy")
+            do debugpy."debugpy_in_iris"($zu(12),debugPort)
+        }
+
+        // Import the module
+        set tModule = ##class(%SYS.Python).Import(moduleName)
+
+    }
+    Catch ex {
+        Set tSC= ##class(IOP.Wrapper).DisplayTraceback(ex)
+        throw ex
+    }
+    return tModule
+}
+
+ClassMethod DisplayTraceback(ex) As %Status
+{
+    set tSC = ex.AsStatus()
+
+    // Import Modules
+    set sys = ##class(%SYS.Python).Import("sys")
+    set tracebackModule = ##class(%SYS.Python).Import("traceback")
+    set builtins = ##class(%SYS.Python).Import("builtins")
+    // Get the last traceback
+    set traceback = sys."last_traceback"
+    set exType = sys."last_type"."__name__"
+    set exValue = sys."last_value"."__str__"()
+    // Check if traceback is an object
+    if $isObject(traceback) {
+        // Format the traceback
+        set tb = tracebackModule."format_exception"(sys."last_type", sys."last_value", traceback)
+        set tbString = ""
+        for i=0:1:(tb."__len__"()-1) {
+            set tbString = tbString _ $c(10)_$c(13) _ tb."__getitem__"(i)
+        }
+        w tbString
+        set tSC = $$$ERROR("Exception in Python - "_exType_" - "_exValue)
+    }
+    
+    return tSC
+}
+
+}