Debug Python code

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

Microsoft Visual Studio

The following ArcGIS Pro components can be debugged in Visual Studio:

• Script tool source code
• Script tool validation
• Python toolboxes

• 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 start debugging Python code in ArcGIS Pro, complete the following steps:

1. In ArcGIS Pro, open the Geoprocessing pane of the tool to be debugged.

   The Python window and any notebooks must be closed.

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

   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.

6. In the list of available processes, click the ArcGISPro.exe process and click the Attach button.
7. Run your tool in ArcGIS Pro to start debugging.

After detaching the IDE from ArcGIS Pro, exceptions in Python code will not display correctly. To address this, 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

The following ArcGIS Pro components can be debugged in PyCharm Professional edition:

• Script tool source code
• Script tool validation

• 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. The pdb module cannot be used to debug within ArcGIS Pro, but it can be used to debug stand-alone scripts, including the source code for script tools.

• https://docs.python.org/3/library/pdb.html

Using the pdb module is useful for debugging a script tool's source 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

Python code in the script tool validation is embedded in the tool and needs to be copied to an external Python file (.py) to debug it. 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 the toolbox.

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 run repeatedly as a user interacts with a tool.

Debug Python toolboxes

You cannot debug a Python toolbox (.pyt) directly, instead it must be debugged using a Python file (.py). Follow these steps to debug a Python toolbox:

1. Create an external Python file within the same directory as the Python toolbox.
2. Copy the code within the execute function of the Python toolbox and paste it into a function func() in the new Python file. Copy over any other necessary functions.
3. Replace the code in the Python toolbox execute function with the following:

import execute_code
execute_code.func(parameters)

4. Open the Python file in Visual Studio and set breakpoints using the steps above to debug the Python toolbox.

The following code is an example of the execute function in the Python toolbox and the separate Python file being called.

In the following example, runCode.py is saved to the same directory as a .pyt file.

import arcpy

def func(parameters):
    arcpy.AddMessage("This is where your code goes.")
    return

The following is an example of the modified execute function in a Python toolbox.

def execute(self, parameters, messages):
    """The source code of the tool."""
    import runCode

    runCode.func(parameters)
    return

Upon completion of code modification, copy the contents of the Python file back into the tool's execute function.