GEOG 485:
GIS Programming and Automation

2.2.3 Printing messages from the Esri geoprocessing framework

PrintPrint

When you work with geoprocessing tools in Python, sometimes a script will fail because something went wrong with the tool. It could be that you wrote flawless Python syntax, but your script doesn't work as expected because Esri geoprocessing tools cannot find a dataset or otherwise digest a tool parameter. You won't be able to catch these errors with the debugger, but you can get a view into them by printing the messages returned from the Esri geoprocessing framework.

Esri has configured its geoprocessing tools to frequently report what they're doing. When you run a geoprocessing tool from ArcMap or ArcCatalog, you see a box with these messages, sometimes accompanied by a progress bar. You learned in Lesson 1 that you can use arcpy.GetMessages() to access these messages from your script. If you only want to view the messages when something goes wrong, you can include them in an except block of code, like this.

try:
    . . .
except:
    print arcpy.GetMessages()

Remember that when using try/except, in the normal case Python will execute everything in the try-block (= everything following the "try:" that is indented relative to it) and then continue after the except-block (= everything following the "except:" that is indented relative to it). However, if some command in the try-block fails, the program execution directly jumps to the beginning of the except-block and, in this case, prints out the messages we get from arcpy.GetMessages(). After the except-block has been executed, Python will continue with the next statement after the except-block.

Geoprocessing messages have three levels of severity: Message, Warning, and Error. You can pass an index to the arcpy.GetMessages() method to filter through only the messages that reach a certain level of severity. For example, arcpy.GetMessages(2) would return only the messages with a severity of "Error". Error and warning messages sometimes include a unique code that you can use to look up more information about the message. The ArcGIS Desktop Help contains topics that list the message codes and provide details on each. Some of the entries have tips for fixing the problem.

Try/except can be used in many ways and at different indentation levels in a script. For instance, you can have a single try/except construct as in the example above where the try-block contains the entire functionality of your program. If something goes wrong, the script will output some error message and then terminate. In other situations, you may want to split the main code into different parts, each contained by its own try/except construct to deal with a the particular problems that may occur in this part of the code. For instance, the following structure may be used in a batch script that performs two different geoprocessing operations on a set of shapefiles when an attempt should be made to perform the second operation, even if the first one fails.

for featureClass in fcList: 
    try:
       . . .   # perform geoprocessing operation 1
    except:
       . . .   # deal with failure of geoprocessing operation 1

    try:
       . . .   # perform geoprocessing operation 2
    except:
       . . .   # deal with failure of geoprocessing operation 2

Let us assume, the first geoprocessing operation fails for the first shapefile in fcList. As a result, the program execution will jump to the first except-block which contains the code for dealing with this error situation. In the simplest case, it will just produce some output messages. After the except-block has been executed, the program execution will continue as normal by moving on to the second try/except statement and attempt to perform the second geoprocessing operation. Either this one succeeds or it fails too, in which case the second except-block will be executed. The last thing to note is that since both try/except statements are contained in the body of the for-loop going through the different shapefiles, even if both of the operations fail for one of the files, the script will always jump back to the beginning of the loop body and continue with the next shapefile in the list which is often the desired behavior of a batch script.

Further reading

Please take a look at the official ArcGIS documentation for more detail about geoprocessing messages. Be sure to read these topics:

  • Understanding message types and severity
  • Understanding geoprocessing tool errors and warnings - This is the gateway into the error and warning reference section of the help that explains all the error codes. Sometimes you'll see these codes in the messages you get back, and the specific help topic for the code can help you understand what went wrong. The article also talks about how you can trap for certain conditions in your own scripts and cause specific error codes to appear. This type of thing is optional, for over and above credit, in this course.