Debug Python code

Python is used in many parts of the ArcGIS Pro application. Integrated development environments (IDEs) are applications that provide editing and debugging functionality for code writers. IDEs make the writing and troubleshooting of code easier and more efficient. Python IDEs can be used to author and troubleshoot script tool and Python toolbox validation and execution code.

IDEs

Microsoft Visual Studio IDE

Debugging method	Attach to running processes
Supported ArcGIS Pro components	Script tool execution Script tool validation Python toolboxes
Additional resources	https://docs.microsoft.com/en-us/visualstudio/python/debugging

The following Visual Studio workload must be installed: Python development. See https://docs.microsoft.com/en-us/visualstudio/install/modify-visual-studio.

To debug Python code in ArcGIS Pro, use the following steps to get started:

1. Start Microsoft Visual Studio.
2. On the main menu, click Debug > Attach to Process.
3. On the Attach to Process dialog box, click the Select button.
4. On the Select Code Type dialog box, check Debug these code types, check Python, and click OK.

   Note:

   You must choose Attach to: Python code. Do not use the default code type of Automatic: Managed (v4.6, v4.5, v4.0) code, Python code.

5. In the list of available processes, click the ArcGISPro.exe process and click the Attach button.

After detaching the IDE from ArcGIS Pro, exceptions in Python code will not display correctly. To address this, either reattach the IDE or restart ArcGIS Pro.

Note:

Microsoft Visual Studio 2017 can be used to debug ArcGIS Pro 2.1 and later. Earlier versions of either of these applications will not work.

PyCharm Professional edition

Debugging method	Python Debug Server
Supported ArcGIS Pro components	Script tool execution Script tool validation
Additional resources	https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html

pdb module

The pdb module is part of the Python standard library. It is not a fully developed IDE, but it can be used for interactive source code debugging.

Debugging method	Interactive (at hard-coded breakpoint)
Supported ArcGIS Pro components	Script tool execution (from a stand-alone Python script only)
Additional resources	https://docs.python.org/3/library/pdb.html

Using the pdb module is useful for debugging a script tool execution code running in a stand-alone Python script. Add a breakpoint (using import pdb;pdb.set_trace()) into your script tool's code, and run a Python script that calls that script tool. Upon encountering the breakpoint, Python will enter interactive mode. Remember to remove the breakpoint code upon completion of the debugging effort.

Debug script tool validation code

IDEs can only debug Python files (.py). For Python code in script tool validation (embedded in a toolbox), copy the code to an external Python file and replace the code in the Python toolbox with the example below. You can then open the Python file in your IDE and set breakpoints, attach the IDE to ArcGIS Pro, and run your script tool. Upon completion of code modification, copy the contents of the Python file back into the tool validation.

In the following example, val.py contains the ToolValidator class and is saved to the same directory as a .tbx file.

import sys
import val

# the following code will reload the val.py module if it's modified
if 'val' in sys.modules:
    import importlib
    importlib.reload(val)

# ToolValidator should exist at the global scope
ToolValidator = val.ToolValidator

The validation code in script tool validation is executed repeatedly as a user interacts with a tool.

Debug Python toolboxes

IDEs can only debug Python files (.py). For code in a Python toolbox file (.pyt), copy the code to an external Python file, and replace the code in the Python toolbox with the example below. You can then open the Python file in your IDE and set breakpoints, attach the IDE to ArcGIS Pro, and use your Python toolbox. Upon completion of code modification, copy the contents of the Python file back into the Python toolbox.

In the following example, pyt_code.py contains the code usually found in the Python toolbox and is saved to the same directory as a .pyt file.

from pyt_code import *

The code in the Python toolbox will be executed multiple times as the tools are loaded and you interact with them.