Desktop Help 10.0 - Understanding tool syntax

The syntax section of a tool reference page provides details for each tool parameter. It also provides the syntax for using the tool in Python.

Tip:

An easy way to create Python code that executes a particular tool is to use the Results window, as follows:

Use the tool dialog box to execute the tool.
After the tool executes, open the Results window.
Right-click the result and click Copy As Python Snippet.
In your Python code, paste the copied snippet.

Dive-in:

The syntax section is also for the use of IGeoProcessor.Execute() in .NET. (For more information on calling a geoprocessing tool in .NET, see the online SDK document How to run a geoprocessing tool.)

Tool signature

The first line below the syntax header contains the tool signature.

Tool name and alias

In Python, the tool name is used instead of the tool label.

The tool label is displayed at the top of a tool dialog box or in the Catalog window.
In Python, the toolbox alias follows the tool name separated by an underscore. For example, in Python, the Symmetrical Difference tool is identified as SymDiff_analysis.

Optional parameters

Tool parameters can be either required or optional. Optional parameters are surrounded by braces ( {} ); required parameters are not.

Parameter Type	Symbol	Meaning
Required		Required parameter. These parameters are always the first parameters in the command. You must provide a value for required parameters.
Optional	{ }	Optional parameter. These parameters always follow the required parameters. If you don't enter a value for an optional parameter, the default value is calculated and used. A parameter's default value can be found in the tool's help.

Parameter types

Optional parameter names can be helpful as a shortcut in Python. Instead of specifically skipping other unused optional parameters with an empty set of quotation marks ("") or a pound sign ("#"), the parameter can be explicitly set using the parameter name.

# Use the parameter name to bypass unused optional arguments
arcpy.AddField_management("c:/data/streets.shp", "Address", "TEXT", field_length=120)

Parameter table

Following the tool signature is the parameter table with three columns: Parameter, Explanation, and Data Type. The rows in the parameter table are always in parameter order (the same as the tool signature).

A tool dialog box has the capability to show parameters in a different order than the actual parameter order, so in rare cases, the order of the parameters in the tool's dialog box may be different than the order in the parameter table. For Python, always use the order as shown in the parameter table.

Parameter column

The cells in this column have the parameter name; whether the parameter is optional; and, for parameters that accept a list, the list syntax, as illustrated below.

Appearance	Description
	Simple list. Simple lists are known as multivalue parameters.
	List of lists. The data type is Value Table. Only built-in tools can have parameters with a data type of Value Table.

Simple list

A simple list contains a list of single values. In the above example, the Distances parameter has a data type (shown in the Data Type column) of double. You can express this list using one of the following methods:

# Method 1: A list of numbers
dist = [10.0, 20.0, 30.0]

# Method 2: A list of strings
dist = ["10.0", "20.0", "30.0"]

# Method 3: String representation of a list
dist = "10.0; 20.0; 30.0"

List of lists

The data type of a list of lists is Value Table. In the above example, the in_features parameter is a list of lists where an individual list contains the path to a feature dataset or layer and an optional integer rank. You can express this parameter using one of the following methods:

# Method 1: A list of lists
inFeatures = [["counties", 2],["parcels", 1],["state"]]

# Method 2: A list of strings
inFeatures = ["counties 2", "parcels 1", "state"]

# Method 3: String representation, each list separated by a semicolon
inFeatures = "counties 2; parcels 1; state"

Tip:

When in doubt about the string syntax of a multivalue or value table, you can do the following:

Use the tool dialog box to execute the tool.
After the tool executes, open the Results window.
Right-click the result and click Copy As Python Snippet.
In your Python code, paste the copied snippet.

Explanation column

The cells in this column provide further information about what a parameter is used for and how it can be set, including keyword options. In most cases, this explanation is the same as you see in the side-panel help for the tool. In some cases, the explanation of the parameter may be slightly different than what you see in the side-panel help. For example, the tool dialog box will have a check box for a Boolean (true/false) parameter, but the description in the syntax will have two keyword strings, one for the true state and one for the false state.

Keywords are strings; they are always surrounded by quotes when calling the tool. For example, the AddField tool has keywords for field type:

 # Add field idField with data type of long
arcpy.AddField_management("Parks", "idField", "LONG", field_is_nullable="NULLABLE", field_is_required="NON_REQUIRED")

Data Type

Every tool parameter has an associated data type. Some simple data types are string (any set of alphanumeric characters), Boolean (a true or false value), and long (an integer value between -2,147,483,648 and 2,147,483,647). In addition to these simple data types, there are dozens of other data types built specifically for data found in ArcGIS, such as coordinate system and extent.

Using scripting objects

Tool parameters are usually defined using simple text strings. Dataset names, paths, keywords, field names, tolerances, and domain names can be specified using a quoted string.

Some parameters are harder to define using simple strings; they are more complex parameters that require many properties. Instead of using long, complicated text strings to define these parameters, you can use classes (for example, SpatialReference, ValueTable, and Point classes). The documentation for each tool contains a scripting example of how each tool parameter is defined and used.

In the following example, a SpatialReference object is created and used to define the output coordinate system of a new feature class created using the CreateFeatureClass tool.

import arcpy

inputWorkspace = "c:/temp"
outputName =  "rivers.shp"

prjFile = "c:/projections/North America Equidistant Conic.prj"
spatialRef = arcpy.SpatialReference(prjFile)

# Run CreateFeatureclass using the spatial reference object
#
arcpy.CreateFeatureclass_management(inputWorkspace, outputName, "POLYLINE", 
                                    "", "", "", spatialRef)

In many geoprocessing workflows, you may need to run a specific operation using coordinate and geometry information but don't necessarily want to go through the process of creating a new (temporary) feature class, populating the feature class with cursors, using the feature class, then deleting the temporary feature class. Geometry objects can be used instead for both input and output to make geoprocessing simpler. Geometry objects can be created from scratch using Geometry, Multipoint, PointGeometry, Polygon, or Polyline classes.

Understanding tool syntax