Skip to main content

Parameter

Summary

Every tool parameter has an associated Parameter object with properties and methods that are useful in tool validation.

Discussion

Although many Parameter object properties are read/write, most of them can only be set or modified when you initially create or modify the object. The following properties establish the characteristics of a parameter and cannot be modified during validation methods (such as updateMessages and updateParameters):

  • category

  • controlCLSID

  • datatype

  • direction

  • displayName

  • displayOrder

  • multiValue

  • name

  • parameterDependencies

  • parameterType

Syntax

Parameter({name}, {displayName}, {direction}, {datatype}, {parameterType}, {enabled}, {category}, {symbology}, {multiValue})

Name Explanation Data type

name

(Optional)

The parameter name.

The default value is None.

String

displayName

(Optional)

The parameter label as shown in the Geoprocessing pane.

The default value is None.

String

direction

(Optional)

Specifies the direction of the parameter.

The default value is Input.

String

datatype

(Optional)

The data type of the parameter.

Learn more about geoprocessing data types.

The default value is GPString.

String

parameterType

(Optional)

Specifies the parameter type.

The default value is Required.

String

enabled

(Optional)

Specifies whether the parameter is visible in the Geoprocessing pane.

The default value is True.

Boolean

category

(Optional)

The category of the parameter.

The default value is None.

String

symbology

(Optional)

The path to a layer file (.lyrx or .lyr) used for drawing the output.

The default value is None.

String

multiValue

(Optional)

Specifies whether the parameter is a multivalue parameter.

The default value is False.

Boolean

Properties

Name Explanation Data type

altered

(Read only)

Specifies whether the user has modified the value.

Boolean

category

(Read and Write)

The category of the parameter.

String

charts

(Read and Write)

A list of Chart objects that are added to an output parameter.

Object

columns

(Read and Write)

The structure of the columns in a Value Table parameter.

The columns are organized in a list of lists, with each inner list representing the column data type, column name, and an optional read-only value. If the read-only value is set to ReadOnly, the column cannot be modified by the user.

import arcpy
param = arcpy.Parameter()
param.datatype = "GPValueTable"
param.columns = [["GPFeatureLayer", "Features"], ["GPLong", "Ranks"]]

String

controlCLSID

(Read and Write)

A class identifier that can be used to override the default control for the data type.

Learn more about parameter controls

String

datatype

(Read and Write)

The data type of the parameter.

Learn more about geoprocessing data types.

String

defaultEnvironmentName

(Read and Write)

The name of the geoprocessing environment that will be used to set the parameter's default value.

String

direction

(Read and Write)

Specifies the direction of the parameter.

  • Input—An input parameter

  • Output—An output parameter

String

displayName

(Read and Write)

The parameter label as shown in the Geoprocessing pane.

String

displayOrder

(Read and Write)

The order in which a parameter displays in the Geoprocessing pane. This may be different from the order the parameters are accessed from Python.

Integer

enabled

(Read and Write)

Specifies whether the parameter is visible in the Geoprocessing pane.

Boolean

filter

(Read only)

The filter to apply to values in the parameter.

Filter

filters

(Read and Write)

Similar to the filter property, but it is used to support value table and composite parameters.

For a value table parameter, set the filters property, and define a Filter object using the list and optional type for each column in the value table.

class ValueTableSampleTool(object):
    # __init__ left out to simplify example

    def getParameterInfo(self):
        in_fc = arcpy.Parameter(
            name='in_features',
            displayName='Input Features',
            datatype='GPFeatureLayer',
            direction='Input',
            parameterType='Required')

        vt = arcpy.Parameter(
            name='summary_fields',
            displayName='Summary fields',
            datatype='GPValueTable',
            direction='Input',
            parameterType='Optional')

        vt.parameterDependencies = [in_fc.name]
        vt.columns = [
          ['Field', 'Field'],
          ['GPString', 'Statistic'],
          ['GPDouble', 'Multiplier']
        ]
        vt.filters[0].list = ['Double', 'Float', 'Short', 'Long']
        vt.filters[1].type = 'ValueList'
        vt.filters[1].list = ['SUM', 'MIN', 'MAX', 'MEAN']
        vt.filters[2].type = 'Range'
        vt.filters[2].list = [0, 10]

        return [in_fc, vt]

For a composite parameter, set the filters property, and define a Filter object using a list for each data type in the composite parameter.

