Debug from Embedded Python

Initializing Configurations

VS Code’s debugging configurations determine the behavior of debugging sessions. The launch.json file defines the configuration. To open the file, which is located in the.vscode folder in your work space, complete the following steps:

1. Select the Run and Debug (Crtl+Shift+D) tab on the left sidebar of the VS Code window.

2. Select the option to create a launch.json file.

3. Choose the Python Debugger from the list of debuggers.

   Note:

   You must have the Python Debugger extension for VS Code installed to see it on the list of available options. See Python debugging in VS CodeOpens in a new tab for more details.

4. Select the Remote Attach option from the debug configuration menu.

5. Enter local host in the Remote Debugging (1/2) menu.

6. Specify 5678 as the port number in the Remote Debugging (2/2) menu.

This will generate a launch.json file that should look like the following:

{
	"version": "0.2.0",
	"configurations": [
		
			"name": "Python Debugger: Remote Attach",
			"type": "debugpy",
			"request": "attach",
			"connect": {
				"host": "localhost",
				"port": 5678
			},
			"pathMappings": [
				{
					"localRoot": "${workspaceFolder}",
					"remoteRoot": "."
				}
			]
		}
	] 
}

Now, a VS Code debugging session will look for Python on port 5678. You can use this launch.json file to run session regardless of the environment you choose to debug in (i.e. local or Docker).

Running a Session Locally

Using the VS Code debugger configuration as above, you can run a debugger session locally.

Run the following in the command line to start the debugger at port 5678:

/<path to IRIS>/bin/irispython -m debugpy --listen localhost:5678 --wait-for-client <python file name>.py

In the command above, --listen localhost:5678 tells the debug adapter server to wait fro connections at port 5678 from the local host. --wait-for-client prevents the Python script from executing until there is a connection from the debug server.

Now, run the debugger by either selecting Python Debugger: Remote Attach (as specified in launch.json) in the VS Code debugging tab or by pressing F5. This will start a debugging session with the Python file you entered in the command line above.

You can now debug in VS Code just as with any debugger you are familiar with.

Visit Debug Code with Visual Studio CodeOpens in a new tab to find more details about debugging in VS Code and Run Embedded Python to find more documentation about Embedded Python in Python script files (.py).

Running a Session through Docker

Running a debugging session with InterSystems IRIS in a Docker image utilizes the same configuration as with InterSystems IRIS on your local computer.

Docker Setup

Create a new InterSystems IRIS container with the following in the command line:

docker run --name iris -d --publish 9091:1972 --publish 9092:52773 --publish 5678:5678 intersystems/iris-community:latest-cd

The arguments above specify the ports from your host machine that will be exposed to communicate with services running inside the container and the container itself:

• The 1972 Superserver Port is used by InterSystems IRIS for network protocols.

• The 52773 Web Server Port is used by InterSystems IRIS for the Management Portal.

• The 5678 Debugging Port is the same as the one specified in the launch.json file defined in Initializing Configurations.

• intersystems/iris-community:latest-cd is the name of the container that you will run.

Launch the container by running docker start iris. You can check whether the container is active with docker ps.

The container must have information on your InterSystems IRIS credentials. Once the container is active, go into the container’s Linux environment through docker exec -it iris bash. Then, enter the following to insert the credentials (replace these values with your credentials) needed to authenticate yourself:

export IRISUSERNAME=SuperUser
export IRISPASSWORD=sys
export IRISNAMESPACE=USER

Note:

You can also set these credentials and save them in the container by using bind mountsOpens in a new tab, which allow the container to access persisting files. The bind mount links files or directories from the host machine into the container.

Now, open a browser and log into the Management Portal of the containerized instance through http://localhost:9092/csp/sys/UtilHome.csp. Navigate to the Services page and enable %Service_CallIn to give Docker access to InterSystems IRIS services.

Inside the container environment, run pip install debupy --break-system-packages to install debupy inside the container. This will be the debugger that you will be using to run against your Python scripts.

Running a Session through Docker Dev Containers

You can work directly inside the Docker container environment by using the VS Code Dev ContainersOpens in a new tab extension. This way, you can directly create and edit files in the container on VS Code and run them just as if they were local on your machine. Make sure to follow the same instructions for Docker Setup. Run the container with docker start iris. Open a remote window on VS Code through the bottom-left corner.

Select Attach to Running Container in the menu that pops up. Then choose the appropriate container when prompted. This will open a new VS Code window connected to the InterSystems IRIS container you just started.

Once the new window opens, you can proceed development and debugging just as in Running a Session Locally:

• Create the file launch.json through the Remote Attach option.

• Start the debugger with <path to irissys>/bin/irispython -m debugpy --listen 0.0.0.0:5678 --wait-for-client ../../../bin<file name>.py -Xfrozen_modules=off.

• Run the VS Code debugger with the defined configurations.

You should be able to see the container that you are running on your window.

See VS Code’s Developing inside a ContainerOpens in a new tab for more details on debugging with the Dev Containers extension. You can also look through articles on the Developer CommunityOpens in a new tab such as Python REST CRUD templateOpens in a new tab, Running InterSystems IRIS with DockerOpens in a new tab, and Calling Embedded Python in Docker ContainerOpens in a new tab to find more content on Embedded Python debugging.