arcsmith.param

Parameter

Helpers for managing 'arcpy.Parameter' state in a tool's 'updateParameters' function.

Create dynamic ArcPy toolboxes that respond to user input
Automatically reset specified parameters following a change to an upstream value
Populate parameters and dropdowns with contextual content

Functions of the `param` module

state

Translates a parameter's altered + hasBeenValidated flags into a single readable state.

state(param: arcpy.Parameter) -> str

State	`.altered`	`.hasBeenValidated`	Description
`fresh`	`False`	`False`	Initial, untouched state
`pending`	`True`	`False`	Changed, awaiting validation
`settled`	`False`	`True`	Validated, not changed since
`confirmed`	`True`	`True`	Changed and validated

Tip

'pending' is the most important state to detect. It marks the exact moment a value was just changed and marks the right time to reset or re-populate dependent parameters.

Example

# React only the moment a value changes
if arcsmith.param.state(parameters[0]) == 'pending':
    parameters[1].value = None

cascade_populate

Assigns a specific value to downstream parameters. Useful when a required downstream parameter needs to hold a concrete placeholder rather than be left empty.

cascade_populate(trigger_param, downstream_params, value=None)

Parameter	Type	Default	Description
`trigger_param`	`arcpy.Parameter`	required	The parameter whose change triggers the cascade.
`downstream_params`	`arcpy.Parameter` or list of `arcpy.Parameter`	required	Parameter(s) to set when `trigger_param` is `'pending'` or `'fresh'`. A single parameter may be passed without a list.
`value`	scalar or list	`None`	Value assigned to each downstream parameter. A scalar is broadcast to all; a list maps one-to-one. Default `None` clears them.

Note

Safe to call unconditionally on every updateParameters pass. If trigger_param is not 'pending' or 'fresh' the call is a no-op.

Raises

ValueError if value is a list whose length differs from downstream_params.

Examples

# Reset all dependents to the same concrete value
arcsmith.param.cascade_populate(parameters[0], [parameters[1], parameters[2]], value=100)

# Reset each dependent to a different value
arcsmith.param.cascade_populate(parameters[0],
                                [parameters[1], parameters[2]],
                                value=["Population", 3000])

# Reset all dependents to the default: None
# (cascade_clear performs the same operation)
arcsmith.param.cascade_populate(parameters[0], [parameters[1], parameters[2]])

cascade_clear

Clears downstream parameters the moment an upstream value changes.

cascade_clear(trigger_param, downstream_params)

Parameter	Type	Default	Description
`trigger_param`	`arcpy.Parameter`	required	The parameter whose change triggers the cascade.
`downstream_params`	`arcpy.Parameter` or list of `arcpy.Parameter`	required	Parameters to clear when `trigger_param` is `'pending'` or `'fresh'`.

Fires on both unvalidated states: 'fresh' and 'pending'

cascade_clear fires on both states so that clearing, resetting, or changing an upstream value reliably resets its dependents.

Examples

# Clear a single downstream parameter
arcsmith.param.cascade_clear(parameters[0], parameters[1])

# Clear multiple downstream parameters at once
arcsmith.param.cascade_clear(parameters[0], [parameters[1], parameters[2]])

drop_populate

Fills a parameter's dropdown list. Call this every updateParameters pass whenever the options depend on an upstream value. drop_populate is a no-op if the dropdown list hasn't changed and won't overwrite anything the user has already selected.

drop_populate(param, values, default=None, overwrite_empty=False, none_label=None)

Parameter	Type	Default	Description
`param`	`arcpy.Parameter`	required	The parameter to populate with a dropdown.
`values`	list	required	Options to display in the dropdown. Non-string values are coerced to `str` automatically. `None` entries are dropped unless `none_label` is provided.
`default`	`str`	`None`	Value to pre-select after the filter list is set. Only applied while the parameter is `'fresh'` or `'settled'` so existing user input is never overwritten. Ignored when the filter list is not updated.
`overwrite_empty`	`bool`	`False`	If `True`, updates the filter even when `values` is empty. Use this to clear a stale list when an upstream value is removed.
`none_label`	`str`	`None`	If provided, `None` entries in `values` are replaced with this string rather than dropped. Note that selecting this label and passing it to `arcsmith.fc.build_where` will not produce a valid `IS NULL` clause — handle that case separately.

Note

Passing an empty values list is silently ignored by default. This prevents wiping a valid dropdown when the upstream feature class parameter hasn't been set yet on tool open.

Null values

None entries are dropped silently by default since arcpy's ValueList filter requires strings and null is rarely a meaningful selectable option. Pass none_label="(No value)" if the user needs to be able to select null explicitly, and handle that sentinel separately before passing the value to build_where.

