Define parameters in a Python toolbox

Almost all tools have parameters, and you set their values on the tool dialog box or in a script. When the tool is run, the parameter values are sent to the tool's source code. The tool reads these values and processes them accordingly.

To learn more about parameters, see Understanding script tool parameters.

In a Python toolbox (.pyt), tool parameters are defined in the getParameterInfo method of the tool class by creating Parameter objects and setting their properties.

Parameter objects have many read-write properties, but the properties that should be set for every parameter include the following:

Property	Description
displayName	The parameter name as shown in the Geoprocessing pane.
name	The parameter name as shown in the tool's syntax in Python.
datatype	Every Python toolbox tool parameter has an associated data type. When you open the Geoprocessing pane, the data type is used to check the parameter value. The data type is also used in browsing for data—only data that matches the parameter data type will be shown on the browse dialog box. For a list of parameter data types, see Parameter data types in a Python toolbox.
parameterType	The following are the options for parameterType: Required—The tool cannot be run until a value has been provided. Optional—The parameter does not require a value. Derived—The parameter is only for output parameters (see the direction property below). A derived output parameter does not appear on the tool dialog box.
direction	This property defines whether the parameter is an input to the tool or an output of the tool. The options are Input and Output. If parameterType is set to Derived, set direction to Output.

The example below defines three parameters for a tool: an input parameter that accepts a feature layer, an input parameter that accepts a new field name, and a derived output parameter based on the first input parameter. For the parameters to be reflected in the tool, return the parameters at the end of the getParameterInfo method.

def getParameterInfo(self):
    #Define parameter definitions

    # First parameter
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input")

    # Second parameter
    param1 = arcpy.Parameter(
        displayName="Sinuosity Field",
        name="sinuosity_field",
        datatype="Field",
        parameterType="Optional",
        direction="Input")

    param1.value = "sinuosity"

    # Third parameter
    param2 = arcpy.Parameter(
        displayName="Output Features",
        name="out_features",
        datatype="GPFeatureLayer",
        parameterType="Derived",
        direction="Output")

    param2.parameterDependencies = [param0.name]
    param2.schema.clone = True

    params = [param0, param1, param2]

    return params

Derived outputs

The last parameter shown above is a derived output parameter. There are five uses for a derived output parameter as follows:

• The output is the same as the input, such as Calculate Field or the example shown above. Calculate Field changes the values of a particular field on the input table; it doesn't create a table or modify the schema of the input. Other tools whose output is the same as the input can be found in the Editing toolbox.
• The tool modifies the schema of the input, such as Add Field. Add Field adds a field to the input table; it doesn't create an output table.
• The tool creates output using information from other parameters, such as the Create Feature Class tool. With the Create Feature Class tool, you specify the workspace and the name of the new feature class, and the tool creates the feature class.
• The tool creates an output scalar value as opposed to a dataset. Get Count, for example, creates an output long value (the number of records). Whenever a tool outputs a scalar value, the output is derived.
• The tool creates data in a known location. For example, you have a script that updates an existing table in a known workspace. The user doesn't need to provide this table on the dialog box or in scripting.

Multivalue parameters

If you want a parameter to handle a list of values rather than only one value, set the multiValue property to True.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input",
        multiValue=True)

The following is an example of a multivalue parameter:

Value table parameters

Value table parameters allow you to specify multiple entries. For example, you can include multiple datasets for the Input Features parameter in the Append, Union, and a number of other tools, or you can include multiple fields for the Statistics Fields parameter in the Dissolve and Summary Statistics tools.

Value table parameters are defined by setting datatype to GPValueTable and setting a columns property to define the data types and column headings of the parameter. In the example below, a value table parameter is defined with two columns that accept field names and string values for Statistic Type (GPString). When using a ValueList filter and a list of values, you can generate a drop-down list for the parameter control under the corresponding GPValueTable column. To set default values for a value table parameter, use the values property and provide the parameter values in a list of lists of values.

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

    param1 = arcpy.Parameter(
        displayName='Statistics Field(s)',
        name='stat_fields',
        datatype='GPValueTable',
        parameterType='Required',
        direction='Input')

    param1.parameterDependencies = [param0.name]
    param1.columns = [['Field', 'Field'], ['GPString', 'Statistic Type']]
    param1.filters[1].type = 'ValueList'
    param1.values = [['NAME', 'SUM']]
    param1.filters[1].list = ['SUM', 'MIN', 'MAX', 'STDEV', 'MEAN']

