Every tool page in the ArcGIS Pro tool reference adheres to the same structure; understand the structure and you'll be able to use any tool effortlessly.
Elements of a tool reference page
Whether you search for a tool page or browse to it by expanding its toolbox, followed by its toolset, and clicking to load its page, here's what you'll find.
Summary and Illustration
The summary is a short description of what the tool does. It may contain links to more in-depth discussions of how the tool works. In some cases, the summary will be followed by an illustration that explains what the tool does.
The Usage section contains vital notes and clarifications about using the tool. When the notes refer to a particular parameter, the parameter label, which appears on the tool dialog box, is used rather than the parameter name, which appears in the syntax and is used in Python. The relationship between the parameter's label and name is usually obvious, but in some cases, the name is noted to avoid confusion.
Syntax (includes list of parameters)
The Syntax section provides the format and set of parameters that are required to execute the tool in Python. It is followed by a table listing all the parameters with their names, explanations, and the data (value) types. See Tool syntax decoded below for a detailed explanation of this section of a tool reference page.
The Code Sample section includes one or more examples illustrating how the tool can be executed and used in Python.
The Environments section is a list of the environment settings that the tool honors. Clicking on any link in the list will take you to its reference page. If a particular environment setting is of importance to the tool, there may be further information about that setting.
The Licensing Information section details whether the tool runs at specific licensing levels and notes if it requires an extension. For example, ArcGIS for Desktop Basic: Yes means that this tool will run with an ArcGIS Desktop Basic license while ArcGIS for Desktop Basic: Requires 3D Analyst means that it will run only if the 3D Analyst extension is used in conjunction with the ArcGIS Desktop Basic license.
Tool syntax decoded
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.
Tool name and alias
The first line below the syntax header contains the tool signature. 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.
- 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.
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.
Tool parameters can be either required or optional. Optional parameters are followed by (Optional) on the tool's dialog box.
You must provide a value for required parameters. These parameters are always the first parameters in the command.
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. The default value should be described in the Explanation column.
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 names versus labels
A parameter label is what you see in the tool's dialog box. A parameter name is what you see in the parameter table. The correspondence between the parameter label and name is usually obvious, but in some cases, the parameter name will be noted to avoid confusion.
Parameters that accept lists
For parameters that accept a list of values, the syntax of the list can be found following the parameter name, as illustrated below.
Simple list; Simple lists are known as multivalue parameters.
List of lists: The data type is Value Table. Only built-in tools and tools in a Python toolbox can have parameters with a data type of Value Table.
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"
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"
The cells in this column provide further information about what a parameter is used for and how it can be set, including keyword options.
Keywords are strings; they are always surrounded by quotation marks when calling the tool. For example, the Add Field tool has keywords for the following 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")
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 Create Feature Class 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 easier. Geometry objects can be created from scratch using Geometry, Multipoint, PointGeometry, Polygon, or Polyline classes.