Skip to content

Latest commit

 

History

History
208 lines (139 loc) · 6.81 KB

column_conversion.rst

File metadata and controls

208 lines (139 loc) · 6.81 KB
Raw

Column to form field conversion

Basic type conversion

By default WTForms-Alchemy converts SQLAlchemy model columns using the following type table. So for example if an Unicode column would be converted to TextField.

The reason why so many types here convert to wtforms_components based fields is that wtforms_components provides better HTML5 compatible type handling than WTForms at the moment.

SQAlchemy column type Form field
BigInteger wtforms_components.fields.IntegerField
Boolean BooleanField
Date wtforms_components.fields.DateField
DateTime wtforms_components.fields.DateTimeField
Enum wtforms_components.fields.SelectField
Float FloatField
Integer wtforms_components.fields.IntegerField
Numeric wtforms_components.fields.DecimalField
SmallInteger wtforms_components.fields.IntegerField
String TextField
Text TextAreaField
Time wtforms_components.fields.TimeField
Unicode TextField
UnicodeText TextAreaField

WTForms-Alchemy also supports many types provided by SQLAlchemy-Utils.

SQAlchemy-Utils type Form field
ArrowType wtforms_components.fields.DateTimeField
ChoiceType wtforms_components.fields.SelectField
ColorType wtforms_components.fields.ColorField
CountryType wtforms_alchemy.fields.CountryType
EmailType wtforms_components.fields.EmailField
IPAddressType wtforms_components.fields.IPAddressField
PasswordType wtforms.fields.PasswordField
PhoneNumberType wtforms_components.fields.PhoneNumberField
URLType wtforms_components.fields.StringField + URL validator
UUIDType wtforms.fields.TextField + UUID validator
WeekDaysType wtforms_components.fields.WeekDaysField
SQAlchemy-Utils range type Form field
DateRangeType wtforms_components.fields.DateIntervalField
DateTimeRangeType wtforms_components.fields.DateTimeIntervalField
IntRangeType wtforms_components.fields.IntIntervalField
NumericRangeType wtforms_components.fields.DecimalIntervalField

Excluded fields

By default WTForms-Alchemy excludes a column from the ModelForm if one of the following conditions is True:
  • Column is primary key
  • Column is foreign key
  • Column is DateTime field which has default value (usually this is a generated value)
  • Column is of TSVectorType type
  • Column is set as model inheritance discriminator field

Using include, exclude and only

If you wish the include some of the excluded fields described in the earlier chapter you can use the 'include' configuration parameter.

In the following example we include the field 'author_id' in the ArticleForm (by default it is excluded since it is a foreign key column).

class Article(Base):
    __tablename__ = 'article'

    id = sa.Column(sa.Integer, primary_key=True, nullable=False)
    name = sa.Column(
        sa.Unicode(255),
        nullable=False
    )
    author_id = sa.Column(sa.Integer, sa.ForeignKey(User.id))
    author = sa.orm.relationship(User)


class ArticleForm(Form):
    class Meta:
        include = ['author_id']

If you wish the exclude fields you can either use 'exclude' or 'only' configuration parameters. The recommended way is using only, since in most cases it is desirable to explicitly tell which fields the form should contain.

Consider the following model:

class Article(Base):
    __tablename__ = 'article'

    id = sa.Column(sa.Integer, primary_key=True, nullable=False)
    name = sa.Column(
        sa.Unicode(255),
        nullable=False
    )
    content = sa.Column(
        sa.UnicodeText
    )
    description = sa.Column(
        sa.UnicodeText
    )

Now let's say we want to exclude 'description' from the form. This can be achieved as follows:

class ArticleForm(Form):
    class Meta:
        exclude = ['description']

Or as follows (the recommended way):

class ArticleForm(Form):
    class Meta:
        only = ['name', 'content']

Adding/overriding fields

Example:

from wtforms.fields import TextField, IntegerField
from wtforms.validators import Email

class User(Base):
    __tablename__ = 'user'

    name = sa.Column(sa.Unicode(100), primary_key=True, nullable=False)
    email = sa.Column(
        sa.Unicode(255),
        nullable=False
    )

class UserForm(ModelForm):
    class Meta:
        model = User

    email = TextField(validators=[Optional()])
    age = IntegerField()
Now the UserForm would have three fields:
  • name, a required TextField
  • email, an optional TextField
  • age, IntegerField

Type decorators

WTForms-Alchemy supports SQLAlchemy TypeDecorator based types. When WTForms-Alchemy encounters a TypeDecorator typed column it tries to convert it to underlying type field.

Example:

import sqlalchemy as sa
from wtforms.fields import TextField, IntegerField
from wtforms.validators import Email


class CustomUnicodeType(sa.types.TypeDecorator):
    impl = sa.types.Unicode

class User(Base):
    __tablename__ = 'user'

    id = sa.Column(sa.Integer, primary_key=True, autoincrement=True)
    name = sa.Column(CustomUnicodeType(100), primary_key=True)


class UserForm(ModelForm):
    class Meta:
        model = User

Now the name field of UserForm would be a simple TextField since the underlying type implementation is Unicode.