Validation is everything that happens before clicking the tool's OK button. When creating your own custom tools, validation allows you to customize how parameters respond and interact with values and each other. Validation is performed with a block of Python code that is used to control tool behavior.
To learn more about validation, see Understanding validation in script tools.
You can provide custom behavior for your script tool dialog box, such as enabling and disabling parameters, providing default values, and updating string keywords. To add custom behavior for your script tool, right-click the script tool, click Properties, and click the Validation tab. In the Validation panel, you can provide Python code that implements a Python class named ToolValidator.
ToolValidator is a Python class that contains four methods: initializeParameters, isLicensed, updateParameters, and updateMessages. It also contains the standard Python class initialization method, __init__. To view and edit the ToolValidator class, right-click your script tool, click Properties, and click Validation. The code sample below shows the default ToolValidator class code. The Python code can be edited in place, or alternatively, click the Open in Script Editor button to edit the code.
import arcpy
class ToolValidator(object):
"""Class for validating a tool's parameter values and controlling
the behavior of the tool's dialog."""
def __init__(self):
"""Setup arcpy and the list of tool parameters."""
self.params = arcpy.GetParameterInfo()
def initializeParameters(self):
"""Refine the properties of a tool's parameters. This method is
called when the tool is opened."""
def isLicensed(self):
"""Set whether tool is licensed to execute."""
return True
def updateParameters(self):
"""Modify the values and properties of parameters before internal
validation is performed. This method is called whenever a parameter
has been changed."""
def updateMessages(self):
"""Modify the messages created by internal validation for each tool
parameter. This method is called after internal validation."""| Method | Description |
|---|---|
__init__ | Initializes the ToolValidator class. Import any libraries you need and initialize the object (self). |
initializeParameters | Refines the properties of a tool's parameters. Called once when the tool dialog box first opens or when the tool is executed from Python. |
Sets whether a tool is licensed to execute. Called once when the tool dialog box first opens or when the tool is executed from Python. | |
updateParameters | Called each time the user changes a parameter on the tool dialog box. After returning from updateParameters, geoprocessing calls its internal validation routine. |
updateMessages | Called after returning from the internal validation routine. You can examine the messages created from internal validation and change them if desired. |
Note:
Avoid using time-consuming tasks such as geoprocessing tools or the opening of datasets in your validation code, as the ToolValidator class is executed each time a change is made in the tool dialog box. Use geoprocessing tools in your script—not in ToolValidator.
Following are some examples of ToolValidator code. For a description of all the methods and more examples, see Programming a ToolValidator class.
To enable or disable a parameter
This example is from the Hot Spot Analysis tool:
def updateParameters(self):
# If the option to use a weights file is selected (the user chose
# "Get Spatial Weights From File"), enable the parameter for specifying
# the file, otherwise disable it
if self.params[3].value == "Get Spatial Weights From File":
self.params[8].enabled = True
else:
self.params[8].enabled = FalseTo set a default value
This example is also from the Hot Spot Analysis tool:
def updateParameters(self):
# Set the default distance threshold to 1/100 of the larger of the width
# or height of the extent of the input features. Do not set if there is no
# input dataset yet, or the user has set a specific distance (Altered is true).
if self.params[0].valueAsText:
if not self.params[6].altered:
extent = arcpy.Describe(self.params[0]).extent
if extent.width > extent.height:
self.params[6].value = extent.width / 100
else:
self.params[6].value = extent.height / 100
returnTo update a filter
Following is an example of dynamically updating a Value List Filter containing a choice list of keywords. If the user enters OLD_FORMAT in the second parameter, the third parameter contains POINT, LINE, and POLYGON. If NEW_FORMAT is entered, the third parameter contains three additional choices.
import arcpy
class ToolValidator:
def __init__(self):
self.params = arcpy.GetParameterInfo()
def initializeParameters(self):
return
def updateParameters(self):
# Provide default values for "file format type" and
# "feature type in file"
#
if not self.params[1].altered:
self.params[1].value = "OLD_FORMAT"
if not self.params[2].altered:
self.params[2].value = "POINT"
# Update the value list filter of the "feature type in file" parameter
# depending on the type of file (old vs. new format) input
#
if self.params[1].value == "OLD_FORMAT":
self.params[2].filter.list = ["POINT", "LINE", "POLYGON"]
elif self.params[1].value == "NEW_FORMAT":
self.params[2].filter.list = ["POINT", "LINE", "POLYGON",
"POINT_WITH_ANNO",
"LINE_WITH_ANNO",
"POLYGON_WITH_ANNO"]
return
def updateMessages(self):
returnHere is another example in which the Value List Filter in the second parameter changes based on the shape type found in the first parameter, a feature class:
def updateParameters(self):
# Update the value list filter in the second parameter based on the
# shape type in the first parameter
stringFilter = self.params[1].filter
if self.params[0].valueAsText:
shapetype = arcpy.Describe(self.params[0]).shapeType.lower()
if shapetype == "point" or shapetype == "multipoint":
stringFilter.list = ["RED", "GREEN", "BLUE"]
elif shapetype == "polygon":
stringFilter.list = ["WHITE", "GRAY", "BLACK"]
else:
stringFilter.list = ["ORANGE", "INDIGO", "VIOLET"]
else:
stringFilter.list = ["RED", "GREEN", "BLUE"]
# If the user hasn't changed the keyword value, set it to the default value
# (first value in the value list filter).
if not self.params[1].altered:
self.params[1].value = stringFilter.list[0]
returnTo customize a message
def updateMessages(self):
self.params[6].clearMessage()
# Check to see if the threshold distance contains a value of zero and the user has
# specified a fixed distance band.
if self.params[6].value <= 0:
if self.params[3].value == "Fixed Distance Band":
self.params[6].setErrorMessage("Zero or a negative distance is invalid \
when using a fixed distance band. Please \
use a positive value greater than zero." )
elif self.params[6].value < 0:
self.params[6].setErrorMessage("A positive distance value is required \
when using a fixed distance band. \
Please specify a distance.")
returnUpdating the description of output data using the Schema object
In addition to customizing the behavior of the tool dialog box, you can use tool validation to update descriptions of output data variables for ModelBuilder. You can think of data variables in ModelBuilder as nothing more than brief descriptions of datasets. Data variables contain description of data on disk, including information such as the name, fields, extent, and other data characteristics that can be described using the Describe function.
All tools should update the description of their output data for use in ModelBuilder. By updating the description, subsequent processes in ModelBuilder can see pending changes to data before any process is run. The two examples below show how subsequent processes see pending changes.
For example, when the Add Field tool is used in ModelBuilder, its output data variable is updated to include the new field so that subsequent tools that depend on recognizing the field name (such as Calculate Field) can see the intended field name and use it for parameters that require it.
In the ToolValidator class, you can use a Schema object to set rules for building the description of the output; for example, you can set rules such as the following:
- Make a copy of the input dataset description and add a new field to its list of fields (such as Add Field), or add a list of fixed fields (such as Add XY Coordinates).
- Set the list of output fields to be all the fields in a collection of datasets and, optionally, add fields to contain the feature IDs from the collection of datasets (such as Union and Intersect).
- Set the extent to that of a dataset in another parameter, or the union or intersection (such as Clip) of datasets in a list of parameters.
- Set a specific geometry type (point, line, polygon), or set it to that of a dataset in another parameter or to the minimum or maximum type in a list of parameters. The definition of minimum and maximum geometry type is points = 0, polylines = 1, polygons = 2, so the minimum geometry type in the set {point, polyline, polygon} is point, and the maximum is polygon.
Output parameters have a schema
The Schema object is created for you by geoprocessing. Every output parameter of type feature class, table, raster, or workspace has a Schema object. Only feature class, table, raster, and workspace output data types have a schema—other data types do not. You access this schema through the Parameter object and set the rules for describing the output. On return from updateParameters, the internal validation routine examines the rules you set and updates the description of the output.
Setting dependencies
Whenever you create a rule, such as copy the fields of the dataset in parameter 3 and add a field, you must tell the Schema object from what parameter you want to copy (parameter 3). This is done by adding dependencies to the Parameter object. You can add more than one dependency.
def initializeParameters(self):
# Set the dependencies for the output and its schema properties
self.params[2].parameterDependencies = [0, 1]parameterDependencies takes a list.
The examples that follow show setting and using dependencies.
Setting dependencies examples: Clip and Add Field
Recall that the Clip tool makes a copy of the input features definition and sets the extent to the intersection of the input features and the clip features. An example of how this rule is implemented in ToolValidator is provided below. Because Clip is a built-in tool and not a script, it does not use a ToolValidator class. Built-in tools do their validation using internal routines that are essentially the same as ToolValidator. But if it did use a ToolValidator class, this is what it would look like:
def initializeParameters(self):
# Set the dependencies for the output and its schema properties
self.params[2].parameterDependencies = [0, 1]
# Feature type, geometry type, and fields all come from the first
# dependent (parameter 0), the input features
self.params[2].schema.featureTypeRule = "FirstDependency"
self.params[2].schema.geometryTypeRule = "FirstDependency"
self.params[2].schema.fieldsRule = "FirstDependency"
# The extent of the output is the intersection of the input features and
# the clip features (parameter 1)
self.params[2].schema.extentRule = "Intersection"
return
def updateParameters(self):
returnAdd Field copies the definition of an input parameter and adds the user-specified field. The link below shows how Add Field would be implemented in ToolValidator.
Setting schema in initializeParameters versus updateParameters
Note that the Clip example above modifies the Schema object in initializeParameters and that updateParameters does nothing but return. Add Field, on the other hand, has to modify the Schema object in updateParameters because it doesn't have the definition of the field to add until the user provides the information (and updateParameters is called).
You can think of these two cases as static versus dynamic. Clip doesn't rely on anything but the datasets found in the dependent parameters (static case), whereas Add Field needs to examine other parameters (such as field name and field type) that are not dependent parameters (dynamic case).
This static and dynamic behavior is evident in the way a ToolValidator class is called, as follows:
- When the tool dialog box is first opened, initializeParameters is called. You set up the static rules for describing the output. No output description is created at this time, since the user hasn't specified values for any of the parameters.
- Once the user interacts with the tool dialog box in any way, updateParameters is called.
- updateParameters can modify the schema to account for dynamic behavior that can't be determined from the parameter dependencies, such as adding a new field like Add Field.
- After returning from updateParameters, the internal validation routines are called, and the rules found in the Schema object are applied to update the description of the output data.
- updateMessages is then called. You can examine the warning and error messages that internal validation may have created and modify them or add warnings and errors.
Output dataset name: Cloning derived output versus required output
When you set the Schema.clone property to true, you are instructing geoprocessing to make an exact copy (clone) of the description in the first dependent parameter in the parameter dependency list. Typically, you set clone to true in initializeParameters rather than updateParameters since it only needs to be set once.
If ParameterType of the output parameter is set to Derived, an exact copy is made. This is the behavior of the Add Field tool.
If ParameterType is set to Required, an exact copy is also made, but the catalog path to the dataset is changed. Since most tools create data, this is the most common behavior.
Learning more
Programming a ToolValidator class provides details on the Parameter, Schema, and Filter objects and gives code examples.
All script-based system tools, such as Multiple Ring Buffer, have ToolValidator code from which you can examine and learn. Many of the tools in the Spatial Statistics toolbox are script tools and have ToolValidator implementation you can examine.