SimpleArrayField

This class provides a form field for handling arrays of data represented as a single delimited string. It wraps a base field to handle the validation and conversion of individual array elements while supporting configurable delimiters and length constraints. The field automatically manages the transformation between comma-separated input and Python list objects.

Attributes

Attribute	Type	Description
default_error_messages	dict = {"item_invalid": _("Item %(nth)s in the array did not validate:")}	A dictionary containing the default error message for the 'item_invalid' key, used to prefix validation errors for specific items within the array.

---

Constructor

Signature

def SimpleArrayField(
    base_field: [Field](../../../../forms/fields/field.md?sid=django_forms_fields_field),
    delimiter: string = ,,
    max_length: integer = None,
    min_length: integer = None,
    **kwargs: dict
)

Parameters

Name	Type	Description
base_field	[Field](../../../../forms/fields/field.md?sid=django_forms_fields_field)	The Django form field class used to validate each item in the array.
delimiter	string = ,	The character used to separate values in the input string.
max_length	integer = None	Optional maximum number of items allowed in the array.
min_length	integer = None	Optional minimum number of items required in the array.
**kwargs	dict	Additional keyword arguments passed to the parent CharField constructor.

---

Methods

---

clean()

@classmethod
def clean(
    value: any
) - > list

Validates the given value and returns its clean Pythonic representation. It processes the input through the base field's cleaning logic for each item in the array.

Parameters

Name	Type	Description
value	any	The raw input value to be cleaned and validated.

Returns

Type	Description
list	A list of cleaned values processed by the underlying base field.

---

prepare_value()

@classmethod
def prepare_value(
    value: list|any
) - > string

Converts the Python list back into a delimited string representation suitable for display in a form widget.

Parameters

Name	Type	Description
value	`list	any`

Returns

Type	Description
string	A string of values joined by the configured delimiter, or the original value if it is not a list.

---

to_python()

@classmethod
def to_python(
    value: string|list
) - > list

Parses the delimited string input into a list of Python objects, invoking the base field's to_python method for each element.

Parameters

Name	Type	Description
value	`string	list`

Returns

Type	Description
list	A list of Python objects converted from the raw input string.

---

validate()

@classmethod
def validate(
    value: list
)

Performs validation on each individual item in the array using the base field's validation logic.

Parameters

Name	Type	Description
value	list	The list of items to validate against the base field's constraints.

---

run_validators()

@classmethod
def run_validators(
    value: list
)

Executes all registered validators on the array as a whole and on each individual element within the array.

Parameters

Name	Type	Description
value	list	The list of items to be checked by the field and item-level validators.

---

has_changed()

@classmethod
def has_changed(
    initial: any,
    data: any
) - > boolean

Determines if the field's value has changed from the initial data, accounting for empty values and potential validation errors during conversion.

Parameters

Name	Type	Description
initial	any	The original value of the field before user modification.
data	any	The new data submitted via the form to compare against the initial value.

Returns

Type	Description
boolean	True if the data differs from the initial value, False otherwise.

---