Examples

# Populate dropdown options and pre-select a sensible default
arcsmith.param.drop_populate(
    parameters[1],
    ["PARCEL_ID", "OWNER", "AREA_SQFT"],
    default="PARCEL_ID",
)

# Explicitly clear a stale dropdown when the upstream value is removed
arcsmith.param.drop_populate(parameters[1], [], overwrite_empty=True)

# Fill a dropdown with unique field values — None entries and non-strings
# are handled automatically; no manual coercion needed at the call site
values = arcsmith.flds.unique_values(input_fc, "STATUS")
arcsmith.param.drop_populate(parameters[1], values)

# Common pattern: clear the dropdown when the feature class changes,
# then refill it if a feature class is currently set
arcsmith.param.cascade_clear(parameters[0], parameters[1])
arcsmith.param.drop_populate(
    parameters[1],
    arcsmith.flds.list_cols(parameters[0].valueAsText)
    if parameters[0].valueAsText else [],
    overwrite_empty=True,
)

checkbox_dependence

Shows, hides, and seeds dependent parameters based on a controlling checkbox. Parameters are disabled while the checkbox is unchecked, enabled the moment it's checked, and left alone on every subsequent pass so that the user's input isn't overwritten.

checkbox_dependence(
    controlling_checkbox,
    dependents,
    hidden_value=None,
    shown_value=None,
    auto_hide_dependents=True
)

Parameter	Type	Default	Description
`controlling_checkbox`	`arcpy.Parameter`	required	Checkbox that drives the state of all dependents.
`dependents`	`arcpy.Parameter` or list of `arcpy.Parameter`	required	Parameter(s) to control. A single parameter may be passed without a list.
`hidden_value`	scalar or list	`None`	Value(s) assigned while dependents are inactive (checkbox unchecked). A scalar broadcasts to all; a list maps one-to-one. Applied regardless of `auto_hide_dependents`.
`shown_value`	scalar or list	`None`	Value(s) assigned the moment dependents are first shown (checkbox just checked). Same scalar/list rules.
`auto_hide_dependents`	`bool`	`True`	If `True`, dependents are not visible while the controlling checkbox is unchecked.

Autohide for tool development

Set to false False during tool development to interact with each dependent parameter regardless of controlling checkbox state.

Checkbox state	Effect
Unchecked, `auto_hide_dependents=True`	`hidden_value` assigned; dependents disabled.
Unchecked, `auto_hide_dependents=False`	`hidden_value` assigned; dependents remain enabled.
Just checked (`'pending'`)	`shown_value` assigned; dependents enabled.
Otherwise (stable)	No-op. Existing user input is preserved.

Raises

ValueError if hidden_value or shown_value is a list whose length differs from dependents.

Examples

# The simplest case: disable dependents when unchecked, enable when checked
arcsmith.param.checkbox_dependence(parameters[0], [parameters[1], parameters[2]])

# Keep dependent parameters satisfied with a placeholder
# value while inactive by using the hidden_value argument
arcsmith.param.checkbox_dependence(
    parameters[0],
    [parameters[1], parameters[2]],
    hidden_value=-999,
)

# Seed a starting value when the checkbox is first checked
arcsmith.param.checkbox_dependence(
    parameters[0],
    parameters[1],
    hidden_value=0,
    shown_value=100,
)

# Different hidden and shown values per dependent
arcsmith.param.checkbox_dependence(
    parameters[0],
    [parameters[1], parameters[2]],
    hidden_value=["Empty/Path", -999],
    shown_value=["", 1],
)

# Keep dependents visible while testing (hidden_value is still applied)
arcsmith.param.checkbox_dependence(
    parameters[0],
    [parameters[1], parameters[2]],
    hidden_value=-999,
    auto_hide_dependents=False,
)

dynamic_dropdown

Dynamically enables/disables parameters based on what's selected in dropdown. Each option in the dropdown maps to a group of parameters; when that option is selected its group is enabled and all other groups are disabled.

dynamic_dropdown(
    controlling_dropdown,
    option_map,
    hidden_value_map=None,
    shown_value_map=None,
    auto_hide_dependents=True
)

Parameter	Type	Default	Description
`controlling_dropdown`	`arcpy.Parameter`	required	The parameter whose value controls which dependent parameter group is active.
`option_map`	dict of `str` to `arcpy.Parameter` or list of `arcpy.Parameter`	required	Maps each dropdown option to the dependent parameters that will be enabled when that option is selected. A single parameter may be passed without wrapping it in a list.
`hidden_value_map`	dict of `str` to scalar or list	`None`	Values assigned to an option's dependent parameters while that group is inactive. Applied regardless of `auto_hide_dependents`. Per key: a scalar broadcasts to all parameters in that group; a list maps one-to-one. Missing keys fall back to `None`.
`shown_value_map`	dict of `str` to scalar or list	`None`	Values assigned to an option's dependent parameters the moment the option is selected. Same per-key rules as `hidden_value_map`. Missing keys fall back to `None`.
`auto_hide_dependents`	`bool`	`True`	If `True`, dependents are not visible while dropdown options is not selected.

