Reference

ModelQueryField

class modelqueryform.forms.ModelQueryForm(*args, **kwargs)[source]

ModelQueryForm builds a django form that allows complex filtering against a model.

Variables:
  • model (Model) – Model to be filtered
  • include (list) – Field names to be included using the standard orm naming
Raises:

ImproperlyConfigured – If model is missing

_build_form(model, field_prepend=None)[source]

Iterates through model fields to generate modelqueryform fields matching self.include Recursively called to correctly build relationship spanning form fields

Parameters:
  • model (django.db.model) – Current model to inspect. Alwasy starts with self.model
  • field_prepend (str) – Relation field name if using self.traverse
_build_form_field(model_field, name)[source]

Build a form field for a given model field

Parameters:
  • model_field (django.db.models.fields) – field that the resulting form field will filter
  • name (String) – The name for the form field (will match a value in self.include)

They type of FormField built is determined in the following order:

  1. build_FIELD(model_field) (FIELD is the ModelField name)
  2. build_type_FIELD(model_field) (FIELD is the ModelField type .lower() eg. ‘integerfield’, charfield’, etc.)
  3. modelqueryform.utils.get_multiplechoice_field() if model_field has .choices
  4. modelqueryform.utils.get_range_field() if the ModelField type is in self.numeric_fields()
  5. modelqueryform.utils.get_multiplechoice_field() if the ModelField type is in self.choice_fields()
  6. modelqueryform.utils.get_multiplechoice_field() if the ModelField type is in self.rel_fields()

Warning

You must define either build_FIELD(model_field) or build_type_FIELD(model_field) for ModelFields that do not use a RangeField or MultipleChoiceField

Returns:FormField
Raises:NotImplementedError – For fields that do not have a default ModelQueryForm field builder and no custom field builder can be found
_test_filter_func_is_Q(filter_func)[source]

Make sure that a filter is a Q object

Parameters:filter_func (Q) – Object to test
Raises:TypeError – if filter is not a Q object
build_query_from_filters(filters)[source]

Generate a Q object that is a logical AND of a list of Q objects

Note

Override this method to build a more complex Q object than AND(filters.values())

Parameters:filters (dict) – Dict of {Form field name: Q object,...}
Returns Q:AND(filters.values())
Raises:TypeError – if any value in the filters dict is not a Q object
choice_fields()[source]

Get a list of model fields backed by choice values (Boolean types)

Returns list:Model Field types that are backed by a boolean
get_filters()[source]

Get a dict of the POSTed form values as Q objects Form fields will be evaluated in the following order to generate a Q object:

  1. filter_FIELD(field_name, values) (FIELD is the ModelField name)
  2. filter_type_FIELD(field_name, values) (FIELD is the ModelField type .lower() eg. ‘integerfield’, charfield’, etc.)
  3. modelqueryform.utils.get_range_field_filter() if the FormField is a RangeField
  4. modelqueryform.utils.get_multiplechoice_field_filter() if the FormField is a MultipleChoiceField

Warning

You must define either filter_FIELD(field, values) or filter_type_FIELD(field, values) for ModelFields that do not use a RangeField or MultipleChoiceField

Returns Dict:{Form field name: Q object,...}
Raises:NotImplementedError – For fields that do not have a default ModelQueryForm filter builder and no custom filter builder can be found
get_multichoice_field_print(form_field, cleaned_field_data)[source]

Default string representation of multichoice field

Parameters:
  • form_field – FormField
  • cleaned_field_data (dict) – the cleaned_data for the field
Returns str:

Comma delimited get_display_FIELD() for selected choices

get_range_field_print(form_field, cleaned_field_data)[source]

Default string representation of multichoice field

Parameters:
  • form_field – FormField (Unused)
  • cleaned_field_data (dict) – the cleaned_data for the field
Returns str:

“MIN - MAX [(include empty values)]”

Make choices from a related

Parameters:model_field (ForeignKey, OneToOneField, ManyToManyField) – Field to generate choices from
Returns list:[[field.pk, field.__str__()],...]
Raises:TypeError – If model_field is not a relationship type
numeric_fields()[source]

Get a list of model fields backed by numeric values

Returns list:Model Field types that are backed by a numeric
pretty_print_query(fields_to_print=None)[source]

Get an OrderedDict to facilitate printing of generated filter

Parameters:fields_to_print (list) – List of names in changed_data

Note

If fields_to_print == None, self.changed_data is used

Returns dict:

{form field name: string representation of filter,...}

Raises:
  • NotImplementedError – For fields that do not have a default print builder and no custom print builder can be found
  • ValueError – if any name in the field_to_print is not in self.changed_data
process(data_set=None)[source]

Filter a QuerySet with the POSTed form values

Parameters:data_set (QuerySet (Same Model class as self.model)) – QuerySet to filter against

Note

If data_set == None, self.model.objects.all() is used

Returns QuerySet:
 

data_set.filter(Q object)

Raises:
  • ImproperlyConfigured – No data_set to filter
  • TypeErrordata_set is not an instance (using isinstance()) of self.model
rel_fields()[source]

Get a list of related model fields

Returns list:Model Field types that are relationships

RangeField

class modelqueryform.widgets.RangeField(model, field, *args, **kwargs)[source]

RangeWidget

class modelqueryform.widgets.RangeWidget(allow_null=False, attrs=None, mode=0)[source]
Build a MultiWidget with 3 fields:
TextInput with a “min” attribute TextInput with a “max” attribute Checkbox to include/exclude None values

Utils

modelqueryform.utils.get_choices_from_distinct(model, field)[source]

Generate a list of choices from a distinct() call.

Parameters:
  • model (django.db.models.Model) – Model to use
  • field (django Model Field) – Field whose .distinct values you want
Returns:

list – the distinct values of the field in the model

modelqueryform.utils.get_multiplechoice_field(field, choices)[source]

Generate a MultipleChoiceField form element

Parameters:
  • field (django model field) – Model Field to use
  • choices (iterable) – List of choices for form field
Returns:

MultipleChoiceField

Raises:

ValueError

modelqueryform.utils.get_multiplechoice_field_filter(field, values)[source]

Generate a model filter from a POSTed MultipleChoiceField

Parameters:
  • field (string) – orm field name
  • values (list) – Selected values
Returns:

Q – (OR(field: value),...)

modelqueryform.utils.get_range_field(model, field, name)[source]

Generate a RangeField form element

Parameters:
  • model (django.db.models.Model) – Model to generate a form element for
  • field (django model field) – Model Field to use
  • name – Name to use for the form field
  • name – string
Returns:

RangeField

modelqueryform.utils.get_range_field_filter(field, values)[source]

Generate a model filter from a POSTed RangeField

Parameters:
  • field (string) – orm field name
  • values (dict) – RangeField values dict
Returns:

Q – AND(OR(field__gte: min, field__lte: max),(field__isnull: allow_empty)

Given an orm relational representation ‘relational_field__field_name’ and the base model of the relation, return the actual terminal Field