Working with Python can feel like an exercise in frustration. First, there are the complications with whitespace. Then, there are challenges with working with ArcPy. And finally, how is it even possible to debug Python scripts within ArcGIS? All these and more might come to mind when thinking about using Python. It’s enough to make one start to feel like Black Knight from Monty Python and the Holy Grail. Losing limbs in the fight against Python.

However, there is hope. While it takes time to get used to the whitespace and learn the in’s and out’s of ArcPy, there can be some immediate relief in the form of debugging. Let’s dive in and take a look at some easy tips and then move into using a debugging programs with ArcGIS.

The basics

The simplest way to add debugging to Python scripts is through print statements. This is simple with stand alone scripts. Let’s take the following simple example.

The script is using print statements to check the current value of a runtime variable, n. Print statements are also used to display when the script reaches the end. Using print statements in this manner can help to determine where a piece of code is failing. However, what about running the same script from ArcMap? There’s no console to print values to. The ArcPy libraries provide a solution to this problem with the AddMessage, AddWarning, and AddError functions. These functions print statements to the progress dialog box. These functions also print the messages as informational, warnings, or errors for AddMessage, AddWarning, and AddError respectively.

In order to use these functions the script needs to be converted to run as a geoprocessing tool. The changes are straight forward in this case. The print statements need to be converted to calls to the arcpy functions and arcpy needs to be imported.

Now the Python script can be imported as a geoprocessing tool. When ran this tool will show the “print” statements in the process dialog box.

Interactive Debuggers with ArcMap

Using print statements is an easy way to debug simple scripts. Unfortunately, for some more complicated scripts this approach may not be practical. There are a number of powerful debuggers available for stand alone Python code. These debuggers allow for code to be interactively debugged. Fortunately there is a way to attach these debuggers to ArcMap to allow interactive debugging of scripts.

In order for Python scripts to work with a debugger the arguments must be passed in using the GetParameterAsText arcpy function rather than using sys.argv. More information about how to access script parameters can be found here: http://desktop.arcgis.com/en/arcmap/latest/analyze/creating-tools/accessing-parameters-in-a-script-tool.htm

One other setting to assign before debugging is found in ArcMap or ArcCatalog. From either ArcMap or ArcCatalog select Geoprocessing Options.

Set the Debugger options to the path of the debugger that you would like to use. In this case PyCharm is selected. Other debuggers that are available include IDLE, PythonWin, PyScriptor, and Wing IDE.

When selecting the Python script to run right click and select Debug. This will open the script in debug mode. Running the script in this mode will launch the debugger set in the options and open the script in the debugger. Once open the script is able to be debugged with breakpoints and other tools available in the debugger.

What about ArcGIS Pro

The process to debug python code in ArcGIS Pro is similar to ArcMap in that the goal is to attach a debugger to the process. However, with Pro the debugger will not be launched from ArcGIS Pro. The recommended approach with ArcGIS Pro is to open the python files in an IDE and then attach to an instance of ArcGIS Pro. How to attach an IDE to a process will not be covered by this article since that process will be different for each different IDE. For example, with Visual Studio the IDE needs to be attached to the ArcGIS Pro process and with PyCharm a Python Debug Server needs to be used.

There are steps that need to be taken to allow communication between ArcGIS Pro and the debugger. For a script tool validator the code to execute should be saved to a Python file that the IDE can open. This file needs to be saved in the same location as the .tbx file. The .tbx file could then contain the following to allow ArcGIS Pro to use the Python file containing all the logic. In this example of logic is stored in val.py.

The method to debug a Python Toolbox is similar to a tool validator. The logic should be stored in separate Python file saved in the same location as the .pyt file. Then the Python Toolbox only needs to contain the following. The logic in this example is stored in a file called pyt_code.py.

from pyt_code import *

Wrapping it Up

Debugging Python meant to be used within ArcGIS software doesn’t need to be complicated. For a lot of scripts it’s enough to add the print statements. For others attaching a debugger will be required. Either way, the end goal should be to alleviate frustration. Python and ArcPy don’t need to be daunting tasks. Learning to troubleshoot effectively is just one step in the journey toward the holy grail of coding with ArcGIS.

Resources

Python and ArcMap: http://desktop.arcgis.com/en/arcmap/latest/analyze/creating-tools/debugging-script-tools.htm

Python and Pro: http://pro.arcgis.com/en/pro-app/arcpy/get-started/debugging-python-code.htm