"""Fields are used to control what's displayed in forms. It makes the link

between something to edit and its display in the form. Actual display is handled

by a widget associated to the field.

:organization: Logilab

:copyright: 2009-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.

:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr

:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses

"""

__docformat__ = "restructuredtext en"

from warnings import warn

from datetime import datetime

from logilab.mtconverter import xml_escape

from logilab.common.date import ustrftime

from yams.schema import KNOWN_METAATTRIBUTES, role_name

from yams.constraints import (SizeConstraint, StaticVocabularyConstraint,

                              FormatConstraint)

from cubicweb import Binary, tags, uilib

from cubicweb.web import INTERNAL_FIELD_VALUE, ProcessFormError, eid_param, \

     formwidgets as fw, uicfg

class UnmodifiedField(Exception):

    """raise this when a field has not actually been edited and you want to skip

    it

    """

def vocab_sort(vocab):

    """sort vocabulary, considering option groups"""

    result = []

    partresult = []

    for label, value in vocab:

        if value is None: # opt group start

            if partresult:

                result += sorted(partresult)

                partresult = []

            result.append( (label, value) )

        else:

            partresult.append( (label, value) )

    result += sorted(partresult)

    return result

_MARKER = object()

class Field(object):

    """This class is the abstract base class for all fields. It hold a bunch

    of attributes which may be used for fine control of the behaviour of a

    concret field.

    All the attributes described below have sensible default value which may be

    overriden by value given to field's constructor.

    :name:

       name of the field (basestring), should be unique in a form.

    :id:

       dom identifier (default to the same value as `name`), should be unique in

       a form.

    :label:

       label of the field (default to the same value as `name`).

    :help:

       help message about this field.

    :widget:

       widget associated to the field. Each field class has a default widget

       class which may be overriden per instance.

    :required:

       bool flag telling if the field is required or not.

    :value:

       field's value, used when no value specified by other means. XXX explain

    :choices:

       static vocabulary for this field. May be a list of values or a list of

       (label, value) tuples if specified.

    :sort:

       bool flag telling if the vocabulary (either static vocabulary specified

       in `choices` or dynamic vocabulary fetched from the form) should be

       sorted on label.

    :internationalizable:

       bool flag telling if the vocabulary labels should be translated using the

       current request language.

    :eidparam:

       bool flag telling if this field is linked to a specific entity

    :role:

       when the field is linked to an entity attribute or relation, tells the

       role of the entity in the relation (eg 'subject' or 'object')

    :fieldset:

       optional fieldset to which this field belongs to

    :order:

       key used by automatic forms to sort fields

    :ignore_req_params:

       when true, this field won't consider value potentialy specified using

       request's form parameters (eg you won't be able to specify a value using for

       instance url like http://mywebsite.com/form?field=value)

    """

    # default widget associated to this class of fields. May be overriden per

    # instance

    widget = fw.TextInput

    # does this field requires a multipart form

    needs_multipart = False

    # class attribute used for ordering of fields in a form

    __creation_rank = 0

    eidparam = False

    role = None

    id = None

    help = None

    required = False

    choices = None

    sort = True

    internationalizable = False

    fieldset = None

    order = None

    value = _MARKER

    fallback_on_none_attribute = False

    ignore_req_params = False

    def __init__(self, name=None, label=_MARKER, widget=None, **kwargs):

        for key, val in kwargs.items():

            if key == 'initial':

                warn('[3.6] use value instead of initial', DeprecationWarning,

                     stacklevel=3)

                key = 'value'

            assert hasattr(self.__class__, key) and not key[0] == '_', key

            setattr(self, key, val)

        self.name = name

        if label is _MARKER:

            label = name or _MARKER

        self.label = label

        # has to be done after other attributes initialization

        self.init_widget(widget)

        # ordering number for this field instance

        self.creation_rank = Field.__creation_rank

        Field.__creation_rank += 1

    def __unicode__(self):

        return u'<%s name=%r eidparam=%s role=%r id=%r value=%r visible=%r @%x>' % (

            self.__class__.__name__, self.name, self.eidparam, self.role,

            self.id, self.value, self.is_visible(), id(self))

    def __repr__(self):

        return self.__unicode__().encode('utf-8')

    def init_widget(self, widget):

        if widget is not None:

            self.widget = widget

        elif self.choices and not self.widget.vocabulary_widget:

            self.widget = fw.Select()

        if isinstance(self.widget, type):

            self.widget = self.widget()

    def set_name(self, name):

        """automatically set .label when name is set"""

        assert name

        self.name = name

        if self.label is _MARKER:

            self.label = name

    def is_visible(self):

        """return true if the field is not an hidden field"""

        return not isinstance(self.widget, fw.HiddenInput)

    def actual_fields(self, form):

        """return actual fields composing this field in case of a compound

        field, usually simply return self

        """

        yield self

    def format_value(self, req, value):

        """return value suitable for display where value may be a list or tuple

        of values

        """

        if isinstance(value, (list, tuple)):

            return [self.format_single_value(req, val) for val in value]

        return self.format_single_value(req, value)

    def format_single_value(self, req, value):

        """return value suitable for display"""

        if value is None or value is False:

            return u''

        if value is True:

            return u'1'

        return unicode(value)

    def get_widget(self, form):

        """return the widget instance associated to this field"""

        return self.widget

    def input_name(self, form, suffix=None):

        """return 'qualified name' for this field"""

        # caching is necessary else we get some pb on entity creation :

        # entity.eid is modified from creation mark (eg 'X') to its actual eid

        # (eg 123), and then `field.input_name()` won't return the right key

        # anymore if not cached (first call to input_name done *before* eventual

        # eid affectation).

        #

        # note that you should NOT use @cached else it will create a memory leak

        # on persistent fields (eg created once for all on a form class) because

        # of the 'form' appobject argument: the cache will keep growing as new

        # form are created...

        try:

            return form.formvalues[(self, 'input_name', suffix)]

        except KeyError:

            name = self.role_name()

            if suffix is not None:

                name += suffix

            if self.eidparam:

                name = eid_param(name, form.edited_entity.eid)

            form.formvalues[(self, 'input_name', suffix)] = name

            return name

    def role_name(self):

        """return <field.name>-<field.role> if role is specified, else field.name"""

        if self.role is not None:

            return role_name(self.name, self.role)

        return self.name

    def dom_id(self, form, suffix=None):

        """return an html dom identifier for this field"""

        id = self.id or self.role_name()

        if suffix is not None:

            id += suffix

        if self.eidparam:

            return eid_param(id, form.edited_entity.eid)

        return id

    def typed_value(self, form, load_bytes=False):

        if self.eidparam and self.role is not None:

            entity = form.edited_entity

            if form._cw.vreg.schema.rschema(self.name).final:

                if entity.has_eid() or self.name in entity:

                    value = getattr(entity, self.name)

                    if value is not None or not self.fallback_on_none_attribute:

                        return value

            elif entity.has_eid() or entity.relation_cached(self.name, self.role):

                value = [r[0] for r in entity.related(self.name, self.role)]

                if value or not self.fallback_on_none_attribute:

                    return value

        return self.initial_typed_value(form, load_bytes)

    def initial_typed_value(self, form, load_bytes):

        if self.value is not _MARKER:

            if callable(self.value):

                return self.value(form)

            return self.value

        formattr = '%s_%s_default' % (self.role, self.name)

        if hasattr(form, formattr):

            warn('[3.6] %s.%s deprecated, use field.value' % (

                form.__class__.__name__, formattr), DeprecationWarning)

            return getattr(form, formattr)()

        if self.eidparam and self.role is not None:

            if form._cw.vreg.schema.rschema(self.name).final:

                return form.edited_entity.e_schema.default(self.name)

            return ()

        return None

    def example_format(self, req):

        """return a sample string describing what can be given as input for this

        field

        """

        return u''

    def render(self, form, renderer):

        """render this field, which is part of form, using the given form

        renderer

        """

        widget = self.get_widget(form)

        return widget.render(form, self, renderer)

    def vocabulary(self, form, **kwargs):

        """return vocabulary for this field. This method will be called by

        widgets which requires a vocabulary.

        """

        assert self.choices is not None

        if callable(self.choices):

            try:

                if getattr(self.choices, 'im_self', None) is self:

                    vocab = self.choices(form=form, **kwargs)

                else:

                    vocab = self.choices(form=form, field=self, **kwargs)

            except TypeError:

                try:

                    vocab = self.choices(form=form, **kwargs)

                    warn('[3.6]  %s: choices should now take '

                         'the form and field as named arguments' % self,

                         DeprecationWarning)

                except TypeError:

                    warn('[3.3]  %s: choices should now take '

                         'the form and field as named arguments' % self,

                         DeprecationWarning)

                    vocab = self.choices(req=form._cw, **kwargs)

        else:

            vocab = self.choices

        if vocab and not isinstance(vocab[0], (list, tuple)):

            vocab = [(x, x) for x in vocab]

        if self.internationalizable:

            # the short-cirtcuit 'and' boolean operator is used here to permit

            # a valid empty string in vocabulary without attempting to translate

            # it by gettext (which can lead to weird strings display)

            vocab = [(label and form._cw._(label), value) for label, value in vocab]

        if self.sort:

            vocab = vocab_sort(vocab)

        return vocab

    def format(self, form):

        """return MIME type used for the given (text or bytes) field"""

        if self.eidparam and self.role == 'subject':

            entity = form.edited_entity

            if entity.e_schema.has_metadata(self.name, 'format') and (

                entity.has_eid() or '%s_format' % self.name in entity):

                return form.edited_entity.attr_metadata(self.name, 'format')

        return form._cw.property_value('ui.default-text-format')

    def encoding(self, form):

        """return encoding used for the given (text) field"""

        if self.eidparam:

            entity = form.edited_entity

            if entity.e_schema.has_metadata(self.name, 'encoding') and (

                entity.has_eid() or '%s_encoding' % self.name in entity):

                return form.edited_entity.attr_metadata(self.name, 'encoding')

        return form._cw.encoding

    def form_init(self, form):

        """method called before by build_context to trigger potential field

        initialization requiring the form instance

        """

        pass

    def has_been_modified(self, form):

        # fields not corresponding to an entity attribute / relations

        # are considered modified

        if not self.eidparam or not self.role or not form.edited_entity.has_eid():

            return True # XXX

        try:

            if self.role == 'subject':

                previous_value = getattr(form.edited_entity, self.name)

            else:

                previous_value = getattr(form.edited_entity,

                                         'reverse_%s' % self.name)

        except AttributeError:

            # fields with eidparam=True but not corresponding to an actual

            # attribute or relation

            return True

        # if it's a non final relation, we need the eids

        if isinstance(previous_value, tuple):

            # widget should return a set of untyped eids

            previous_value = set(unicode(e.eid) for e in previous_value)

        try:

            new_value = self.process_form_value(form)

        except ProcessFormError:

            return True

        except UnmodifiedField:

            return False

        if previous_value == new_value:

            return False # not modified

        return True

    def process_form_value(self, form):

        """process posted form and return correctly typed value"""

        try:

            return form.formvalues[(self, form)]

        except KeyError:

            value = form.formvalues[(self, form)] = self._process_form_value(form)

            return value

    def _process_form_value(self, form):

        widget = self.get_widget(form)

        value = widget.process_field_data(form, self)

        return self._ensure_correctly_typed(form, value)

    def _ensure_correctly_typed(self, form, value):

        """widget might to return date as a correctly formatted string or as

        correctly typed objects, but process_for_value must return a typed value.

        Override this method to type the value if necessary

        """

        return value or None