API debugging guidelines

Note

This is an opinionated guide that only applies to VS Code users. If you use a different editor or IDE, these instructions will not apply to you.

This is the guide to debugging the API using VS Code. This uses Microsoft’s debugpy package.

Prerequisites

1. Install the Python Debugger extension.

2. Set up a VS Code workspace for the Openverse monorepo.

Steps

1. Add a launch configuration to the Openverse workspace configuration. This configuration does the following things.

   • Specifies that the debugger used should be debugpy.

   • Configures the debugger to “attach” to a running process instead of launching a new one.

   • Specifies the port on which the debugpy server is running so that VS Code can connect to it.

   • Maps source code in the local repo clone to paths inside the Docker container so you can set breakpoints in the editor.

   {
     // existing configuration
     "launch": {
       "version": "0.2.0",
       "configurations": [
         {
           "name": "API",
           "type": "debugpy",
           "request": "attach",
           "connect": {
             "host": "localhost",
             "port": 50256
           },
           "pathMappings": [
             {
               "localRoot": "${workspaceFolder:api}",
               "remoteRoot": "/api"
             }
           ],
           "justMyCode": true
         }
       ]
     }
   }
   

2. Edit the compose.yml file inside the api/ directory to uncomment the command field and port mapping for port 5678.

3. Run the API server inside Docker using the instructions in the quickstart guide.

4. Connect the debugger to the running instance from the Run and Debug panel.

   

5. Read the Visual Code debugger’s official instructions to better understand how to use the debugger interface to accomplish tasks like setting breakpoints, watching variables etc.