class CompositeSampleTool(object):
    # __init__ left out to simplify example

    def getParameterInfo(self):
        composite = arcpy.Parameter(
            name="composite_example",
            displayName="Composite Example",
            datatype=["GPString", "GPDouble"],
            parameterType="Optional",
            direction="Input",
            multiValue=True)

        composite.filters = ["CodedValue", "Range"]
        composite.filters[0].list = ["MIN", "MAX"]
        composite.filters[1].list = [1, 100]

        return [composite]

Filter

hasBeenValidated

(Read only)

Specifies whether the internal validation routine has checked the parameter.

Boolean

message

(Read only)

The message to be displayed to the user.

String

multiValue

(Read and Write)

Specifies whether the parameter is a multivalue parameter.

Boolean

name

(Read and Write)

The parameter name.

String

parameterDependencies

(Read and Write)

A list of indexes of each dependent parameter.

In a script tool, parameterDependencies is set with a list of parameter indexes; in a Python toolbox tool, parameterDependencies is set with a list of parameter names.

Integer

parameterType

(Read and Write)

Specifies the parameter type.

  • Required—The tool cannot be run until a value has been provided.

  • Optional—The parameter does not require a value.

  • Derived—The parameter returns an output value. Derived parameters are always output parameters and are not shown in the Geoprocessing pane.

For derived parameters, set the direction property to Output and the parameterType property to Derived.

In validation, the parameterType value cannot be dynamically modified. However, it may be necessary for a parameter to behave as a required parameter or an optional parameter depending on other parameter settings. If this is the case, set the parameter as optional. Then, in the validation updateMessages method, use the Parameter setIDMessage method with message ID 530 or 735. Using message ID 530 or 735 will cause an optional parameter to behave as a required parameter.

String

schema

(Read only)

The schema of the output dataset.

Schema

symbology

(Read and Write)

The path to a layer file (.lyrx or .lyr) used for drawing the output.

String

value

(Read and Write)

The value of the parameter.

Object

valueAsText

(Read only)

The value of the parameter as a string.

String

values

(Read and Write)

The values of a Value Table parameter, which is set using a list of lists.

Object

Methods

clearMessage()

Clears any message text and sets the status to informative (no error or warning).

hasError()

Returns True if the parameter contains an error.

To evaluate whether a parameter has an error, call hasError from the tool validation's updateMessages method.

Return value

Data type Explanation

Boolean

True if the parameter contains an error.

hasWarning()

Specifies whether the parameter contains a warning.

Return value

Data type Explanation

Boolean

Returns whether the parameter contains a warning.

isInputValueDerived()

Specifies whether the tool is validated inside a model and the input value is the output of another tool in the model.

Return value

Data type Explanation

Boolean

Returns whether the tool is validated inside a model and the input value is the output of another tool in the model.

setErrorMessage(message)

Sets a parameter as having an error with the supplied message. Tools do not execute if any of the parameters have an error.

Name Explanation Data type

message

The string to be added as an error message to the geoprocessing tool messages.

String

setIDMessage(message_type, message_ID, {add_argument1}, {add_argument2})

Sets a parameter as having a system message.

Name Explanation Data type

message_type

Defines whether the message will be an error or a warning.

  • ERROR—The message will be an error message.

  • WARNING—The message will be a warning message.

String

message_ID

The message ID allows you to reference existing system messages.

Integer

add_argument1

(Optional)

Depending on which message ID is used, an argument may be necessary to complete the message. Common examples include dataset or field names. The data type is variable depending on the message.

Object

add_argument2

(Optional)

Depending on which message ID is used, an argument may be necessary to complete the message. Common examples include dataset or field names. The data type is variable depending on the message.

Object

setWarningMessage(message)

Sets a parameter as having an error with the supplied message. Unlike errors, tools will execute with warning messages.

Name Explanation Data type

message

The string to be added as a warning message to the geoprocessing tool messages.

String

Code sample

Parameter example

Enable or disable a parameter in a ToolValidator class.

def updateParameters(self):
    # If the option to use a weights file ("Get Spatial Weights From File")
    # is selected, 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 = False

    return
Parameter example 2

Set a default value for a parameter in a ToolValidator class.

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].value:
        if not self.params[6].altered:
            extent = arcpy.Describe(self.params[0].value)
        width = extent.XMax - extent.XMin
        height = extent.YMax - extent.YMin

        if width < height:
            self.params[6].value = width / 100
        else:
            self.params[6].value = height / 100

        return
Parameter example 3

Set a custom error message for a parameter in a ToolValidator class.

def updateMessages(self):
    self.params[6].clearMessage()

    # Check whether 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. Be sure to specify "
                "a distance.")

    return