API Documentation

This part of the documentation covers all the public classes and functions in WTForms-Alchemy.


class wtforms_alchemy.ModelForm(*args, **kwargs)

Standard base-class for all forms to be combined with a model. Use model_form_factory() in case you wish to change its behavior.

get_session: If you want to use the Unique validator, you should define this method. If you are using Flask-SQLAlchemy along with WTForms-Alchemy you don’t need to set this. If you define this in the superclass, it will not be overriden.

class Meta
wtforms_alchemy.model_form_factory(base=<class 'wtforms.form.Form'>, meta=<class 'wtforms_alchemy.ModelFormMeta'>, **defaults)[source]

Create a base class for all model forms to derive from.

  • base – Class that should be used as a base for the returned class. By default, this is WTForms’s base class wtforms.Form.
  • meta – A metaclass to use on this class. Normally, you do not need to provide this value, but if you want, you should check out model_form_meta_factory().

A class to be used as the base class for all forms that should be connected to a SQLAlchemy model class.

Additional arguments provided to the form override the default configuration as described in Custom form base class.

class wtforms_alchemy.ModelFormMeta(*args, **kwargs)

Meta class that overrides WTForms base meta class. The primary purpose of this class is allowing ModelForms use special configuration params under the ‘Meta’ class namespace.

ModelForm classes inherit parent’s Meta class properties.

wtforms_alchemy.model_form_meta_factory(base=<class 'wtforms.form.FormMeta'>)[source]

Create a new class usable as a metaclass for the model_form_factory(). You only need to concern yourself with this if you desire to have a custom metclass. Otherwise, a default class is created and is used as a metaclass on model_form_factory().

Parameters:base – The base class to use for the meta class. This is an optional parameter that defaults to FormMeta. If you want to provide your own, your class must derive from this class and not directly from type.
Returns:A new class suitable as a metaclass for the actual model form. Therefore, it should be passed as the meta argument to model_form_factory().

Example usage:

from wtforms.form import FormMeta

class MyModelFormMeta(FormMeta):
    # do some metaclass magic here

ModelFormMeta = model_form_meta_factory(MyModelFormMeta)
ModelForm = model_form_factory(meta=ModelFormMeta)


class wtforms_alchemy.generator.FormGenerator(form_class)[source]

Base form generator, you can make your own form generators by inheriting this class.

additional_validators(key, column)[source]

Returns additional validators for given column

  • key – String key of the column property
  • column – SQLAlchemy Column object

Returns coerce callable for given column

Parameters:column – SQLAlchemy Column object
create_field(prop, column)[source]

Create form field for given column.

  • prop – SQLAlchemy ColumnProperty object.
  • column – SQLAlchemy Column object.
create_fields(form, properties)[source]

Creates fields for given form based on given model attributes.

  • form – form to attach the generated fields into
  • attributes – model attributes to generate the form fields from

Creates the form.

Parameters:form – ModelForm instance
create_validators(prop, column)[source]

Returns validators for given column

Parameters:column – SQLAlchemy Column object

Returns date format for given column.

Parameters:column – SQLAlchemy Column object

Return field default for given column.

Parameters:column – SQLAlchemy Column object

Filter set of model attributes based on only, exclude and include meta parameters.

Parameters:attrs – Set of attributes

Return filters for given column.

Parameters:column – SQLAlchemy Column object

Returns WTForms field class. Class is based on a custom field class attribute or SQLAlchemy column type.

Parameters:column – SQLAlchemy Column object

Whether or not given column has an index.

Parameters:column – Column object to inspect the indexes from

Returns length validator for given column

Parameters:column – SQLAlchemy Column object

Returns range validator based on column type and column info min and max arguments

Parameters:column – SQLAlchemy Column object

Returns required / optional validator for given column based on column nullability and form configuration.

Parameters:column – SQLAlchemy Column object

Returns HTML5 compatible step attribute for given decimal scale.

Parameters:scale – an integer that defines a Numeric column’s scale

