Using tools in Python
A geoprocessing tool has a fixed set of parameters that provide the tool with the information it needs for execution. Tools usually have input parameters that define the dataset or datasets that are typically used to generate new output data. Parameters have several important properties:
- Each parameter expects a specific data type or data types, such as feature class, integer, string, or raster.
- A parameter expects either an input or output value.
- A parameter either requires a value or is optional.
- Each tool parameter has a unique name.
When a tool is used in Python, its parameter values must be correctly set so it can execute when the script is run. Once a valid set of parameter values is provided, the tool is ready to be executed. Parameters are specified as either strings or objects.
Strings are simply text that uniquely identifies a parameter value, such as a path to a dataset or a keyword. In the following code example, input and output parameters are defined for the Buffer tool. Note that the tool name is appended with its toolbox alias. In the example, two string variables are used to define the input and output parameters to make the call to the tool easier to read.
import arcpy roads = "c:/base/data.gdb/roads" output = "c:/base/data.gdb/roads_Buffer" # Run Buffer using the variables set above and pass the remaining # parameters in as strings arcpy.Buffer_analysis(roads, output, "distance", "FULL", "ROUND", "NONE")
For some parameters, such as a spatial reference, an object can also be specified. In the following code example, the Create Feature Class tool is executed using a SpatialReference object for its optional Coordinate System parameter.
import arcpy in_workspace = "c:/temp" output_name = "rivers.shp" # Create a spatial reference object spatial_ref = arcpy.SpatialReference('North America Equidistant Conic') # Run CreateFeatureclass using the spatial reference object arcpy.CreateFeatureclass_management( in_workspace, output_name, spatial_reference=spatial_ref)
Most geoprocessing tools include both required and optional arguments. Oftentimes there are cases where there are many optional arguments that don't need to be specified. There are a couple of strategies for dealing with these unused arguments. One is to keep all optional arguments in order, and reference those you don't need as either an empty string "", a pound sign "#" or with a None type. A second strategy is to use keyword arguments and use the argument name to assign a value. Using keyword arguments allows you to skip unused optional arguments or specify them in different orders.
Skipping optional arguments using empty strings.
import arcpy arcpy.AddField_management("schools", "school_id", "LONG", "", "", "", "", "NON_NULLABLE")
A better alternative; skipping optional arguments using keyword arguments.
import arcpy arcpy.AddField_management("schools", "school_id", "LONG", field_is_nullable="NON_NULLABLE")
ArcPy returns the output values of a tool when it is executed as a Result object. The advantage of a result object is that you can maintain information about the execution of tools, including messages, parameters, and output. These results can be maintained even after several other tools have been run.
The following examples show how to get the output from a result object following the execution of a geoprocessing tool.
import arcpy arcpy.env.workspace = "c:/city/data.gdb" # Geoprocessing tools return a result object of the derived # output dataset. result = arcpy.CopyFeatures_management("roads", "urban_roads") # A print statement will display the string # representation of the output. print result # A result object can be indexed to get the output value. # Note: a result object also has a getOutput() method that # can be used for the same purpose. result_value = result
When indexing the result object or using its getOutput() method, the return value is a Unicode string. This is an important consideration when running a tool with a derived output parameter such as Get Count, which provides a count of records in a table, or Calculate Default Cluster Tolerance, which provides a cluster tolerance value. To convert the unicode string to the expected type, built-in Python functions such as int() or float() can be used.
A derived parameter requires no interaction from the user and does not show up on the tool dialog box or as an argument to the tool in Python. Derived types are always output parameters.
import arcpy import types arcpy.env.workspace = "c:/base/data.gdb" # Many geoprocessing tools return a result object of the derived # output dataset. result = arcpy.GetCount_management("roads") result_value = result # The result object's getOutput method returns values as a # unicode string. To convert to a different Python type, use # built-in Python functions: str(), int(), long(), float() count = int(result_value) print count print types.TypeType(count)
If creating output that is just an intermediate stage in a larger workflow, the output argument can be omitted to allow the tool to create a unique path and name for the output. This can be accomplished by setting the output either to "#" or None, or if the output would be the last argument used, skip it entirely. In each case, the returned value is the full path to the new datasource.
import arcpy arcpy.env.workspace = "c:/city/data.gdb" result = arcpy.CopyFeatures_management("roads", "#") result = arcpy.CopyFeatures_management("roads", "") result = arcpy.CopyFeatures_management("roads")
Tool organization in ArcPy
Geoprocessing tools are organized in two different ways. All tools are available as functions on ArcPy but are also available in modules matching the toolbox alias name. Although most of the examples in the help show tools organized as functions available from ArcPy, both approaches are equally valid. Which approach you use will come down to a matter of personal preference and coding habits. In the following example, the Get Count tool is shown using both approaches.
import arcpy in_features = "c:/temp/rivers.shp" # Tools can be accessed as functions on the arcpy module arcpy.GetCount_management(in_features) # Or from modules matching the toolbox name arcpy.management.GetCount(in_features)
When using tools in modules, sometimes you may want to draw attention to how a module is identified to make your script more readable. In this case, you can use the form from - import - as.
# Clean up street centerlines that were digitized without # having set proper snapping environments import arcpy from arcpy import edit as EDIT from arcpy import management as DM streets = "c:/data/streets.gdb/majorrds" streets_copy = "c:/output/Output.gdb/streetsBackup" DM.CopyFeatures(streets, streets_copy) EDIT.TrimLine(streets, "10 Feet", "KEEP_SHORT") EDIT.ExtendLine(streets, "15 Feet", "EXTENSION")
ArcGIS Spatial Analyst extension tools are handled differently to accommodate Map Algebra and are available only in the arcpy.sa module and not as functions on ArcPy.