#!/usr/bin/env python
#
# Copyright 2007 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

"""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.
"""



import itertools
import logging


import django.core.exceptions
import django.utils.datastructures

try:
  from django import newforms as forms
except ImportError:
  from django import forms

try:
  from django.utils.translation import ugettext_lazy as _
except ImportError:
  pass

from google.appengine.api import users
from google.appengine.ext import db




def monkey_patch(name, bases, namespace):
  """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, ...): ...
    TargetClass.foo = foo
    TargetClass.bar = bar
    PatchClass = TargetClass

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

  assert len(bases) == 1, 'Exactly one base class is required'
  base = bases[0]
  for name, value in namespace.iteritems():
    if name not in ('__metaclass__', '__module__'):
      setattr(base, name, value)
  return base




class Property(db.Property):
  __metaclass__ = monkey_patch

  def get_form_field(self, form_class=forms.CharField, **kwargs):
    """Return a Django form field appropriate for this property.

    Args:
      form_class: a forms.Field subclass, default forms.CharField

    Additional keyword arguments are passed to the form_class constructor,
    with certain defaults:
      required: self.required
      label: prettified self.verbose_name, if not None
      widget: a forms.Select instance if self.choices is non-empty
      initial: self.default, if not None

    Returns:
       A fully configured instance of form_class, or None if no form
       field should be generated for this property.
    """
    defaults = {'required': self.required}
    if self.verbose_name:
      defaults['label'] = self.verbose_name.capitalize().replace('_', ' ')
    if self.choices:
      choices = []
      if not self.required or (self.default is None and
                               'initial' not in kwargs):
        choices.append(('', '---------'))
      for choice in self.choices:
        choices.append((str(choice), unicode(choice)))
      defaults['widget'] = forms.Select(choices=choices)
    if self.default is not None:
      defaults['initial'] = self.default
    defaults.update(kwargs)
    return form_class(**defaults)

  def get_value_for_form(self, instance):
    """Extract the property value from the instance for use in a form.

    Override this to do a property- or field-specific type conversion.

    Args:
      instance: a db.Model instance

    Returns:
      The property's value extracted from the instance, possibly
      converted to a type suitable for a form field; possibly None.

    By default this returns the instance attribute's value unchanged.
    """
    return getattr(instance, self.name)

  def make_value_from_form(self, value):
    """Convert a form value to a property value.

    Override this to do a property- or field-specific type conversion.

    Args:
      value: the cleaned value retrieved from the form field

    Returns:
      A value suitable for assignment to a model instance's property;
      possibly None.

    By default this converts the value to self.data_type if it
    isn't already an instance of that type, except if the value is
    empty, in which case we return None.
    """
    if value in (None, ''):
      return None
    if not isinstance(value, self.data_type):
      value = self.data_type(value)
    return value


class UserProperty(db.Property):
  """This class exists solely to log a warning when it is used."""

  def __init__(self, *args, **kwds):
    logging.warn("Please don't use modelforms.UserProperty; "
                 "use db.UserProperty instead.")
    super(UserProperty, self).__init__(*args, **kwds)


class StringProperty(db.StringProperty):
  __metaclass__ = monkey_patch

  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for a string property.

    This sets the widget default to forms.Textarea if the property's
    multiline attribute is set.
    """
    defaults = {}
    if self.multiline:
      defaults['widget'] = forms.Textarea
    defaults.update(kwargs)
    return super(StringProperty, self).get_form_field(**defaults)


class TextProperty(db.TextProperty):
  __metaclass__ = monkey_patch

  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for a text property.

    This sets the widget default to forms.Textarea.
    """
    defaults = {'widget': forms.Textarea}
    defaults.update(kwargs)
    return super(TextProperty, self).get_form_field(**defaults)


class BlobProperty(db.BlobProperty):
  __metaclass__ = monkey_patch

  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for a blob property.

    This defaults to a forms.FileField instance when using Django 0.97
    or later.  For 0.96 this returns None, as file uploads are not
    really supported in that version.
    """
    if not hasattr(forms, 'FileField'):
      return None
    defaults = {'form_class': forms.FileField}
    defaults.update(kwargs)
    return super(BlobProperty, self).get_form_field(**defaults)

  def get_value_for_form(self, instance):
    """Extract the property value from the instance for use in a form.

    There is no way to convert a Blob into an initial value for a file
    upload, so we always return None.
    """
    return None

  def make_value_from_form(self, value):
    """Convert a form value to a property value.

    This extracts the content from the UploadedFile instance returned
    by the FileField instance.
    """
    if value.__class__.__name__ == 'UploadedFile':
      return db.Blob(value.content)
    return super(BlobProperty, self).make_value_from_form(value)