Returns key value args for SelectField based on SQLAlchemy column definitions.

Parameters:column – SQLAlchemy Column object

Whether or not to skip column in the generation process.

Parameters:column_property – SQLAlchemy Column object

Whether or not to skip column property in the generation process.

Parameters:column_property – SQLAlchemy ColumnProperty object
type_agnostic_parameters(key, column)[source]

Returns all type agnostic form field parameters for given column.

Parameters:column – SQLAlchemy Column object

Returns type specific parameters for given column.

Parameters:column – SQLAlchemy Column object
unique_validator(key, column)[source]

Returns unique validator for given column if column has a unique index

  • key – String key of the column property
  • column – SQLAlchemy Column object

Finds out whether or not given sqlalchemy model attribute name is valid. Returns attribute property if valid.

Parameters:attr_name – Attribute name

Returns WTForms widget for given column.

Parameters:column – SQLAlchemy Column object


class wtforms_alchemy.fields.QuerySelectField(label=None, validators=None, query_factory=None, get_pk=None, get_label=None, allow_blank=False, blank_text=u'', **kwargs)[source]

Will display a select drop-down field to choose between ORM results in a sqlalchemy Query. The data property actually will store/keep an ORM model instance, not the ID. Submitting a choice which is not in the query will result in a validation error. This field only works for queries on models whose primary key column(s) have a consistent string representation. This means it mostly only works for those composed of string, unicode, and integer types. For the most part, the primary keys will be auto-detected from the model, alternately pass a one-argument callable to get_pk which can return a unique comparable key. The query property on the field can be set from within a view to assign a query per-instance to the field. If the property is not set, the query_factory callable passed to the field constructor will be called to obtain a query. Specify get_label to customize the label associated with each option. If a string, this is the name of an attribute on the model object to use as the label text. If a one-argument callable, this callable will be passed model instance and expected to return the label text. Otherwise, the model object’s __str__ or __unicode__ will be used. If allow_blank is set to True, then a blank choice will be added to the top of the list. Selecting this choice will result in the data property being None. The label for this blank choice can be set by specifying the blank_text parameter.

class wtforms_alchemy.fields.QuerySelectMultipleField(label=None, validators=None, default=None, **kwargs)[source]

Very similar to QuerySelectField with the difference that this will display a multiple select. The data property will hold a list with ORM model instances and will be an empty list when no value is selected. If any of the items in the data list or submitted form data cannot be found in the query, this will result in a validation error.



Return translated attributes for current model class. See SQLAlchemy-i18n package for more information about translatable attributes.

Parameters:model – SQLAlchemy declarative model class
class wtforms_alchemy.utils.ClassMap(items=None)[source]

An ordered dictionary with keys as classes. ClassMap has the following charasteristics:

1. Checking if a key exists not only matches exact classes but also subclasses and objects which are instances of a ClassMap key.

2. Getting an item of ClassMap with a key matches subclasses and instances also.


Checks if given key exists in by first trying to find an exact match. If no exact match is found then this method iterates trhough keys and tries to check if given key is either:

  1. A subclass of one of the keys
  2. An instance of one of the keys

The first check has the time complexity of O(1) whereas the second check has O(n).


class A(object):

class B(object):

class A2(A):

class_map = ClassMap({A: 1, B: 2})
assert B in class_map
assert A in class_map
assert A2 in class_map
assert B() in class_map
assert A() in class_map
assert A2() in class_map

Returns the item matching a key. The key matching has the same charasteristics as __contains__ method.


class A(object):

class B(object):

class A2(A):

class_map = ClassMap({A: 1, B: 2})
assert class_map[B] == 2
assert class_map[A] == 1
assert class_map[A2] == 1
assert class_map[B()] == 2
assert class_map[A()] == 1
assert class_map[A2()] == 1

Initialize an ordered dictionary. The signature is the same as regular dictionaries, but keyword arguments are not recommended because their insertion order is arbitrary.