Skip to content
arcsmith.flds

Fields

Utilities for field mapping, field-filtered copying, and blank value standardization.

  • Build field mappings to retain or drop specific fields before exporting
  • Standardize blank-like values across string fields
  • List field names or extract unique values for use in dropdowns

Functions of the flds module

build_field_map

Builds an arcpy.FieldMappings object that retains only a chosen subset of fields. Pass the result directly to any arcpy tool that accepts field mappings.

build_field_map(input_fc, fields=None, keep=True)
Parameter Type Default Description
input_fc str or Path required Path to the source feature class.
fields list of str None Field names to act on. When keep=True these are the fields to retain; all others are removed. When keep=False these are the fields to remove; all others are kept. Pass [] with keep=True to retain geometry only. Default None (all fields retained; keep is ignored).
keep bool True If True, fields specifies what to keep. If False, fields specifies what to drop. Ignored when fields is None.

Returns

arcpy.FieldMappings: ready to pass to arcpy.conversion.FeatureClassToFeatureClass or any other arcpy tool that accepts field mappings.

Raises

ValueError if any field name in fields does not exist in input_fc (system fields are exempt from this check).

System fields

OID, Shape, Shape_Length, Shape_Area, and GlobalID are managed internally by arcpy and are always present in the output regardless. Listing them in fields is silently ignored rather than raising an error.

Examples

# All fields - no filtering
fm = arcsmith.flds.build_field_map(input_fc)

# Keep only the fields you need
fm = arcsmith.flds.build_field_map(input_fc, ["NAME", "POP_2020", "STATE"])

# Drop fields you don't want and keep everything else
fm = arcsmith.flds.build_field_map(input_fc, ["NOTES", "TEMP_FLAG"], keep=False)

# Geometry only - no attribute fields
fm = arcsmith.flds.build_field_map(input_fc, [])

# Pass directly to an arcpy export tool
fm = arcsmith.flds.build_field_map(input_fc, ["NAME", "STATUS"])
arcpy.conversion.FeatureClassToFeatureClass(input_fc, out_gdb, "output", field_mapping=fm)

# Or use copy_w_fields as a shorthand for the same operation
arcsmith.fc.copy_w_fields(input_fc, "path/to/out.gdb/output", ["NAME", "STATUS"])

clean_blanks

Standardizes blank-like values in a text field to a single canonical value. Edits in-place by default, or writes to a new feature class if output_fc is provided.

clean_blanks(input_fc, fields, blank_value="N/A", output_fc=None)
Parameter Type Default Description
input_fc str or Path required Path to the source feature class.
fields str or list of str required Text field name(s) to clean. A single name may be passed without a list.
blank_value str "N/A" The canonical replacement for blank-like cells. Default "N/A".
output_fc str or Path None If provided, input_fc is copied to this path and cleaning is performed on the copy. input_fc is left unchanged. Default None (edits input_fc in-place).

Returns

dict of str to int: maps each cleaned field name to the number of cells that were replaced. Fields that were skipped (non-string type) are not included.

Raises

ValueError if any name in fields does not exist in input_fc.

What counts as blank

A cell is replaced if it is None / SQL NULL, an empty string "", a whitespace-only string, or a case-insensitive match (after stripping whitespace) for any of: "N/A", "NA", "None", "Null", "Nil", "-", "--", "---".

Non-string fields

Any field in fields whose type is not String is skipped with an arcpy.AddWarning and is not included in the returned counts.

Examples

# Clean a single field in-place
counts = arcsmith.flds.clean_blanks(input_fc, "STATUS")
# {"STATUS": 12}

# Clean a copy, leaving the original unchanged
counts = arcsmith.flds.clean_blanks(
    input_fc, "STATUS", output_fc="C:/data/results.gdb/cleaned"
)

# Clean multiple fields with a custom replacement
counts = arcsmith.flds.clean_blanks(
    input_fc, ["STATUS", "NOTES", "CATEGORY"],
    blank_value="Unknown",
    output_fc="C:/data/results.gdb/cleaned",
)

# Report how many cells were standardized
for field, n in counts.items():
    arcpy.AddMessage(f"{field}: {n} blank(s) replaced")

list_cols

Returns the field names present in a feature class. System-managed fields are excluded by default.

list_cols(input_fc, include_system=False)
Parameter Type Default Description
input_fc str or Path required Path to the source feature class.
include_system bool False If False (default), system-managed fields (OID, Shape, Shape_Length, Shape_Area, GlobalID) are excluded. If True, all fields are returned.

Returns

list of str: field names in the order arcpy reports them.

Examples

# List user-defined fields
arcsmith.flds.list_cols(input_fc)
# ['PARCEL_ID', 'OWNER', 'STATUS', 'AREA_SQFT']

# Include system fields
arcsmith.flds.list_cols(input_fc, include_system=True)
# ['OBJECTID', 'Shape', 'PARCEL_ID', 'OWNER', 'STATUS', 'AREA_SQFT', 'Shape_Length', 'Shape_Area']

# Feed directly into a dropdown
arcsmith.param.drop_populate(parameters[1], arcsmith.flds.list_cols(parameters[0].valueAsText))

unique_values

Returns the unique values present in a single field, or the unique value combinations present across multiple fields.

unique_values(input_fc, fields, sort=True)
Parameter Type Default Description
input_fc str or Path required Path to the source feature class.
fields str or list of str required Field name(s) to inspect. A single string for one field; a list for multi-field combinations. Field names are matched case-insensitively.
sort bool True If True, the result is sorted: values directly for a single field, lexicographically for tuples. None sorts before all other values in every position. Set False to preserve first-encountered order.

Returns

Single field: list of distinct values (any type). Multiple fields: list of tuple, one per unique combination, aligned to the order of fields.

Raises

ValueError if any name in fields does not exist in input_fc.

None handling

SQL NULL is included as a distinct value when present in the data. With sort=True, None sorts before all other values in every position.

Examples

Unique values from a single field

arcsmith.flds.unique_values(input_fc, "STATUS")

['Active', 'Inactive', 'Pending']

Unique combinations across two fields

arcsmith.flds.unique_values(input_fc, ["STATE", "COUNTY"])

[('CA', 'Alameda'), ('CA', 'Marin'), ('TX', 'Harris')]

Preserve insertion order instead of sorting

arcsmith.flds.unique_values(input_fc, "STATUS", sort=False)

Feed directly into a parameter dropdown.

None entries and non-strings are handled automatically by drop_populate.

values = arcsmith.flds.unique_values(input_fc, "CATEGORY") arcsmith.param.drop_populate(parameters[1], values)