class DateTimeProperty(db.DateTimeProperty):
  __metaclass__ = monkey_patch

  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for a date-time property.

    This defaults to a DateTimeField instance, except if auto_now or
    auto_now_add is set, in which case None is returned, as such
    'auto' fields should not be rendered as part of the form.
    """
    if self.auto_now or self.auto_now_add:
      return None
    defaults = {'form_class': forms.DateTimeField}
    defaults.update(kwargs)
    return super(DateTimeProperty, self).get_form_field(**defaults)


class DateProperty(db.DateProperty):
  __metaclass__ = monkey_patch

  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for a date property.

    This defaults to a DateField instance, except if auto_now or
    auto_now_add is set, in which case None is returned, as such
    'auto' fields should not be rendered as part of the form.
    """
    if self.auto_now or self.auto_now_add:
      return None
    defaults = {'form_class': forms.DateField}
    defaults.update(kwargs)
    return super(DateProperty, self).get_form_field(**defaults)


class TimeProperty(db.TimeProperty):
  __metaclass__ = monkey_patch

  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for a time property.

    This defaults to a TimeField instance, except if auto_now or
    auto_now_add is set, in which case None is returned, as such
    'auto' fields should not be rendered as part of the form.
    """
    if self.auto_now or self.auto_now_add:
      return None
    defaults = {'form_class': forms.TimeField}
    defaults.update(kwargs)
    return super(TimeProperty, self).get_form_field(**defaults)


class IntegerProperty(db.IntegerProperty):
  __metaclass__ = monkey_patch

  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for an integer property.

    This defaults to an IntegerField instance.
    """
    defaults = {'form_class': forms.IntegerField}
    defaults.update(kwargs)
    return super(IntegerProperty, self).get_form_field(**defaults)


class FloatProperty(db.FloatProperty):
  __metaclass__ = monkey_patch

  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for an integer property.

    This defaults to a FloatField instance when using Django 0.97 or
    later.  For 0.96 this defaults to the CharField class.
    """
    defaults = {}
    if hasattr(forms, 'FloatField'):
      defaults['form_class'] = forms.FloatField
    defaults.update(kwargs)
    return super(FloatProperty, self).get_form_field(**defaults)


class BooleanProperty(db.BooleanProperty):
  __metaclass__ = monkey_patch

  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for a boolean property.

    This defaults to a BooleanField.
    """
    defaults = {'form_class': forms.BooleanField}
    defaults.update(kwargs)
    return super(BooleanProperty, self).get_form_field(**defaults)

  def make_value_from_form(self, value):
    """Convert a form value to a property value.

    This is needed to ensure that False is not replaced with None.
    """
    if value is None:
      return None
    if isinstance(value, basestring) and value.lower() == 'false':
      return False
    return bool(value)


class StringListProperty(db.StringListProperty):
  __metaclass__ = monkey_patch


  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for a StringList property.

    This defaults to a Textarea widget with a blank initial value.
    """
    defaults = {'widget': forms.Textarea,
                'initial': ''}
    defaults.update(kwargs)
    return super(StringListProperty, self).get_form_field(**defaults)

  def get_value_for_form(self, instance):
    """Extract the property value from the instance for use in a form.

    This joins a list of strings with newlines.
    """
    value = super(StringListProperty, self).get_value_for_form(instance)
    if not value:
      return None
    if isinstance(value, list):
      value = '\n'.join(value)
    return value

  def make_value_from_form(self, value):
    """Convert a form value to a property value.

    This breaks the string into lines.
    """
    if not value:
      return []
    if isinstance(value, basestring):
      value = value.splitlines()
    return value


class LinkProperty(db.LinkProperty):
  __metaclass__ = monkey_patch

  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for a URL property.

    This defaults to a URLField instance.
    """
    defaults = {'form_class': forms.URLField}
    defaults.update(kwargs)
    return super(LinkProperty, self).get_form_field(**defaults)


class _WrapIter(object):
  """Helper class whose iter() calls a given function to get an iterator."""

  def __init__(self, function):
    self._function = function

  def __iter__(self):
    return self._function()


