Anatomy of a tool reference page

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 information about how the tool works. In some cases, the summary will be followed by an illustration that also explains what the tool does.

Usage

The Usage section contains 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 types. See Tool syntax decoded below for a detailed explanation of this section of a tool reference page.

Code sample

The Code Sample section includes one or more examples illustrating how the tool can be executed and used in Python.

Environments

The Environments section is a list of the environment settings that the tool honors. Click any link in the list to go to its reference page. If a particular environment setting is of importance to the tool, there may be further information about that setting.

Licensing information

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 the 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 appears 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.

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).

Note:

The parameter help in geoprocessing tool topics often describes a parameter from the context of Python. This is most notable for Boolean parameters and string parameters with keywords. Parameter help that relates to usage of the tool from the tool dialog box can be viewed by hovering over the information button Information next to each parameter.

A tool dialog box can show parameters in a different order than the actual parameter order, so in rare cases, the order of the parameters on the tool's dialog box may be different than the order in the parameter table. For Python, always use the order 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.

Parameter TypeDescription

Required

You must provide a value for required parameters. These parameters are always the first parameters in the command.

Optional

These parameters always follow the required parameters. If you don't provide a value for an optional parameter, the default value is calculated and used. The default value is described in the Explanation column.

Required and optional parameters

Optional parameter names can be helpful as a shortcut in Python. Instead of 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

The parameter label is used on the tool's dialog box. The parameter name is used in the parameter table. The relationship 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 follows the parameter name as follows:

AppearanceDescription

Simple list

Simple list; Simple lists are known as multivalue parameters.

Value table

List of lists: The data type is Value Table.

A simple list contains a list of single values. In the example above, the Distances parameter has a data type (shown in the Data Type column) of double. You can denote 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 example above, the in_features parameter is a list of lists in which an individual list contains the path to a feature dataset or layer and an optional integer rank. You can denote 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"

Explanation column

This column provides 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 a field named 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 in ArcGIS, such as coordinate system and extent.

Derived output

Derived parameters are output parameters that are not entered as values on a tool's dialog box or as arguments in Python. Tools will have derived outputs in the following cases:

  • The tool calculates a value that is returned by the tool, such as the Get Count tool, which provides a count of records in a table.
  • The tool modifies input datasets, such as the Calculate Field tool, which modifies field values.
  • Output datasets whose name or location is determined from input parameters or other known locations, such as the Feature Class to Feature Class, which determines the output path from workspace and feature class name parameters.

Use 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 difficult 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 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 want to go through the process of creating a (temporary) feature class, populating the feature class with cursors, using the feature class, and 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 Multipoint, PointGeometry, Polygon, or Polyline classes.