google.appengine.ext.db.djangoforms module


Support for creating Django (new) forms from Datastore data models.

This is our best shot at supporting as much of Django as possible: you won’t be able to use Django’s db package, but you can use our db package instead, and create Django forms from it, either fully automatically, or with overrides.

Note, you should not import these classes from this module. Importing this module patches the classes in place, and you should continue to import them from google.appengine.db.

Some of the code here is strongly inspired by Django’s own ModelForm class (new in Django 0.97). Our code also supports Django 0.96 (so as to be maximally compatible). Note that our API is always similar to Django 0.97’s API, even when used with Django 0.96 (which uses a different API, chiefly form_for_model()).

Terminology notes:
  • forms: always refers to the Django newforms subpackage

  • field: always refers to a Django forms.Field instance

  • property: always refers to a db.Property instance

Mapping between properties and fields:

+====================+===================+==============+====================+ | Property subclass | Field subclass | datatype | widget; notes | +====================+===================+==============+====================+ | StringProperty | CharField | unicode | Textarea | | | | | if multiline | +——————–+——————-+————–+——————–+ | TextProperty | CharField | unicode | Textarea | +——————–+——————-+————–+——————–+ | BlobProperty | FileField | str | skipped in v0.96 | +——————–+——————-+————–+——————–+ | DateTimeProperty | DateTimeField | datetime | skipped | | | | | if auto_now[_add] | +——————–+——————-+————–+——————–+ | DateProperty | DateField | date | ditto | +——————–+——————-+————–+——————–+ | TimeProperty | TimeField | time | ditto | +——————–+——————-+————–+——————–+ | IntegerProperty | IntegerField | int or long | | +——————–+——————-+————–+——————–+ | FloatProperty | FloatField | float | CharField in v0.96 | +——————–+——————-+————–+——————–+ | BooleanProperty | BooleanField | bool | | +——————–+——————-+————–+——————–+ | UserProperty | CharField | users.User | | +——————–+——————-+————–+——————–+ | StringListProperty | CharField | list of str | Textarea | +——————–+——————-+————–+——————–+ | LinkProperty | URLField | str | | +——————–+——————-+————–+——————–+ | ReferenceProperty | ModelChoiceField* | db.Model | | +——————–+——————-+————–+——————–+ | _ReverseReferenceP.| None | <iterable> | always skipped | +====================+===================+==============+====================+

Notes: *: this Field subclasses is defined by us, not in Django.


class google.appengine.ext.db.djangoforms.BaseModelForm(data=None, files=None, auto_id=None, prefix=None, initial=None, error_class=None, label_suffix=None, instance=None)source

Bases: django.forms.forms.BaseForm

Base class for ModelForm.

This overrides the forms.BaseForm constructor and adds a save() method.

This class does not have a special metaclass; the magic metaclass is added by the subclass ModelForm.


Save this form’s cleaned data into a model instance.


commit – optional bool, default True; if true, the model instance is also saved to the datastore.


A model instance. If a model instance was already associated with this form instance (either passed to the constructor with instance=… or by a previous save() call), that same instance is updated and returned; if no instance was associated yet, one is created by this call.


ValueError if the data couldn’t be validated.

class google.appengine.ext.db.djangoforms.ModelChoiceField(reference_class, query=None, choices=None, empty_label=u'---------', required=True, widget=django.forms.widgets.Select, label=None, initial=None, help_text=None, *args, **kwargs)source

Bases: django.forms.fields.Field


Getter for the choices attribute.

This is required to return an object that can be iterated over multiple times.


Override Field.clean() to do reference-specific value cleaning.

This turns a non-empty value into a model instance.

default_error_messages = {'invalid_choice': <django.utils.functional.__proxy__ object>}

Getter for the query attribute.

class google.appengine.ext.db.djangoforms.ModelForm(data=None, files=None, auto_id=None, prefix=None, initial=None, error_class=None, label_suffix=None, instance=None)source

Bases: google.appengine.ext.db.djangoforms.BaseModelForm

A Django form tied to a Datastore model.

Note that this particular class just sets the metaclass; all other functionality is defined in the base class, BaseModelForm, above.

Usage example:

from google.appengine.ext import db from google.appengine.ext.db import djangoforms

# First, define a model class class MyModel(db.Model):

foo = db.StringProperty() bar = db.IntegerProperty(required=True, default=42)

# Now define a form class class MyForm(djangoforms.ModelForm):

class Meta:

model = MyModel

You can now instantiate MyForm without arguments to create an unbound form, or with data from a POST request to create a bound form. You can also pass a model instance with the instance=… keyword argument to create an unbound (!) form whose initial values are taken from the instance. For bound forms, use the save() method to return a model instance.

Like Django’s own corresponding ModelForm class, the nested Meta class can have two other attributes:

fields: if present and non-empty, a list of field names to be

included in the form; properties not listed here are excluded from the form

exclude: if present and non-empty, a list of field names to be

excluded from the form

If exclude and fields are both non-empty, names occurring in both are excluded (i.e. exclude wins). By default all property in the model have a corresponding form field defined.

It is also possible to define form fields explicitly. This gives more control over the widget used, constraints, initial value, and so on. Such form fields are not affected by the nested Meta class’s fields and exclude attributes.

If you define a form field named ‘key_name’ it will be treated specially and will be used as the value for the key_name parameter to the Model constructor. This allows you to create instances with named keys. The ‘key_name’ field will be ignored when updating an instance (although it will still be shown on the form).

base_fields = {}
class google.appengine.ext.db.djangoforms.ModelFormMetaclasssource

Bases: type

The metaclass for the ModelForm class defined below.

This is our analog of Django’s own ModelFormMetaclass. (We can’t conveniently subclass that class because there are quite a few differences.)

See the docs for ModelForm below for a usage example.

class google.appengine.ext.db.djangoforms.ModelFormOptions(options=None)source

Bases: object

A simple class to hold internal options for a ModelForm class.

Instance attributes:

model: a db.Model class, or None fields: list of field names to be defined, or None exclude: list of field names to be skipped, or None

These instance attributes are copied from the ‘Meta’ class that is usually present in a ModelForm class, and all default to None.

google.appengine.ext.db.djangoforms.monkey_patch(name, bases, namespace)source

A ‘metaclass’ for adding new methods to an existing class.

This shouldn’t be used to override existing methods. However, because loading this module (like loading any module) should be idempotent, we don’t assert that.

Usage example:

class PatchClass(TargetClass):

__metaclass__ = monkey_patch def foo(self, …): … def bar(self, …): …

This is equivalent to:

def foo(self, …): … def bar(self, …): … = foo = bar PatchClass = TargetClass

Note that PatchClass becomes an alias for TargetClass; by convention it is recommended to give PatchClass the same name as TargetClass.

google.appengine.ext.db.djangoforms.property_clean(prop, value)source

Apply Property level validation to value.

Calls .make_value_from_form() and .validate() on the property and catches exceptions generated by either. The exceptions are converted to forms.ValidationError exceptions.

  • prop – The property to validate against.

  • value – The value to validate.


forms.ValidationError if the value cannot be validated.

Was this page helpful? Let us know how we did:

Send feedback about...

App Engine standard environment for Python