root/trunk/newforms_extra/multiforms.py @ 99

#!/usr/bin/python
# -*- encoding: utf-8 -*-


import re
import new
from itertools import chain

from django import newforms as forms
from django.db import models
from django.utils.datastructures import MultiValueDict
from django.utils.translation import gettext

from ambidjangolib.newforms_extra.models import save_instance
from ambidjangolib.newforms_extra.forms import Form


class IntegerOrNewField(forms.IntegerField):

    new_re = re.compile('NEW(\d+)$')

    def clean(self, value):
        if self.new_re.match(value):
            return value
        else:
            return super(IntegerOrNewField, self).clean(value)


class MultiForm(Form):
    """
    Many instances of the same model can be shown on and saved from a
    single form.  Corresponding HTML fields on repeated forms have
    equal names, and the ``MultiForm.forms_from_POST()`` method
    creates multiple MultiForm instances based on that data.
    """

    core = {}
    new_prefix = 'NEW'

    @classmethod
    def _model(cls, *args):
        raise NotImplementedError(
            'Subclasses of MultiForm must define _model.')


    ###########################################################################
    # Initialization
    ###########################################################################

    def __init__(self, *args, **kw):
        super(MultiForm, self).__init__(*args, **kw)
        for fieldname, field in self.fields.items():
            field.widget.attrs['class'] = '%s-%s' % (
                self.__class__.prefix, fieldname)
        # Repeated forms need unique id="" attributes.  Generate them based on
        # the id field value.
        self.auto_id = 'id_%%s.%s' % self.get_field_val(self.pk_field)


    ###########################################################################
    # Methods for creating MultiForms from POST data
    ###########################################################################

    @classmethod
    def forms_from_POST(cls, POST, *args, **kw):
        """
        Create a list of MultiForm objects for POST data.

        >>> class TestForm(MultiForm):
        ...     fld = forms.CharField()
        ...     prefix = 'px'
        >>> request_POST = {'px-fld': ['val1', 'val2']}
        >>> [f.data for f in TestForm.forms_from_POST(request_POST)]
        [{'px-fld': 'val1'}, {'px-fld': 'val2'}]
        """
        return cls._forms_from_data(POST, *args, **kw)


    @classmethod
    def save_forms_from_POST(cls, POST, *args, **kw):
        """
        Retrieve a list of MultiForm objects for POST data.  Try to
        save each of the objects.  Return three lists: saved, deleted
        and invalid forms.
        """
        saved = []
        deleted = []
        invalid = []
        for form in cls.forms_from_POST(POST, *args, **kw):
            if form.is_valid():
                instance = form.save()
                if instance is None:
                    # object was deleted
                    deleted.append(form)
                else:
                    # object was saved
                    saved.append(cls.for_instance(instance))
            else:
                invalid.append(form)
        return saved, deleted, invalid


    @classmethod
    def from_data(cls, data=None, index=None, initial=None):
        """
        Create one form instance and extract its data from POST field
        arrays.  ``index`` is the index of this form among all
        repeated forms for the same model.

        Non-blank core values for required fields are regarded as
        invalid.
        """

        if index is None:
            raise ValueError('form index missing')

        form = cls(
            data=cls._extract_data(data, index),
            initial=cls._extract_data(initial, index, prefix=False),
            prefix=cls.prefix)
        form.form_index = index

        #
        # The ID field must accept NEW* values for new objects
        #
        form._fix_pk_field_clean()

        #
        # Fields with core must regard values equal to the core as
        # empty values
        #
        form._fix_fields_clean()

        return form


    ###########################################################################
    # Saving data into DB based of form field values
    ###########################################################################

    def save(self, defaults=None):
        """
        Save form data into DB.  A new object is created and saved,
        and existing objects are retrieved and updated.  An existing
        object with its coreed fields left blank is deleted.
        """
        if self.is_new():
            # create a new instance
            instance = self._model(**defaults or {})
        else:
            # retrieve the old instance
            instance = self._model.objects.get(
                pk=self.get_field_val(self.pk_field))
        if self.is_deleted():
            # delete the object
            instance.delete()
            return None
        else:
            # use ambidjangolib.newforms_extra.models.save_instance to combine
            # values from this form to old values from the instance and save the
            # object
            saved_instance = save_instance(self, instance)
            # update ID from NEWx to real DB ID
            fieldname, value = self._extract_instance_field(
                saved_instance, self.pk_field)
            self.data[fieldname] = value
            return saved_instance


    ###########################################################################
    # New blank form handling
    ###########################################################################

    @classmethod
    def make_new(cls, new_id, **initial_data):
        """
        Create a new blank form.
        """
        i = cls.core.copy()
        i.update(initial_data)
        i[cls.pk_field] = '%s%s' % (cls.new_prefix, new_id)
        #data = dict((cls.add_prefix(fieldname), value)
        #            for (fieldname, value) in initial_data.items())
        return cls(initial=i)


    def is_new(self):
        """
        Return True if the value of the form's ID field begins with
        the new form prefix (default: 'NEW').
        """
        return self.get_new_id() is not None


    def get_new_id(self):
        """
        Return the new form identifier number, e.g. the integer 1 for
        a form whose pk_field's value is 'NEW1'.
        """
        value = self.get_field_val(self.pk_field)
        if value.startswith(self.new_prefix):
            return int(value[len(self.new_prefix):])
        else:
            return None


    @staticmethod
    def next_new_id(formlist):
        return max(chain([0], (form.get_new_id() for form in formlist))) + 1


    def non_empty_fields(self):
        """
        Return a dict of those coreed fields which are not are blank
        or identical to their core.

        THIS FUNCTION IS HERE FOR DEBUGGING PURPOSES
        """
        result = {}
        for fieldname, field in self.fields.items():
            if field.widget.is_hidden or fieldname not in self.core:
                continue
            value = self.get_field_val(fieldname)
            if not value or value == self.core[fieldname]:
                continue
            result[fieldname] = value
        return result


    @classmethod
    def _forms_from_data(cls, data, *args, **kw):
        """
        Create form objects for fields in data.

        >>> class TestForm(MultiForm):
        ...     fld1 = forms.CharField()
        ...     fld2 = forms.CharField()
        ...     prefix = 'px'

        >>> testdata = {'px-fld1': ['val1', 'val2']}
        >>> testinitial = {'fld2': ['val3', 'val4']}

        >>> from pprint import pprint
        >>> pprint([(f.data, f.initial)
        ...         for f in TestForm._forms_from_data(
        ...             data=testdata, initial=testinitial)])
        [({'px-fld1': 'val1'}, {'fld2': 'val3'}),
         ({'px-fld1': 'val2'}, {'fld2': 'val4'})]
        """
        forms = []
        while True:
            try:
                forms.append(cls.from_data(data, len(forms), *args, **kw))
            except IndexError:
                break
        return forms


    ###########################################################################
    # Internal validation customizations called from ``from_data``
    ###########################################################################

    #def clean(self):
    #    """
    #    If a form's coreed fields are cleared and the value of
    #    ``pk_field`` identifies an instance in the DB, the instance
    #    should be deleted and the form should pass validation.
    #    """
    #    if self.is_deleted():
    #        # The form for an instance in the DB was cleared blank, so
    #        # the instance should be deleted.  Clear any errors on the
    #        # coreed fields so the form will pass validation.
    #        for fieldname in self.core:
    #            del self.__errors[fieldname]
    #    return super(MultiForm, self).clean()


    def _fix_pk_field_clean(self):
        """
        Replace the clean method of the id field so prefixed new form
        IDs are accepted as valid.  This is called in ``from_data``.
        """
        def clean_pk_field(form, value):
            if value and value.startswith(self.new_prefix):
                return value
            else:
                return orig_id_clean(value)
        pk_field = self.fields[self.pk_field]
        orig_id_clean = pk_field.clean
        pk_field.clean = new.instancemethod(clean_pk_field, pk_field)


    def _fix_fields_clean(self):
        """
        Replace the clean methods of required and coreed fields so
        core values are regarded as empty values.  This is called in
        ``from_data``.
        """
        for fieldname, field in self.fields.items():
            if field.required and fieldname in self.core:
                def new_clean(field, value, fieldname=fieldname):
                    if value == self.core[fieldname]:
                        value = ''
                    if self.is_deleted():
                        return value
                    else:
                        return orig_clean(value)
                orig_clean = field.clean
                field.clean = new.instancemethod(new_clean, field)


    ###########################################################################
    # Internal helper for parsing POST array data
    ###########################################################################

    @classmethod
    def _extract_data(cls, data, index, prefix=True):
        """
        >>> class TestForm(MultiForm):
        ...     testfield = forms.CharField()
        ...     prefix = 'testprefix'

        >>> testdata = {'testfield': ['val1', 'val2']}

        >>> print TestForm._extract_data(testdata, 0, prefix=False)
        {'testfield': 'val1'}

        >>> print TestForm._extract_data(testdata, 2, prefix=False)
        Traceback (most recent call last):
        IndexError: list index out of range

        >>> testdata = {'testprefix-testfield': ['val1', 'val2']}

        >>> print TestForm._extract_data(testdata, 1, prefix=True)
        {'testprefix-testfield': 'val2'}

        >>> print TestForm._extract_data(testdata, 2, prefix=True)
        Traceback (most recent call last):
        IndexError: list index out of range

        >>> TestForm._extract_data({'dummy': '1'}, 0)
        Traceback (most recent call last):
        IndexError: No data for multiform
        """
        if data is None:
            return None
        if not isinstance(data, MultiValueDict):
            data = MultiValueDict(data)
        my_data = {}
        for field_name in cls.base_fields.keys():
            if prefix:
                field_name = cls.add_prefix(field_name)
            if field_name in data:
                my_data[field_name] = data.getlist(field_name)[index]
        if not my_data:
            raise IndexError('No data for multiform')
        return my_data


    ###########################################################################
    # Miscellaneous helpers
    ###########################################################################

    def __repr__(self): return "<%s %s>" % (
        self.__class__.__name__,
        self.get_field_val(self.pk_field))


    def get_field_val(self, fieldname):
        """
        Return the value of the given field by plain field name.
        Knows about the prefix and prepends it automatically.
        """
        full_fieldname = self.add_prefix(fieldname)
        try:
            return self.data[full_fieldname]
        except KeyError:
            return self.initial[fieldname]


    def dump(self):
        return '[%s %s]' % (
            self.__class__.__name__,
            self.get_field_val(self.pk_field))


    ###########################################################################
    # Trashbin -- are these methods used anywhere?
    ###########################################################################

    @classmethod
    def forms_from_data(cls, data):
        """
        Create MultiForm objects for matching fields found in data.
        """
        return cls._forms_from_data(data=data)


    @classmethod
    def forms_from_initial(cls, initial):
        """
        Create MultiForm objects for matching fields found in initial data.
        """
        return cls._forms_from_data(None, initial=initial)