In this section of the guide, we will observe advanced concepts such as configuring environment settings, using logging and exception handling while executing geoprocessing tools.
Geoprocessing environment
Geoprocessing environment settings are additional settings that affect geoprocessing tools. These settings provide a powerful way to ensure geoprocessing is performed in a controlled environment where you decide things such as the processing extent that limits processing to a specific geographic area, a coordinate system for all output geodatasets, or whether Z or M values should be included with the geoprocessing results.
Only certain environment settings will be used by a given geoprocessing tool. To determine the environments that a tool will use, consult the tool's documentation.
The arcgis.env module has globals to store such environment settings that are common among all geoprocessing tools. The code snippet below sets the spatial reference of the output geometries to 4326 (WGS84) :
arcgis.env.out_spatial_reference = 4326Logging and error handling
Geoprocessing tools log informative, warning and error messages using logging facility for Python. These messages include such information as the following:
- When the operation started and ended
- The parameter values used
- General information about the operation's progress (information message)
- Warnings of potential problems (warning message)
- Errors that cause the tool to stop execution (error message)
All communication between tools and users is done with these log messages. Messages are categorized by severity and are logged at these different levels:
| Log Level | Description |
|---|---|
logging.INFO | An informative message is information about a tool execution. It is never used to indicate problems. Only general information, such as a tool's progress, what time a tool started or completed, output data characteristics, or tool results, is found in informative messages. |
logging.WARN | Warning messages are generated when a tool experiences a situation that may cause a problem during its execution or when the result may not be what you expect. For example, defining a coordinate system for a dataset that already has a coordinate system defined generates a warning. You can take action when a warning returns, such as canceling the tool's execution or making another parameter choice. |
logging.ERROR | Error messages indicate a critical event that prevented a tool from executing. Errors are generated when one or more parameters have invalid values, or when a critical execution process or routine has failed. |
The code snippet below sets the log level to logging.INFO, which will cause all messages of severity INFO or higher to be logged and displayed:
import logging
import sys
# Create logger
logger = logging.getLogger()
logger.setLevel(logging.INFO)
# Create STDERR handler
handler = logging.StreamHandler(sys.stderr)
# Set STDERR handler as the only handler
logger.handlers = [handler]Verbose logging to standard output
To ease development, messages from geoprocessing tools are printed to stdout in addition to stderr. This behavior is controlled by the arcgis.env.verbose global and can be turned off by setting it to False. In any case, all geoprocessing messages are available through Python logging module.
arcgis.env.verbose = False Error handling
Geoprocessing tools may encounter error and fail for various reasons. The function for the tool throws a Python Exception to report such errors and failures. To handle the possibility of a tool failing to execute, wrap it's invocation in a try/except block.
The code snippet below wraps the execution of the tool within a try/except block and reports an error in case the tool fails:
geosurtools = import_toolbox('http://tps.geosur.info/arcgis/rest/services/Models/GeoSUR_ElevationDerivatives/GPServer')try:
geosurtools.slope_classificaiton()
except Exception as e:
print('The tool encountered an error')Submitted. Executing... Executing (Slope Classificaiton): SlopeClss2 "Feature Set" "GMTED 30 arc-second (Median)" Degree 3.0E-5 5,10,20,30,40,50 Start Time: Sat Nov 26 03:26:53 2016 Executing (Slope Classificaiton): SlopeClss2 "Feature Set" "GeoSUR_ElevationDerivatives\GMTED 30 arc-second (Median)" Degree 3.0E-5 5,10,20,30,40,50 Start Time: Sat Nov 26 03:26:53 2016 Executing (TPS Slope Classificaiton): TPSSlopeClass2 "Feature Set" "GeoSUR_ElevationDerivatives\GMTED 30 arc-second (Median)" Degree 3.0E-5 5,10,20,30,40,50 Start Time: Sat Nov 26 03:26:54 2016 Running script TPSSlopeClass2... D:\geosur_ags\open\gp\sharedtools\scripts D:\geosur_ags\open\gp\sharedtools\scripts\tps_slopeclss.xml maxPixels: 120000000 Spatial Reference Type: Geographic Raster Input: GeoSUR_ElevationDerivatives\GMTED 30 arc-second (Median) Cell Size x:0.008333 y:0.008333 Pixel Width: -1 Pixel Height: -1 Pixels to be processed: 1 (1.00 - 120000000.00) / 120000000 Failed to process input extent. Verify that client has a defined coordinate system. Failed to process input extent. Verify that client has a defined coordinate system. Completed script TPSSlopeClass2... Failed to execute (TPS Slope Classificaiton). Failed to execute (TPS Slope Classificaiton). Failed at Sat Nov 26 03:26:54 2016 (Elapsed Time: 0.23 seconds) Failed to execute (Slope Classificaiton). Failed to execute (Slope Classificaiton). Failed at Sat Nov 26 03:26:54 2016 (Elapsed Time: 0.33 seconds) Failed to execute (Slope Classificaiton). Failed to execute (Slope Classificaiton). Failed at Sat Nov 26 03:26:54 2016 (Elapsed Time: 0.36 seconds) Failed.
The tool encountered an error
Failed.
Creating Geoprocessing tools
Refer to this documentation for a quick tour of creating Geoprocessing tools using Python.