Filter (arcpy)

Summary

The filter object allows you to specify the choices available for a parameter.

Discussion

The filter object allows you to specify the choices available to the user for a parameter. For example, you can set up a field filter that limits choices to just text fields. A filter does three jobs:

• A filter only presents the user with valid choices when browsing for data. If you set your filter for point feature classes, only point feature classes are shown when the user browses for data. If you set your filter for text fields, the drop-down list of fields only shows text fields.
• If a user types in a parameter value (rather than picking a value from the list or file browser), the value is checked against the filter. If the user enters an invalid value (a numeric field instead of a text field, for example), a warning or error is automatically given.
• Because values are checked against their filter by internal validation, a filter frees you from having to program your own custom validation in the ToolValidator class.

There are two ways to specify filters:

• On the Parameters tab of the tool's properties dialog box, click the parameter, then click the cell next to Filter and choose the filter type from the drop-down list. After choosing the filter type, a dialog box opens where you specify the values for the filter.
• You can set the values programmatically in a ToolValidator class (examples are given below). Geoprocessing creates filters automatically for parameters of type string, long, double, feature class, file, field, and workspace. Even if you don't choose a filter on the tool's properties dialog box, 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.

Properties

Property	Explanation	Data Type
list (Read and Write)	If you do not want to filter values, set the list property to an empty list. The datatype specifiied depends on the filter type (ValueList, Range, FeatureClass, File, Field, and Workspace).	String
type (Read and Write)	The type of filter (ValueList, Range, FeatureClass, File, Field, and Workspace). You can set the type of filter when dealing with Long and Double parameters. 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.	Object

Code Sample

Filter example

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):
        return

Filter example 2

An example where 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
    string_filter = self.params[1].filter
    feature_class = self.params[0].value
    if feature_class:
        shape_type = arcpy.Describe(feature_class).shapeType
        if shape_type in ["Point", "Multipoint"]:
            string_filter.list = ["RED", "GREEN", "BLUE"]
        elif shape_type == "Polygon":
            string_filter.list = ["WHITE", "GRAY", "BLACK"]
        else:
            string_filter.list = ["ORANGE", "INDIGO", "VIOLET"]
    else:
        string_filter.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 = string_filter.list[0]

    return