Optionally, to make a column read-only, you can define the columns property with an additional ReadOnly value. A value of ReadOnly will present the column for information purposes only, for example, param1.columns = [['Field', 'Field', 'ReadOnly'], ['GPString', 'Statistic Type']].

Field columns have an implicit dependency on the first data column in the value table. The parameter's drop-down list for any subsequent field column will automatically include any available fields in the data.

Set default values for a parameter

Default values can be set for a parameter by either applying a value directly with the value property or by applying the value of an environment setting using defaultEnvironmentName.

The default value is the contents of the parameter when the script tool is opened. It is also the value that will be used if a # is entered for the parameter in scripting. If you don't specify a value, the parameter value will be blank when the script tool is opened.

Set a default value from an environment

You can set the default value for a parameter to the value of an environment setting by setting the defaultEnvironmentName property to the name of an environment setting. Once you choose an environment setting, the value property will be ignored.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Workspace",
        name="in_workspace",
        datatype="DEWorkspace",
        parameterType="Required",
        direction="Input")

    # In the tool's dialog box, the first parameter will show 
    #  the workspace environment's value (if set)
    param0.defaultEnvironmentName = "workspace"

Parameter schema

Every output parameter of type feature class, table, raster, or workspace has a schema object. Only output feature classes, tables, rasters, and workspaces have a schema; other types do not. The schema object is created by geoprocessing. You access this schema through the parameter object and set the rules for describing the output of the tool. After you set the schema rules, the geoprocessing internal validation code checks the rules you set and updates the description of the output.

When the input parameter datatype is a feature set or record set, you must specify the fieldsRule and geometryType values of the features to be entered.

Feature sets and record sets

The Feature Set and Record Set data types allow interactive input of data. Feature Set allows the user of a script to interactively create features by clicking the map. Record Set allows the user to interactively create rows in a table grid.

The symbology and schema (attributes and geometry type) can be set for the Feature Set and Record Set data types by setting the parameter's value property to a feature class, table, or layer file (.lyrx).

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Feature Set",
        name="in_feature_set",
        datatype="GPFeatureRecordSetLayer",
        parameterType="Required",
        direction="Input")

    # Use __file__ attribute to find the .lyr file (assuming the
    #  .pyt and .lyr files exist in the same folder)
    param0.value = os.path.join(os.path.dirname(__file__),
                                'Fire_Station.lyrx')

Apply filters to a parameter

Applying a filter to a parameter allows you to narrow the choices available to the user for a parameter. For example, you can set up a field filter that limits choices to only text fields.

Geoprocessing creates filters automatically for parameters of type string, long, double, feature class, file, field, and workspace. Even if you don't set a filter for the parameter, there is still a filter associated with the parameter—it's just empty. An empty filter is the same as having no filter. By adding values to an empty filter, you activate the filter, and the user's choices are limited by the contents of the filter:

• A filter only presents the user with valid choices when browsing for data. If you set a filter for point feature classes, only point feature classes are shown when the user browses for data. If you set a filter for text fields, the drop-down list of fields only shows text fields.
• If a user types a parameter value (rather than choosing a value from the list or file browser), the value is compared to the filter. If the user enters an invalid value (a numeric field instead of a text field, for example), a warning or error occurs.

If you want only certain values or dataset types to be entered for a parameter, you can specify a filter. Set the filter object's type property to the appropriate value. The filter types are described in the table below, and the available filter types depend on the data type of the parameter.

Filter type and values

Filter type	Values
Value List	A list of string or numeric values used with String, Long, Double, Boolean, Linear Unit, Areal Unit, and Time Unit data types. For Linear Unit, Areal Unit, and Time Unit Value List filters, provide a list of unit keyword strings, and only values using those units will be considered valid and shown in the unit drop-down list on the tool dialog box.
Range	A minimum and maximum value used with Long, Double, Linear Unit, Areal Unit, and Time Unit data types. For Linear Unit, Areal Unit, and Time Unit Range filters, provide a list with the minimum and maximum value including a unit, for example, ["1 Meters", "100 Meters"].
Feature Class	A list of allowable feature class types: Point, Multipoint, Polyline, Polygon, MultiPatch, Annotation, and Dimension. More than one value can be provided.
File	A list of file suffixes, for example, ['zip', 'xml'].
Field	A list of allowable field types: Short, Long, Float, BigInteger, Single, Double, Text, Date, OID, TimeOnly, DateOnly, TimestampOffset, Geometry, Blob, Raster, GUID, GlobalID, and XML. More than one value can be provided.
Workspace	A list of allowable workspace types: File System, Local Database, and Remote Database. More than one value can be provided.
Travel Mode Unit Type	A list of allowable travel modes' impedance attribute: Time, Distance, or Other.

