"""

The Field class and basic fields

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. Note::

  Fields are used to control what's edited in forms. They makes the link between

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

  widget associated to the field.

Let first see the base class for fields:

.. autoclass:: cubicweb.web.formfields.Field

Now, you usually don't use that class but one of the concret field classes

described below, according to what you want to edit.

Basic fields

''''''''''''

.. autoclass:: cubicweb.web.formfields.StringField()

.. autoclass:: cubicweb.web.formfields.PasswordField()

.. autoclass:: cubicweb.web.formfields.IntField()

.. autoclass:: cubicweb.web.formfields.FloatField()

.. autoclass:: cubicweb.web.formfields.BooleanField()

.. autoclass:: cubicweb.web.formfields.DateField()

.. autoclass:: cubicweb.web.formfields.DateTimeField()

.. autoclass:: cubicweb.web.formfields.TimeField()

Compound fields

''''''''''''''''

.. autoclass:: cubicweb.web.formfields.RichTextField()

.. autoclass:: cubicweb.web.formfields.FileField()

.. autoclass:: cubicweb.web.formfields.CompoundField()

.. autoclass cubicweb.web.formfields.EditableFileField() XXX should be a widget

Entity specific fields and function

'''''''''''''''''''''''''''''''''''

.. autoclass:: cubicweb.web.formfields.RelationField()

.. autofunction:: cubicweb.web.formfields.guess_field

"""

__docformat__ = "restructuredtext en"

from warnings import warn

from datetime import datetime

from logilab.mtconverter import xml_escape

from logilab.common import nullobject

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 = nullobject()

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.

    **Attributes**

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

    overriden by named arguments given to field's constructor.

    :attr:`name`

       base name of the field (basestring). The actual input name is returned by

       the :meth:`input_name` method and may differ from that name (for instance

       if `eidparam` is true).

    :attr:`id`

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

       a form.

    :attr:`label`

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

    :attr:`help`

       help message about this field.

    :attr:`widget`

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

       class which may be overriden per instance.

    :attr:`value`

       field value. May be an actual value or a callable which should take the

       form as argument and return a value.

    :attr:`choices`

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

       (label, value) tuples or a callable which should take the form and field

       as arguments and return a list of values or a list of (label, value).

    :attr:`required`

       bool flag telling if the field is required or not.

    :attr:`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.

    :attr:`internationalizable`

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

       current request language.

    :attr:`eidparam`

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

    :attr:`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')

    :attr:`fieldset`

       optional fieldset to which this field belongs to

    :attr:`order`

       key used by automatic forms to sort fields

    :attr:`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)

    .. currentmodule:: cubicweb.web.formfields

    **Generic methods**

    .. automethod:: Field.input_name

    .. automethod:: Field.dom_id

    .. automethod:: Field.actual_fields

    **Form generation methods**

    .. automethod:: form_init

    .. automethod:: typed_value

    **Post handling methods**

    .. automethod:: process_posted

    .. automethod:: process_form_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):

        """Fields may be composed of other fields. For instance the

        :class:`~cubicweb.web.formfields.RichTextField` is containing a format

        field to define the text format. This method returns actual fields that

        should be considered for display / edition. It 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 the 'qualified name' for this field, e.g. something suitable

        to use as HTML input name. You can specify a suffix that will be

        included in the name when widget needs several inputs.

        """

        # 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 the HTML DOM identifier for this field, e.g. something

        suitable to use as HTML input id. You can specify a suffix that will be

        included in the name when widget needs several inputs.

        """

        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):

        """Return the correctly typed value for this field in the form context.

        """

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