Parameter (arcpy)

Summary

Every tool parameter has an associated parameter object with properties and methods that are useful in tool validation. Parameters are contained in a Python list.

Syntax

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

Parameter	Explanation	Data Type
name	The parameter name. (The default value is None)	String
displayName	The parameter label as shown on the tool's dialog box. (The default value is None)	String
direction	Input/Output direction of the parameter. (The default value is None)	String
datatype	The data type of the parameter. For a list of parameter data types, see Geoprocessing data types. (The default value is None)	String
parameterType	Can be Required, Optional, or Derived. Derived means that the user of your tool does not enter a value for the parameter. Derived types are always output parameters. (The default value is None)	String
enabled	False if the parameter is unavailable. (The default value is None)	Boolean
category	The category of the parameter. (The default value is None)	String
symbology	The path to a layer file (.lyr) used for drawing the output. (The default value is None)	String
multiValue	True if the parameter is a multivalue parameter. (The default value is None)	Boolean

Properties

Property	Explanation	Data Type
altered (Read Only)	True if the user has modified the value.	Boolean
category (Read and Write)	The category of the parameter.	String
columns (Read and Write)	The column data types and names of a value table parameter. Set using a list of lists: import arcpy param = arcpy.Parameter() param.datatype = "Value Table" param.columns = [["Feature Layer", "Features"], ["Long", "Ranks"]]	String
datatype (Read and Write)	The data type of the parameter. For a list of parameter data types, see Geoprocessing data types.	String
defaultEnvironmentName (Read and Write)	The geoprocessing environment setting used to set the parameter's default value.	String
direction (Read and Write)	Input/Output direction of the parameter.	String
displayName (Read and Write)	The parameter label as shown on the tool's dialog box.	String
enabled (Read and Write)	False if the parameter is unavailable.	Boolean
filter (Read Only)	The filter to apply to values in the parameter.	Filter
hasBeenValidated (Read Only)	True if 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)	True if 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.	Integer
parameterType (Read and Write)	Can be Required, Optional, or Derived. Derived means that the user of your tool does not enter a value for the parameter. Derived types are always output parameters. Required —A Required parameter requires an input value from the user. The tool cannot be executed until a value has been supplied. Optional — An Optional parameter does not require a value. Derived —A Derived parameter is only for output parameters. A derived output parameter does not show on the tool dialog box.	String
schema (Read Only)	The schema of the output dataset.	Schema
symbology (Read and Write)	The path to a layer file (.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. Note: For Python toolboxes only.	String
values (Read and Write)	The values of the Value Table parameter. Set using a list of lists.	Variant

Method Overview

Method	Explanation
clearMessage ()	Clears out any message text and sets the status to informative (no error or warning).
hasError ()	Returns true if the parameter contains an error.
hasWarning ()	Returns True if the parameter contains a warning.
isInputValueDerived ()	Returns True if the tool is being validated inside a Model and the input value is the output of another tool in the model.
setErrorMessage (message)	Marks the parameter as having an error with the supplied message. Tools do not execute if any of the parameters have an error.
setIDMessage (message_type, message_ID, {add_argument1}, {add_argument2})	Allows you to set a system message.
setWarningMessage (message)	Marks the parameter as having a warning with the supplied message. Unlike errors, tools will execute with warning messages.

Methods

clearMessage ()

hasError ()

Return Value

Data Type	Explanation
Boolean	True if the parameter contains an error.

hasWarning ()

Return Value

Data Type	Explanation
Boolean	True if the parameter contains a warning.

isInputValueDerived ()

Return Value

Data Type	Explanation
Boolean	True if the tool is being validated inside a Model and the input value is the output of another tool in the model.

setErrorMessage (message)

Parameter	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})

Parameter	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	Depending on which message ID is used, an argument may be necessary to complete the message. Common examples include dataset or field names. The datatype is variable depending on the message.	Object
add_argument2	Depending on which message ID is used, an argument may be necessary to complete the message. Common examples include dataset or field names. The datatype is variable depending on the message.	Object

setWarningMessage (message)

Parameter	Explanation	Data Type
message	The string to be added as a warning message to the geoprocessing tool messages.	String

Code Sample

Parameter example

Enabling or disabling a parameter in a ToolValidator class.

def updateParameters(self):
    # If the option to use a weights file is selected (the user choose
    # "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 = 1
    else:
        self.params[8].enabled = 0

    return

Parameter example 2

Setting 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

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

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

    return