filter properties

Property	Description
type	The type of filter (ValueList, Range, FeatureClass, File, Field, and Workspace). You can set the type of filter when dealing with Long, Double, Linear Unit, Areal Unit, and Time Unit parameters (see the note below). For other types of parameters, there is only one valid type of filter, so setting the type on these parameters is ignored. If you do not want to filter values, set the list property to an empty list.
list	A list of values for the filter. If you do not want to filter values, set the list property to an empty list.

Typically, there is only one filter type available. Only Long, Double, Linear Unit, Areal Unit, and Time Unit parameters have two choices: ValueList and Range.

Value List

This filter can be used to provide a set of keywords. Many tools have a predefined set of keywords, such as the Field Type parameter in the Add Field tool or the Join Attributes parameter of many of the tools in the Overlay toolset.

The value list filter can be used for Long, Double, Linear Unit, Areal Unit, and Time Unit data types. For these types, enter the allowable numeric values or unit values.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input value",
        name="in_value",
        datatype="GPLong",
        parameterType="Required",
        direction="Input")

    # Set a value list of 1, 10 and 100
    param0.filter.type = "ValueList"
    param0.filter.list = [1, 10, 100]

If you want the user to be able to choose more than one of the values, set the multiValue property to True.

The value list filter can also be used for Boolean data types. For Boolean data types, this filter contains two values: true and false. These value are used in Python for specifying the value. The true value is the first value in the list. For an example, see Add Field and the NULLABLE and NON_NULLABLE keywords used for the field_is_nullable parameter.

Range

The range filter has two values: minimum and maximum. The first value in the list is the minimum. The range is inclusive, meaning the minimum and maximum values are valid choices. A Long, Double, Linear Unit, Areal Unit, or Time Unit parameter can use this filter.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input range",
        name="in_range",
        datatype="GPLong",
        parameterType="Required",
        direction="Input")

    # Set an acceptable range of 1 to 10
    param0.filter.type = "Range"
    param0.filter.list = [1, 10]

Feature Class

For this filter, choose one or more filter values. Input feature classes will be checked using the filter values. For example, if you choose Point as the only filter value, the user can only enter point feature classes as the parameter value.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input")
    param0.filter.list = ["Polygon"]

File

The file filter contains a list of file suffixes that a file may have, such as txt (simple text file) and csv (comma-separated values). You can supply any text for a suffix—it doesn't have to be a suffix that ArcGIS recognizes. The suffix can be of any length and does not include the dot.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input File",
        name="in_file",
        datatype="DEFile",
        parameterType="Required",
        direction="Input")

    # To define a file filter that includes .csv and .txt extensions,
    #  set the filter list to a list of file extension names
    param0.filter.list = ['txt', 'csv']

Field

The field filter defines the permissible field types. The values are provided in the filter type table above. More than one value can be provided.

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

    param1 = arcpy.Parameter(
        displayName="Field",
        name="field",
        datatype="Field",
        parameterType="Required",
        direction="Input")

    # Set the filter to accept only fields that are Short or Long type
    param1.filter.list = ['Short', 'Long']
    param1.parameterDependencies = [param0.name]

Workspace

The workspace filter specifies the types of input workspaces that are permissible. The descriptions of the values are as follows:

Value	Description
File System	A system folder used to store shapefiles and grids
Local Database	A personal or file geodatabase
Remote Database	An enterprise database connection

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Workspace",
        name="in_workspace",
        datatype="DEWorkspace",
        parameterType="Required",
        direction="Input")

    # Set the filter to accept only local geodatabases
    param0.filter.list = ["Local Database"]

Travel Mode Unit Type

This filter can be used to set the permissible travel mode types based on the unit of the travel mode's impedance attribute.

