#!/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.