class ModelChoiceField(forms.Field):

  default_error_messages = {
      'invalid_choice': _(u'Please select a valid choice. '
                          u'That choice is not one of the available choices.'),
    }

  def __init__(self, reference_class, query=None, choices=None,
               empty_label=u'---------',
               required=True, widget=forms.Select, label=None, initial=None,
               help_text=None, *args, **kwargs):
    """Constructor.

    Args:
      reference_class: required; the db.Model subclass used in the reference
      query: optional db.Query; default db.Query(reference_class)
      choices: optional explicit list of (value, label) pairs representing
        available choices; defaults to dynamically iterating over the
        query argument (or its default)
      empty_label: label to be used for the default selection item in
        the widget; this is prepended to the choices
      required, widget, label, initial, help_text, *args, **kwargs:
        like for forms.Field.__init__(); widget defaults to forms.Select
    """
    assert issubclass(reference_class, db.Model)
    if query is None:
      query = db.Query(reference_class)
    assert isinstance(query, db.Query)
    super(ModelChoiceField, self).__init__(required, widget, label, initial,
                                           help_text, *args, **kwargs)
    self.empty_label = empty_label
    self.reference_class = reference_class
    self._query = query
    self._choices = choices
    self._update_widget_choices()

  def _update_widget_choices(self):
    """Helper to copy the choices to the widget."""
    self.widget.choices = self.choices


  def _get_query(self):
    """Getter for the query attribute."""
    return self._query

  def _set_query(self, query):
    """Setter for the query attribute.

    As a side effect, the widget's choices are updated.
    """
    self._query = query
    self._update_widget_choices()

  query = property(_get_query, _set_query)

  def _generate_choices(self):
    """Generator yielding (key, label) pairs from the query results."""
    yield ('', self.empty_label)
    for inst in self._query:
      yield (inst.key(), unicode(inst))


  def _get_choices(self):
    """Getter for the choices attribute.

    This is required to return an object that can be iterated over
    multiple times.
    """
    if self._choices is not None:
      return self._choices
    return _WrapIter(self._generate_choices)

  def _set_choices(self, choices):
    """Setter for the choices attribute.

    As a side effect, the widget's choices are updated.
    """
    self._choices = choices
    self._update_widget_choices()

  choices = property(_get_choices, _set_choices)

  def clean(self, value):
    """Override Field.clean() to do reference-specific value cleaning.

    This turns a non-empty value into a model instance.
    """
    value = super(ModelChoiceField, self).clean(value)
    if not value:
      return None
    instance = db.get(value)
    if instance is None:
      raise db.BadValueError(self.error_messages['invalid_choice'])
    return instance


class ReferenceProperty(db.ReferenceProperty):
  __metaclass__ = monkey_patch

  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for a reference property.

    This defaults to a ModelChoiceField instance.
    """
    defaults = {'form_class': ModelChoiceField,
                'reference_class': self.reference_class}
    defaults.update(kwargs)
    return super(ReferenceProperty, self).get_form_field(**defaults)

  def get_value_for_form(self, instance):
    """Extract the property value from the instance for use in a form.

    This return the key object for the referenced object, or None.
    """
    value = super(ReferenceProperty, self).get_value_for_form(instance)
    if value is not None:
      value = value.key()
    return value

  def make_value_from_form(self, value):
    """Convert a form value to a property value.

    This turns a key string or object into a model instance.
    """
    if value:
      if not isinstance(value, db.Model):
        value = db.get(value)
    return value


class _ReverseReferenceProperty(db._ReverseReferenceProperty):
  __metaclass__ = monkey_patch

  def get_form_field(self, **kwargs):
    """Return a Django form field appropriate for a reverse reference.

    This always returns None, since reverse references are always
    automatic.
    """
    return None


def property_clean(prop, value):
  """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.

  Args:
    prop: The property to validate against.
    value: The value to validate.

  Raises:
    forms.ValidationError if the value cannot be validated.
  """
  if value is not None:
    try:
      prop.validate(prop.make_value_from_form(value))
    except (db.BadValueError, ValueError), e:
      raise forms.ValidationError(unicode(e))


class ModelFormOptions(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.
  """


  def __init__(self, options=None):
    self.model = getattr(options, 'model', None)
    self.fields = getattr(options, 'fields', None)
    self.exclude = getattr(options, 'exclude', None)