def getParameterInfo(self):
    param1 = arcpy.Parameter(
        displayName="Travel Mode",
        name="travel_mode",
        datatype="NetworkTravelMode",
        parameterType="Required",
        direction="Input")

     # Set the parameter to be dependent on the Network Data Source parameter
     param1.parameterDependencies = [param0.name]
     # Set the filter to accept only time-based travel modes
     param1.filter.list = ["Time"]

Dependency

The parameterDependencies property has the following purposes:

• For an output dataset parameter with a derived type, the dependency is the index of the parameter from which the output is derived.
• For certain input data types, the dependency is the index of the parameter containing the information used by the control, as shown in the table below.

# Third parameter
param2 = arcpy.Parameter(
    displayName="Output Features",
    name="out_features",
    datatype="GPFeatureLayer",
    parameterType="Derived",
    direction="Output")

param2.parameterDependencies = [param0.name]
param2.schema.clone = True

You can only set parameterDependencies values for certain input parameters as shown in the following table:

parameterDependencies data types

Parameter data type	Dependant parameter data type
Areal Unit (GPArealUnit)	A geographic dataset used to determine the default units. For example, the Feature Layer (GPFeatureLayer), Raster Layer (GPRasterLayer), Feature Set (GPFeatureRecordSetLayer), or Record Set (GPRecordSet) data type can be used.
Field (Field)	The table containing the fields. For example, the Table View (GPTableView), Feature Layer (GPFeatureLayer), Raster Layer (GPRasterLayer), Feature Set (GPFeatureRecordSetLayer), or Record Set (GPRecordSet) data type can be used.
Field Mappings (GPFieldMapping)	A collection of fields in one or more input tables. For example, the Table View (GPTableView), Feature Layer (GPFeatureLayer), Raster Layer (GPRasterLayer), Feature Set (GPFeatureRecordSetLayer), or Record Set (GPRecordSet) data type can be used.
Geostatistical Value Table ( GPGAValueTable)	A table of datasets and fields to be used in Geostatistical Analyst tools. Use the Geostatistical Layer (GPGALayer) data type.
Linear Unit (GPLinearUnit)	A geographic dataset used to determine the default units. For example, the Feature Layer (GPFeatureLayer), Raster Layer (GPRasterLayer), Feature Set (GPFeatureRecordSetLayer), or Record Set (GPRecordSet) data type can be used.
Network Analyst Hierarchy Settings (GPNAHierarchySettings)	The network dataset containing hierarchy information. Use the Network Dataset (DENetworkDataset) data type.
Network Travel Mode (NetworkTravelMode)	A list of travel modes. Use the Network Data Source (GPNetworkDataSource), Network Dataset (DENetworkDataset), or Network Dataset Layer (GPNetworkDatasetLayer) data type.
SQL Expression (GPSQLExpression)	The table containing the fields. For example, the Table View (GPTableView), Feature Layer (GPFeatureLayer), Raster Layer (GPRasterLayer), Feature Set (GPFeatureRecordSetLayer), or Record Set (GPRecordSet) data type can be used.

Symbology

If the output of the tool is a feature set, raster, TIN, or Network Analyst layer, you can specify the location of a layer file (.lyrx) with the symbology property. When the tool is run, the output is added to the display and drawn using the symbology defined in the symbology layer file.

def getParameterInfo(self):
    param0 = arcpy.Parameter(
        displayName="Input Raster",
        name="in_raster",
        datatype="DERasterDataset",
        parameterType="Required",
        direction="Input")

    param1 = arcpy.Parameter(
        displayName="Output Raster",
        name="out_raster",
        datatype="DERasterDataset",
        parameterType="Required",
        direction="Output")

    # Use __file__ attribute to find the .lyr file (assuming the
    #  .pyt and .lyr files exist in the same folder).
    param1.symbology = os.path.join(os.path.dirname(__file__), 
                                    'raster_symbology.lyrx')

Note:

The layer file is read each time the tool is run. If the layer file cannot be found (because it was moved or deleted), default symbology will be used.

Category

Parameters can be grouped into various categories to minimize the size of the tool dialog box or to group related parameters that will be infrequently used. Parameters that set the category property to the same string value will be grouped together. Several ArcGIS Network Analyst extension tools use categories as shown below.

Categories are shown after uncategorized parameters. Do not put required parameters into categories, as they are hidden from view on the tool dialog box.