Autohide for tool development

Set to False during tool development to interact with each dependent parameter regardless of controlling dropdown's selected option.

Dropdown state	Effect
Inactive group, `auto_hide_dependents=True`	`hidden_value_map` applied; group disabled.
Inactive group, `auto_hide_dependents=False`	`hidden_value_map` applied; group remains enabled.
Active group, just selected (`'pending'`)	`shown_value_map` applied; group enabled.
Active group, stable	No-op; existing user input preserved. Group enabled.

Note

Length checks run for every option up front, so a misconfigured hidden_value_map or shown_value_map entry is caught immediately - even when that option isn't currently selected.

# drop_populate owns the filter list; dynamic_dropdown owns the selected value
arcsmith.param.drop_populate(parameters[4], ["Rectangle by Area", "Convex Hull", "Envelope"])

arcsmith.param.dynamic_dropdown(
    parameters[1],
    option_map={"Minimum Bounding Geometry": [parameters[4]], ...},
    shown_value_map={"Minimum Bounding Geometry": ["Envelope"], ...},
)

Raises

ValueError if any hidden_value_map or shown_value_map list length differs from its option_map counterpart.

Examples

# Show a different parameter for each input type
arcsmith.param.dynamic_dropdown(
    parameters[0],
    option_map={
        # when "Shapefile" is selected in dropdown,
        # 'parameters[1]' is enabled. Dependents of other options are disabled.
        "Shapefile": parameters[1],
        # when "Feature Class" is selected in dropdown,
        # 'parameters[2]+[3]' are enabled. Dependents of other options are disabled.
        "Feature Class": [parameters[2], parameters[3]]
    }
)

# Seed a starting value when an option is selected,
# and fill inactive groups with a placeholder value
arcsmith.param.dynamic_dropdown(
    parameters[0],
    option_map={
        "Shapefile": [parameters[1]],
        "Feature Class": [parameters[2], parameters[3]],
    },
    shown_value_map={
        "Shapefile": [""],  # start p1 as an empty string
        "Feature Class": ["N/A", 0],  # one value per parameter in the group
    },
    hidden_value_map={
        "Feature Class": "N/A"  # scalar broadcasts to all dependents (p2 and p3)
    }
)

# Only seed one option; the other starts unset
arcsmith.param.dynamic_dropdown(
    parameters[0],
    option_map={
        "Shapefile":     parameters[1],
        "Feature Class": [parameters[2], parameters[3]],
    },
    shown_value_map={
        "Shapefile": ""  # "Feature Class" omitted, therefore its params start as None by default
    }
)

# Keep all groups visible while testing
arcsmith.param.dynamic_dropdown(parameters[0], option_map, auto_hide_dependents=False)

to_path

Resolves a feature class or layer parameter to its real catalog path. Use this in execute instead of param.valueAsText whenever the user might select from the map TOC rather than browse to a file.

to_path(param: arcpy.Parameter) -> str

Returns

str: absolute catalog path to the data source.

Why not valueAsText?

valueAsText returns whatever is shown in the tool dialog. When a user picks an existing map layer, that's the layer's TOC name (e.g. "Parcels 2024"), not a path arcpy can open. param_to_path calls arcpy.Describe on the parameter value and returns catalogPath which is always an absolute, resolvable path.

Use Path(param.valueAsText) only for parameters typed as plain file paths, such as an output folder or a .lyrx file.

Examples

# Resolve a feature class parameter before passing it to other arcsmith functions
fc_path = arcsmith.param.to_path(parameters[0])
clause = arcsmith.fc.build_where(fc_path, "STATUS", "Active")
out = arcsmith.flds.copy_w_fields(fc_path, output_fc, ["PARCEL_ID", "OWNER", "STATUS"],
                                    where_clause=clause)

# Resolve in updateParameters to drive a downstream field dropdown
fc_path = arcsmith.param.to_path(parameters[0])
arcsmith.param.drop_populate(parameters[1], arcsmith.flds.list_cols(fc_path))

arcsmith.param

Parameter

Functions of the param module

state

cascade_populate

cascade_clear

drop_populate

checkbox_dependence

dynamic_dropdown

to_path

Functions of the `param` module