class ModelFormMetaclass(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.
  """

  def __new__(cls, class_name, bases, attrs):
    """Constructor for a new ModelForm class instance.

    The signature of this method is determined by Python internals.

    All Django Field instances are removed from attrs and added to
    the base_fields attribute instead.  Additional Field instances
    are added to this based on the Datastore Model class specified
    by the Meta attribute.
    """
    fields = sorted(((field_name, attrs.pop(field_name))
                     for field_name, obj in attrs.items()
                     if isinstance(obj, forms.Field)),
                    key=lambda obj: obj[1].creation_counter)
    for base in bases[::-1]:
      if hasattr(base, 'base_fields'):
        fields = base.base_fields.items() + fields
    declared_fields = django.utils.datastructures.SortedDict()
    for field_name, obj in fields:
      declared_fields[field_name] = obj

    opts = ModelFormOptions(attrs.get('Meta', None))
    attrs['_meta'] = opts

    base_models = []
    for base in bases:
      base_opts = getattr(base, '_meta', None)
      base_model = getattr(base_opts, 'model', None)
      if base_model is not None:
        base_models.append(base_model)
    if len(base_models) > 1:
      raise django.core.exceptions.ImproperlyConfigured(
          "%s's base classes define more than one model." % class_name)

    if opts.model is not None:
      if base_models and base_models[0] is not opts.model:
        raise django.core.exceptions.ImproperlyConfigured(
            '%s defines a different model than its parent.' % class_name)

      model_fields = django.utils.datastructures.SortedDict()
      for name, prop in sorted(opts.model.properties().iteritems(),
                               key=lambda prop: prop[1].creation_counter):
        if opts.fields and name not in opts.fields:
          continue
        if opts.exclude and name in opts.exclude:
          continue
        form_field = prop.get_form_field()
        if form_field is not None:
          model_fields[name] = form_field

      model_fields.update(declared_fields)
      attrs['base_fields'] = model_fields

      props = opts.model.properties()
      for name, field in model_fields.iteritems():
        prop = props.get(name)
        if prop:
          def clean_for_property_field(value, prop=prop, old_clean=field.clean):
            value = old_clean(value)
            property_clean(prop, value)
            return value
          field.clean = clean_for_property_field
    else:
      attrs['base_fields'] = declared_fields

    return super(ModelFormMetaclass, cls).__new__(cls,
                                                  class_name, bases, attrs)


class BaseModelForm(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.
  """

  def __init__(self, data=None, files=None, auto_id=None, prefix=None,
               initial=None, error_class=None, label_suffix=None,
               instance=None):
    """Constructor.

    Args (all optional and defaulting to None):
      data: dict of data values, typically from a POST request)
      files: dict of file upload values; Django 0.97 or later only
      auto_id, prefix: see Django documentation
      initial: dict of initial values
      error_class, label_suffix: see Django 0.97 or later documentation
      instance: Model instance to be used for additional initial values

    Except for initial and instance, these arguments are passed on to
    the forms.BaseForm constructor unchanged, but only if not None.
    Some arguments (files, error_class, label_suffix) are only
    supported by Django 0.97 or later.  Leave these blank (i.e. None)
    when using Django 0.96.  Their default values will be used with
    Django 0.97 or later even when they are explicitly set to None.
    """
    opts = self._meta
    self.instance = instance
    object_data = {}
    if instance is not None:
      for name, prop in instance.properties().iteritems():
        if opts.fields and name not in opts.fields:
          continue
        if opts.exclude and name in opts.exclude:
          continue
        object_data[name] = prop.get_value_for_form(instance)
    if initial is not None:
      object_data.update(initial)
    kwargs = dict(data=data, files=files, auto_id=auto_id,
                  prefix=prefix, initial=object_data,
                  error_class=error_class, label_suffix=label_suffix)
    kwargs = dict((name, value)
                  for name, value in kwargs.iteritems()
                  if value is not None)
    super(BaseModelForm, self).__init__(**kwargs)

  def save(self, commit=True):
    """Save this form's cleaned data into a model instance.

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

    Returns:
      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.

    Raises:
      ValueError if the data couldn't be validated.
    """
    if not self.is_bound:
      raise ValueError('Cannot save an unbound form')
    opts = self._meta
    instance = self.instance
    if instance is None:
      fail_message = 'created'
    else:
      fail_message = 'updated'
    if self.errors:
      raise ValueError("The %s could not be %s because the data didn't "
                       'validate.' % (opts.model.kind(), fail_message))
    cleaned_data = self._cleaned_data()
    converted_data = {}
    propiter = itertools.chain(
      opts.model.properties().iteritems(),
      iter([('key_name', StringProperty(name='key_name'))])
      )
    for name, prop in propiter:
      value = cleaned_data.get(name)
      if value is not None:
        converted_data[name] = prop.make_value_from_form(value)
    try:
      if instance is None:
        instance = opts.model(**converted_data)
        self.instance = instance
      else:
        for name, value in converted_data.iteritems():
          if name == 'key_name':
            continue
          setattr(instance, name, value)
    except db.BadValueError, err:
      raise ValueError('The %s could not be %s (%s)' %
                       (opts.model.kind(), fail_message, err))
    if commit:
      instance.put()
    return instance

  def _cleaned_data(self):
    """Helper to retrieve the cleaned data attribute.

    In Django 0.96 this attribute was called self.clean_data.  In 0.97
    and later it's been renamed to self.cleaned_data, to avoid a name
    conflict.  This helper abstracts the difference between the
    versions away from its caller.
    """
    try:
      return self.cleaned_data
    except AttributeError:
      return self.clean_data


class ModelForm(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).
  """

  __metaclass__ = ModelFormMetaclass