django/db/models/fields/__init__.py

   1 import copy
   2 import datetime
   3 import os
   4 import time
   5 try:
   6     import decimal
   7 except ImportError:
   8     from django.utils import _decimal as decimal    # for Python 2.3
   9
  10 from django.db import get_creation_module
  11 from django.db.models import signals
  12 from django.dispatch import dispatcher
  13 from django.conf import settings
  14 from django.core import validators
  15 from django import oldforms
  16 from django import newforms as forms
  17 from django.core.exceptions import ObjectDoesNotExist
  18 from django.utils.functional import curry
  19 from django.utils.itercompat import tee
  20 from django.utils.text import capfirst
  21 from django.utils.translation import ugettext_lazy, ugettext as _
  22 from django.utils.encoding import smart_unicode, force_unicode, smart_str
  23 from django.utils.maxlength import LegacyMaxlength
  24
  25 class NOT_PROVIDED:
  26     pass
  27
  28 # Values for filter_interface.
  29 HORIZONTAL, VERTICAL = 1, 2
  30
  31 # The values to use for "blank" in SelectFields. Will be appended to the start of most "choices" lists.
  32 BLANK_CHOICE_DASH = [("", "---------")]
  33 BLANK_CHOICE_NONE = [("", "None")]
  34
  35 # prepares a value for use in a LIKE query
  36 prep_for_like_query = lambda x: smart_unicode(x).replace("\\", "\\\\").replace("%", "\%").replace("_", "\_")
  37
  38 # returns the <ul> class for a given radio_admin value
  39 get_ul_class = lambda x: 'radiolist%s' % ((x == HORIZONTAL) and ' inline' or '')
  40
  41 class FieldDoesNotExist(Exception):
  42     pass
  43
  44 def manipulator_validator_unique(f, opts, self, field_data, all_data):
  45     "Validates that the value is unique for this field."
  46     lookup_type = f.get_validator_unique_lookup_type()
  47     try:
  48         old_obj = self.manager.get(**{lookup_type: field_data})
  49     except ObjectDoesNotExist:
  50         return
  51     if getattr(self, 'original_object', None) and self.original_object._get_pk_val() == old_obj._get_pk_val():
  52         return
  53     raise validators.ValidationError, _("%(optname)s with this %(fieldname)s already exists.") % {'optname': capfirst(opts.verbose_name), 'fieldname': f.verbose_name}
  54
  55 # A guide to Field parameters:
  56 #
  57 #   * name:      The name of the field specifed in the model.
  58 #   * attname:   The attribute to use on the model object. This is the same as
  59 #                "name", except in the case of ForeignKeys, where "_id" is
  60 #                appended.
  61 #   * db_column: The db_column specified in the model (or None).
  62 #   * column:    The database column for this field. This is the same as
  63 #                "attname", except if db_column is specified.
  64 #
  65 # Code that introspects values, or does other dynamic things, should use
  66 # attname. For example, this gets the primary key value of object "obj":
  67 #
  68 #     getattr(obj, opts.pk.attname)
  69
  70 class Field(object):
  71     # Provide backwards compatibility for the maxlength attribute and
  72     # argument for this class and all subclasses.
  73     __metaclass__ = LegacyMaxlength
  74
  75     # Designates whether empty strings fundamentally are allowed at the
  76     # database level.
  77     empty_strings_allowed = True
  78
  79     # These track each time a Field instance is created. Used to retain order.
  80     # The auto_creation_counter is used for fields that Django implicitly
  81     # creates, creation_counter is used for all user-specified fields.
  82     creation_counter = 0
  83     auto_creation_counter = -1
  84
  85     def __init__(self, verbose_name=None, name=None, primary_key=False,
  86             max_length=None, unique=False, blank=False, null=False,
  87             db_index=False, core=False, rel=None, default=NOT_PROVIDED,
  88             editable=True, serialize=True, prepopulate_from=None,
  89             unique_for_date=None, unique_for_month=None, unique_for_year=None,
  90             validator_list=None, choices=None, radio_admin=None, help_text='',
  91             db_column=None, db_tablespace=None, auto_created=False):
  92         self.name = name
  93         self.verbose_name = verbose_name
  94         self.primary_key = primary_key
  95         self.max_length, self.unique = max_length, unique
  96         self.blank, self.null = blank, null
  97         # Oracle treats the empty string ('') as null, so coerce the null
  98         # option whenever '' is a possible value.
  99         if self.empty_strings_allowed and settings.DATABASE_ENGINE == 'oracle':
 100             self.null = True
 101         self.core, self.rel, self.default = core, rel, default
 102         self.editable = editable
 103         self.serialize = serialize
 104         self.validator_list = validator_list or []
 105         self.prepopulate_from = prepopulate_from
 106         self.unique_for_date, self.unique_for_month = unique_for_date, unique_for_month
 107         self.unique_for_year = unique_for_year
 108         self._choices = choices or []
 109         self.radio_admin = radio_admin
 110         self.help_text = help_text
 111         self.db_column = db_column
 112         self.db_tablespace = db_tablespace or settings.DEFAULT_INDEX_TABLESPACE
 113
 114         # Set db_index to True if the field has a relationship and doesn't explicitly set db_index.
 115         self.db_index = db_index
 116
 117         # Adjust the appropriate creation counter, and save our local copy.
 118         if auto_created:
 119             self.creation_counter = Field.auto_creation_counter
 120             Field.auto_creation_counter -= 1
 121         else:
 122             self.creation_counter = Field.creation_counter
 123             Field.creation_counter += 1
 124
 125     def __cmp__(self, other):
 126         # This is needed because bisect does not take a comparison function.
 127         return cmp(self.creation_counter, other.creation_counter)
 128
 129     def __deepcopy__(self, memodict):
 130         # We don't have to deepcopy very much here, since most things are not
 131         # intended to be altered after initial creation.
 132         obj = copy.copy(self)
 133         if self.rel:
 134             obj.rel = copy.copy(self.rel)
 135         memodict[id(self)] = obj
 136         return obj
 137
 138     def to_python(self, value):
 139         """
 140         Converts the input value into the expected Python data type, raising
 141         validators.ValidationError if the data can't be converted. Returns the
 142         converted value. Subclasses should override this.
 143         """
 144         return value
 145
 146     def db_type(self):
 147         """
 148         Returns the database column data type for this field, taking into
 149         account the DATABASE_ENGINE setting.
 150         """
 151         # The default implementation of this method looks at the
 152         # backend-specific DATA_TYPES dictionary, looking up the field by its
 153         # "internal type".
 154         #
 155         # A Field class can implement the get_internal_type() method to specify
 156         # which *preexisting* Django Field class it's most similar to -- i.e.,
 157         # an XMLField is represented by a TEXT column type, which is the same
 158         # as the TextField Django field type, which means XMLField's
 159         # get_internal_type() returns 'TextField'.
 160         #
 161         # But the limitation of the get_internal_type() / DATA_TYPES approach
 162         # is that it cannot handle database column types that aren't already
 163         # mapped to one of the built-in Django field types. In this case, you
 164         # can implement db_type() instead of get_internal_type() to specify
 165         # exactly which wacky database column type you want to use.
 166         try:
 167             return get_creation_module().DATA_TYPES[self.get_internal_type()] % self.__dict__
 168         except KeyError:
 169             return None
 170
 171     def validate_full(self, field_data, all_data):
 172         """
 173         Returns a list of errors for this field. This is the main interface,
 174         as it encapsulates some basic validation logic used by all fields.
 175         Subclasses should implement validate(), not validate_full().
 176         """
 177         if not self.blank and not field_data:
 178             return [_('This field is required.')]
 179         try:
 180             self.validate(field_data, all_data)
 181         except validators.ValidationError, e:
 182             return e.messages
 183         return []
 184
 185     def validate(self, field_data, all_data):
 186         """
 187         Raises validators.ValidationError if field_data has any errors.
 188         Subclasses should override this to specify field-specific validation
 189         logic. This method should assume field_data has already been converted
 190         into the appropriate data type by Field.to_python().
 191         """
 192         pass
 193
 194     def set_attributes_from_name(self, name):
 195         self.name = name
 196         self.attname, self.column = self.get_attname_column()
 197         self.verbose_name = self.verbose_name or (name and name.replace('_', ' '))
 198
 199     def contribute_to_class(self, cls, name):
 200         self.set_attributes_from_name(name)
 201         cls._meta.add_field(self)
 202         if self.choices:
 203             setattr(cls, 'get_%s_display' % self.name, curry(cls._get_FIELD_display, field=self))
 204
 205     def get_attname(self):
 206         return self.name
 207
 208     def get_attname_column(self):
 209         attname = self.get_attname()
 210         column = self.db_column or attname
 211         return attname, column
 212
 213     def get_cache_name(self):
 214         return '_%s_cache' % self.name
 215
 216     def get_internal_type(self):
 217         return self.__class__.__name__
 218
 219     def pre_save(self, model_instance, add):
 220         "Returns field's value just before saving."
 221         return getattr(model_instance, self.attname)
 222
 223     def get_db_prep_save(self, value):
 224         "Returns field's value prepared for saving into a database."
 225         return value
 226
 227     def get_db_prep_lookup(self, lookup_type, value):
 228         "Returns field's value prepared for database lookup."
 229         if lookup_type in ('exact', 'regex', 'iregex', 'gt', 'gte', 'lt', 'lte', 'month', 'day', 'search'):
 230             return [value]
 231         elif lookup_type in ('range', 'in'):
 232             return value
 233         elif lookup_type in ('contains', 'icontains'):
 234             return ["%%%s%%" % prep_for_like_query(value)]
 235         elif lookup_type == 'iexact':
 236             return [prep_for_like_query(value)]
 237         elif lookup_type in ('startswith', 'istartswith'):
 238             return ["%s%%" % prep_for_like_query(value)]
 239         elif lookup_type in ('endswith', 'iendswith'):
 240             return ["%%%s" % prep_for_like_query(value)]
 241         elif lookup_type == 'isnull':
 242             return []
 243         elif lookup_type == 'year':
 244             try:
 245                 value = int(value)
 246             except ValueError:
 247                 raise ValueError("The __year lookup type requires an integer argument")
 248             if settings.DATABASE_ENGINE == 'sqlite3':
 249                 first = '%s-01-01'
 250                 second = '%s-12-31 23:59:59.999999'
 251             elif settings.DATABASE_ENGINE == 'oracle' and self.get_internal_type() == 'DateField':
 252                 first = '%s-01-01'
 253                 second = '%s-12-31'
 254             else:
 255                 first = '%s-01-01 00:00:00'
 256                 second = '%s-12-31 23:59:59.999999'
 257             return [first % value, second % value]
 258         raise TypeError("Field has invalid lookup: %s" % lookup_type)
 259
 260     def has_default(self):
 261         "Returns a boolean of whether this field has a default value."
 262         return self.default is not NOT_PROVIDED
 263
 264     def get_default(self):
 265         "Returns the default value for this field."
 266         if self.default is not NOT_PROVIDED:
 267             if callable(self.default):
 268                 return self.default()
 269             return force_unicode(self.default, strings_only=True)
 270         if not self.empty_strings_allowed or (self.null and settings.DATABASE_ENGINE != 'oracle'):
 271             return None
 272         return ""
 273
 274     def get_manipulator_field_names(self, name_prefix):
 275         """
 276         Returns a list of field names that this object adds to the manipulator.
 277         """
 278         return [name_prefix + self.name]
 279
 280     def prepare_field_objs_and_params(self, manipulator, name_prefix):
 281         params = {'validator_list': self.validator_list[:]}
 282         if self.max_length and not self.choices: # Don't give SelectFields a max_length parameter.
 283             params['max_length'] = self.max_length
 284
 285         if self.choices:
 286             if self.radio_admin:
 287                 field_objs = [oldforms.RadioSelectField]
 288                 params['ul_class'] = get_ul_class(self.radio_admin)
 289             else:
 290                 field_objs = [oldforms.SelectField]
 291
 292             params['choices'] = self.get_choices_default()
 293         else:
 294             field_objs = self.get_manipulator_field_objs()
 295         return (field_objs, params)
 296
 297     def get_manipulator_fields(self, opts, manipulator, change, name_prefix='', rel=False, follow=True):
 298         """
 299         Returns a list of oldforms.FormField instances for this field. It
 300         calculates the choices at runtime, not at compile time.
 301
 302         name_prefix is a prefix to prepend to the "field_name" argument.
 303         rel is a boolean specifying whether this field is in a related context.
 304         """
 305         field_objs, params = self.prepare_field_objs_and_params(manipulator, name_prefix)
 306
 307         # Add the "unique" validator(s).
 308         for field_name_list in opts.unique_together:
 309             if field_name_list[0] == self.name:
 310                 params['validator_list'].append(getattr(manipulator, 'isUnique%s' % '_'.join(field_name_list)))
 311
 312         # Add the "unique for..." validator(s).
 313         if self.unique_for_date:
 314             params['validator_list'].append(getattr(manipulator, 'isUnique%sFor%s' % (self.name, self.unique_for_date)))
 315         if self.unique_for_month:
 316             params['validator_list'].append(getattr(manipulator, 'isUnique%sFor%s' % (self.name, self.unique_for_month)))
 317         if self.unique_for_year:
 318             params['validator_list'].append(getattr(manipulator, 'isUnique%sFor%s' % (self.name, self.unique_for_year)))
 319         if self.unique or (self.primary_key and not rel):
 320             params['validator_list'].append(curry(manipulator_validator_unique, self, opts, manipulator))
 321
 322         # Only add is_required=True if the field cannot be blank. Primary keys
 323         # are a special case, and fields in a related context should set this
 324         # as False, because they'll be caught by a separate validator --
 325         # RequiredIfOtherFieldGiven.
 326         params['is_required'] = not self.blank and not self.primary_key and not rel
 327
 328         # BooleanFields (CheckboxFields) are a special case. They don't take
 329         # is_required.
 330         if isinstance(self, BooleanField):
 331             del params['is_required']
 332
 333         # If this field is in a related context, check whether any other fields
 334         # in the related object have core=True. If so, add a validator --
 335         # RequiredIfOtherFieldsGiven -- to this FormField.
 336         if rel and not self.blank and not isinstance(self, AutoField) and not isinstance(self, FileField):
 337             # First, get the core fields, if any.
 338             core_field_names = []
 339             for f in opts.fields:
 340                 if f.core and f != self:
 341                     core_field_names.extend(f.get_manipulator_field_names(name_prefix))
 342             # Now, if there are any, add the validator to this FormField.
 343             if core_field_names:
 344                 params['validator_list'].append(validators.RequiredIfOtherFieldsGiven(core_field_names, ugettext_lazy("This field is required.")))
 345
 346         # Finally, add the field_names.
 347         field_names = self.get_manipulator_field_names(name_prefix)
 348         return [man(field_name=field_names[i], **params) for i, man in enumerate(field_objs)]
 349
 350     def get_validator_unique_lookup_type(self):
 351         return '%s__exact' % self.name
 352
 353     def get_manipulator_new_data(self, new_data, rel=False):
 354         """
 355         Given the full new_data dictionary (from the manipulator), returns this
 356         field's data.
 357         """
 358         if rel:
 359             return new_data.get(self.name, [self.get_default()])[0]
 360         val = new_data.get(self.name, self.get_default())
 361         if not self.empty_strings_allowed and val == '' and self.null:
 362             val = None
 363         return val
 364
 365     def get_choices(self, include_blank=True, blank_choice=BLANK_CHOICE_DASH):
 366         "Returns a list of tuples used as SelectField choices for this field."
 367         first_choice = include_blank and blank_choice or []
 368         if self.choices:
 369             return first_choice + list(self.choices)
 370         rel_model = self.rel.to
 371         if hasattr(self.rel, 'get_related_field'):
 372             lst = [(getattr(x, self.rel.get_related_field().attname), smart_unicode(x)) for x in rel_model._default_manager.complex_filter(self.rel.limit_choices_to)]
 373         else:
 374             lst = [(x._get_pk_val(), smart_unicode(x)) for x in rel_model._default_manager.complex_filter(self.rel.limit_choices_to)]
 375         return first_choice + lst
 376
 377     def get_choices_default(self):
 378         if self.radio_admin:
 379             return self.get_choices(include_blank=self.blank, blank_choice=BLANK_CHOICE_NONE)
 380         else:
 381             return self.get_choices()
 382
 383     def _get_val_from_obj(self, obj):
 384         if obj:
 385             return getattr(obj, self.attname)
 386         else:
 387             return self.get_default()
 388
 389     def flatten_data(self, follow, obj=None):
 390         """
 391         Returns a dictionary mapping the field's manipulator field names to its
 392         "flattened" string values for the admin view. obj is the instance to
 393         extract the values from.
 394         """
 395         return {self.attname: self._get_val_from_obj(obj)}
 396
 397     def get_follow(self, override=None):
 398         if override != None:
 399             return override
 400         else:
 401             return self.editable
 402
 403     def bind(self, fieldmapping, original, bound_field_class):
 404         return bound_field_class(self, fieldmapping, original)
 405
 406     def _get_choices(self):
 407         if hasattr(self._choices, 'next'):
 408             choices, self._choices = tee(self._choices)
 409             return choices
 410         else:
 411             return self._choices
 412     choices = property(_get_choices)
 413
 414     def save_form_data(self, instance, data):
 415         setattr(instance, self.name, data)
 416
 417     def formfield(self, form_class=forms.CharField, **kwargs):
 418         "Returns a django.newforms.Field instance for this database Field."
 419         defaults = {'required': not self.blank, 'label': capfirst(self.verbose_name), 'help_text': self.help_text}
 420         if self.choices:
 421             defaults['widget'] = forms.Select(choices=self.get_choices(include_blank=self.blank or not (self.has_default() or 'initial' in kwargs)))
 422         if self.has_default():
 423             defaults['initial'] = self.get_default()
 424         defaults.update(kwargs)
 425         return form_class(**defaults)
 426
 427     def value_from_object(self, obj):
 428         "Returns the value of this field in the given model instance."
 429         return getattr(obj, self.attname)
 430
 431 class AutoField(Field):
 432     empty_strings_allowed = False
 433     def __init__(self, *args, **kwargs):
 434         assert kwargs.get('primary_key', False) is True, "%ss must have primary_key=True." % self.__class__.__name__
 435         kwargs['blank'] = True
 436         Field.__init__(self, *args, **kwargs)
 437
 438     def to_python(self, value):
 439         if value is None:
 440             return value
 441         try:
 442             return int(value)
 443         except (TypeError, ValueError):
 444             raise validators.ValidationError, _("This value must be an integer.")
 445
 446     def get_manipulator_fields(self, opts, manipulator, change, name_prefix='', rel=False, follow=True):
 447         if not rel:
 448             return [] # Don't add a FormField unless it's in a related context.
 449         return Field.get_manipulator_fields(self, opts, manipulator, change, name_prefix, rel, follow)
 450
 451     def get_manipulator_field_objs(self):
 452         return [oldforms.HiddenField]
 453
 454     def get_manipulator_new_data(self, new_data, rel=False):
 455         # Never going to be called
 456         # Not in main change pages
 457         # ignored in related context
 458         if not rel:
 459             return None
 460         return Field.get_manipulator_new_data(self, new_data, rel)
 461
 462     def contribute_to_class(self, cls, name):
 463         assert not cls._meta.has_auto_field, "A model can't have more than one AutoField."
 464         super(AutoField, self).contribute_to_class(cls, name)
 465         cls._meta.has_auto_field = True
 466         cls._meta.auto_field = self
 467
 468     def formfield(self, **kwargs):
 469         return None
 470
 471 class BooleanField(Field):
 472     def __init__(self, *args, **kwargs):
 473         kwargs['blank'] = True
 474         Field.__init__(self, *args, **kwargs)
 475
 476     def get_internal_type(self):
 477         return "BooleanField"
 478
 479     def to_python(self, value):
 480         if value in (True, False): return value
 481         if value in ('t', 'True', '1'): return True
 482         if value in ('f', 'False', '0'): return False
 483         raise validators.ValidationError, _("This value must be either True or False.")
 484
 485     def get_manipulator_field_objs(self):
 486         return [oldforms.CheckboxField]
 487
 488     def formfield(self, **kwargs):
 489         defaults = {'form_class': forms.BooleanField}
 490         defaults.update(kwargs)
 491         return super(BooleanField, self).formfield(**defaults)
 492
 493 class CharField(Field):
 494     def get_manipulator_field_objs(self):
 495         return [oldforms.TextField]
 496
 497     def get_internal_type(self):
 498         return "CharField"
 499
 500     def to_python(self, value):
 501         if isinstance(value, basestring):
 502             return value
 503         if value is None:
 504             if self.null:
 505                 return value
 506             else:
 507                 raise validators.ValidationError, ugettext_lazy("This field cannot be null.")
 508         return smart_unicode(value)
 509
 510     def formfield(self, **kwargs):
 511         defaults = {'max_length': self.max_length}
 512         defaults.update(kwargs)
 513         return super(CharField, self).formfield(**defaults)
 514
 515 # TODO: Maybe move this into contrib, because it's specialized.
 516 class CommaSeparatedIntegerField(CharField):
 517     def get_manipulator_field_objs(self):
 518         return [oldforms.CommaSeparatedIntegerField]
 519
 520 class DateField(Field):
 521     empty_strings_allowed = False
 522     def __init__(self, verbose_name=None, name=None, auto_now=False, auto_now_add=False, **kwargs):
 523         self.auto_now, self.auto_now_add = auto_now, auto_now_add
 524         #HACKs : auto_now_add/auto_now should be done as a default or a pre_save.
 525         if auto_now or auto_now_add:
 526             kwargs['editable'] = False
 527             kwargs['blank'] = True
 528         Field.__init__(self, verbose_name, name, **kwargs)
 529
 530     def get_internal_type(self):
 531         return "DateField"
 532
 533     def to_python(self, value):
 534         if value is None:
 535             return value
 536         if isinstance(value, datetime.datetime):
 537             return value.date()
 538         if isinstance(value, datetime.date):
 539             return value
 540         validators.isValidANSIDate(value, None)
 541         try:
 542             return datetime.date(*time.strptime(value, '%Y-%m-%d')[:3])
 543         except ValueError:
 544             raise validators.ValidationError, _('Enter a valid date in YYYY-MM-DD format.')
 545
 546     def get_db_prep_lookup(self, lookup_type, value):
 547         if lookup_type == 'range':
 548             value = [smart_unicode(v) for v in value]
 549         elif lookup_type in ('exact', 'gt', 'gte', 'lt', 'lte') and hasattr(value, 'strftime'):
 550             value = value.strftime('%Y-%m-%d')
 551         else:
 552             value = smart_unicode(value)
 553         return Field.get_db_prep_lookup(self, lookup_type, value)
 554
 555     def pre_save(self, model_instance, add):
 556         if self.auto_now or (self.auto_now_add and add):
 557             value = datetime.datetime.now()
 558             setattr(model_instance, self.attname, value)
 559             return value
 560         else:
 561             return super(DateField, self).pre_save(model_instance, add)
 562
 563     def contribute_to_class(self, cls, name):
 564         super(DateField,self).contribute_to_class(cls, name)
 565         if not self.null:
 566             setattr(cls, 'get_next_by_%s' % self.name,
 567                 curry(cls._get_next_or_previous_by_FIELD, field=self, is_next=True))
 568             setattr(cls, 'get_previous_by_%s' % self.name,
 569                 curry(cls._get_next_or_previous_by_FIELD, field=self, is_next=False))
 570
 571     # Needed because of horrible auto_now[_add] behaviour wrt. editable
 572     def get_follow(self, override=None):
 573         if override != None:
 574             return override
 575         else:
 576             return self.editable or self.auto_now or self.auto_now_add
 577
 578     def get_db_prep_save(self, value):
 579         # Casts dates into string format for entry into database.
 580         if value is not None:
 581             try:
 582                 value = value.strftime('%Y-%m-%d')
 583             except AttributeError:
 584                 # If value is already a string it won't have a strftime method,
 585                 # so we'll just let it pass through.
 586                 pass
 587         return Field.get_db_prep_save(self, value)
 588
 589     def get_manipulator_field_objs(self):
 590         return [oldforms.DateField]
 591
 592     def flatten_data(self, follow, obj=None):
 593         val = self._get_val_from_obj(obj)
 594         return {self.attname: (val is not None and val.strftime("%Y-%m-%d") or '')}
 595
 596     def formfield(self, **kwargs):
 597         defaults = {'form_class': forms.DateField}
 598         defaults.update(kwargs)
 599         return super(DateField, self).formfield(**defaults)
 600
 601 class DateTimeField(DateField):
 602     def get_internal_type(self):
 603         return "DateTimeField"
 604
 605     def to_python(self, value):
 606         if value is None:
 607             return value
 608         if isinstance(value, datetime.datetime):
 609             return value
 610         if isinstance(value, datetime.date):
 611             return datetime.datetime(value.year, value.month, value.day)
 612         try: # Seconds are optional, so try converting seconds first.
 613             return datetime.datetime(*time.strptime(value, '%Y-%m-%d %H:%M:%S')[:6])
 614         except ValueError:
 615             try: # Try without seconds.
 616                 return datetime.datetime(*time.strptime(value, '%Y-%m-%d %H:%M')[:5])
 617             except ValueError: # Try without hour/minutes/seconds.
 618                 try:
 619                     return datetime.datetime(*time.strptime(value, '%Y-%m-%d')[:3])
 620                 except ValueError:
 621                     raise validators.ValidationError, _('Enter a valid date/time in YYYY-MM-DD HH:MM format.')
 622
 623     def get_db_prep_save(self, value):
 624         # Casts dates into string format for entry into database.
 625         if value is not None:
 626             # MySQL will throw a warning if microseconds are given, because it
 627             # doesn't support microseconds.
 628             if settings.DATABASE_ENGINE == 'mysql' and hasattr(value, 'microsecond'):
 629                 value = value.replace(microsecond=0)
 630             value = smart_unicode(value)
 631         return Field.get_db_prep_save(self, value)
 632
 633     def get_db_prep_lookup(self, lookup_type, value):
 634         if lookup_type == 'range':
 635             value = [smart_unicode(v) for v in value]
 636         else:
 637             value = smart_unicode(value)
 638         return Field.get_db_prep_lookup(self, lookup_type, value)
 639
 640     def get_manipulator_field_objs(self):
 641         return [oldforms.DateField, oldforms.TimeField]
 642
 643     def get_manipulator_field_names(self, name_prefix):
 644         return [name_prefix + self.name + '_date', name_prefix + self.name + '_time']
 645
 646     def get_manipulator_new_data(self, new_data, rel=False):
 647         date_field, time_field = self.get_manipulator_field_names('')
 648         if rel:
 649             d = new_data.get(date_field, [None])[0]
 650             t = new_data.get(time_field, [None])[0]
 651         else:
 652             d = new_data.get(date_field, None)
 653             t = new_data.get(time_field, None)
 654         if d is not None and t is not None:
 655             return datetime.datetime.combine(d, t)
 656         return self.get_default()
 657
 658     def flatten_data(self,follow, obj = None):
 659         val = self._get_val_from_obj(obj)
 660         date_field, time_field = self.get_manipulator_field_names('')
 661         return {date_field: (val is not None and val.strftime("%Y-%m-%d") or ''),
 662                 time_field: (val is not None and val.strftime("%H:%M:%S") or '')}
 663
 664     def formfield(self, **kwargs):
 665         defaults = {'form_class': forms.DateTimeField}
 666         defaults.update(kwargs)
 667         return super(DateTimeField, self).formfield(**defaults)
 668
 669 class DecimalField(Field):
 670     empty_strings_allowed = False
 671     def __init__(self, verbose_name=None, name=None, max_digits=None, decimal_places=None, **kwargs):
 672         self.max_digits, self.decimal_places = max_digits, decimal_places
 673         Field.__init__(self, verbose_name, name, **kwargs)
 674
 675     def get_internal_type(self):
 676         return "DecimalField"
 677
 678     def to_python(self, value):
 679         if value is None:
 680             return value
 681         try:
 682             return decimal.Decimal(value)
 683         except decimal.InvalidOperation:
 684             raise validators.ValidationError(
 685                 _("This value must be a decimal number."))
 686
 687     def _format(self, value):
 688         if isinstance(value, basestring):
 689             return value
 690         else:
 691             return self.format_number(value)
 692
 693     def format_number(self, value):
 694         """
 695         Formats a number into a string with the requisite number of digits and
 696         decimal places.
 697         """
 698         num_chars = self.max_digits
 699         # Allow for a decimal point
 700         if self.decimal_places > 0:
 701             num_chars += 1
 702         # Allow for a minus sign
 703         if value < 0:
 704             num_chars += 1
 705
 706         return u"%.*f" % (self.decimal_places, value)
 707
 708     def get_db_prep_save(self, value):
 709         if value is not None:
 710             value = self._format(value)
 711         return super(DecimalField, self).get_db_prep_save(value)
 712
 713     def get_db_prep_lookup(self, lookup_type, value):
 714         if lookup_type == 'range':
 715             value = [self._format(v) for v in value]
 716         else:
 717             value = self._format(value)
 718         return super(DecimalField, self).get_db_prep_lookup(lookup_type, value)
 719
 720     def get_manipulator_field_objs(self):
 721         return [curry(oldforms.DecimalField, max_digits=self.max_digits, decimal_places=self.decimal_places)]
 722
 723     def formfield(self, **kwargs):
 724         defaults = {
 725             'max_digits': self.max_digits,
 726             'decimal_places': self.decimal_places,
 727             'form_class': forms.DecimalField,
 728         }
 729         defaults.update(kwargs)
 730         return super(DecimalField, self).formfield(**defaults)
 731
 732 class EmailField(CharField):
 733     def __init__(self, *args, **kwargs):
 734         kwargs['max_length'] = kwargs.get('max_length', 75)
 735         CharField.__init__(self, *args, **kwargs)
 736
 737     def get_manipulator_field_objs(self):
 738         return [oldforms.EmailField]
 739
 740     def validate(self, field_data, all_data):
 741         validators.isValidEmail(field_data, all_data)
 742
 743     def formfield(self, **kwargs):
 744         defaults = {'form_class': forms.EmailField}
 745         defaults.update(kwargs)
 746         return super(EmailField, self).formfield(**defaults)
 747
 748 class FileField(Field):
 749     def __init__(self, verbose_name=None, name=None, upload_to='', **kwargs):
 750         self.upload_to = upload_to
 751         kwargs['max_length'] = kwargs.get('max_length', 100)
 752         Field.__init__(self, verbose_name, name, **kwargs)
 753
 754     def get_internal_type(self):
 755         return "FileField"
 756
 757     def get_db_prep_save(self, value):
 758         "Returns field's value prepared for saving into a database."
 759         # Need to convert UploadedFile objects provided via a form to unicode for database insertion
 760         if value is None:
 761             return None
 762         return unicode(value)
 763
 764     def get_manipulator_fields(self, opts, manipulator, change, name_prefix='', rel=False, follow=True):
 765         field_list = Field.get_manipulator_fields(self, opts, manipulator, change, name_prefix, rel, follow)
 766         if not self.blank:
 767             if rel:
 768                 # This validator makes sure FileFields work in a related context.
 769                 class RequiredFileField(object):
 770                     def __init__(self, other_field_names, other_file_field_name):
 771                         self.other_field_names = other_field_names
 772                         self.other_file_field_name = other_file_field_name
 773                         self.always_test = True
 774                     def __call__(self, field_data, all_data):
 775                         if not all_data.get(self.other_file_field_name, False):
 776                             c = validators.RequiredIfOtherFieldsGiven(self.other_field_names, ugettext_lazy("This field is required."))
 777                             c(field_data, all_data)
 778                 # First, get the core fields, if any.
 779                 core_field_names = []
 780                 for f in opts.fields:
 781                     if f.core and f != self:
 782                         core_field_names.extend(f.get_manipulator_field_names(name_prefix))
 783                 # Now, if there are any, add the validator to this FormField.
 784                 if core_field_names:
 785                     field_list[0].validator_list.append(RequiredFileField(core_field_names, field_list[1].field_name))
 786             else:
 787                 v = validators.RequiredIfOtherFieldNotGiven(field_list[1].field_name, ugettext_lazy("This field is required."))
 788                 v.always_test = True
 789                 field_list[0].validator_list.append(v)
 790                 field_list[0].is_required = field_list[1].is_required = False
 791
 792         # If the raw path is passed in, validate it's under the MEDIA_ROOT.
 793         def isWithinMediaRoot(field_data, all_data):
 794             f = os.path.abspath(os.path.join(settings.MEDIA_ROOT, field_data))
 795             if not f.startswith(os.path.abspath(os.path.normpath(settings.MEDIA_ROOT))):
 796                 raise validators.ValidationError, _("Enter a valid filename.")
 797         field_list[1].validator_list.append(isWithinMediaRoot)
 798         return field_list
 799
 800     def contribute_to_class(self, cls, name):
 801         super(FileField, self).contribute_to_class(cls, name)
 802         setattr(cls, 'get_%s_filename' % self.name, curry(cls._get_FIELD_filename, field=self))
 803         setattr(cls, 'get_%s_url' % self.name, curry(cls._get_FIELD_url, field=self))
 804         setattr(cls, 'get_%s_size' % self.name, curry(cls._get_FIELD_size, field=self))
 805         setattr(cls, 'save_%s_file' % self.name, lambda instance, filename, raw_contents, save=True: instance._save_FIELD_file(self, filename, raw_contents, save))
 806         dispatcher.connect(self.delete_file, signal=signals.post_delete, sender=cls)
 807
 808     def delete_file(self, instance):
 809         if getattr(instance, self.attname):
 810             file_name = getattr(instance, 'get_%s_filename' % self.name)()
 811             # If the file exists and no other object of this type references it,
 812             # delete it from the filesystem.
 813             if os.path.exists(file_name) and \
 814                 not instance.__class__._default_manager.filter(**{'%s__exact' % self.name: getattr(instance, self.attname)}):
 815                 os.remove(file_name)
 816
 817     def get_manipulator_field_objs(self):
 818         return [oldforms.FileUploadField, oldforms.HiddenField]
 819
 820     def get_manipulator_field_names(self, name_prefix):
 821         return [name_prefix + self.name + '_file', name_prefix + self.name]
 822
 823     def save_file(self, new_data, new_object, original_object, change, rel, save=True):
 824         upload_field_name = self.get_manipulator_field_names('')[0]
 825         if new_data.get(upload_field_name, False):
 826             func = getattr(new_object, 'save_%s_file' % self.name)
 827             if rel:
 828                 func(new_data[upload_field_name][0]["filename"], new_data[upload_field_name][0]["content"], save)
 829             else:
 830                 func(new_data[upload_field_name]["filename"], new_data[upload_field_name]["content"], save)
 831
 832     def get_directory_name(self):
 833         return os.path.normpath(force_unicode(datetime.datetime.now().strftime(smart_str(self.upload_to))))
 834
 835     def get_filename(self, filename):
 836         from django.utils.text import get_valid_filename
 837         f = os.path.join(self.get_directory_name(), get_valid_filename(os.path.basename(filename)))
 838         return os.path.normpath(f)
 839
 840     def save_form_data(self, instance, data):
 841         from django.newforms.fields import UploadedFile
 842         if data and isinstance(data, UploadedFile):
 843             getattr(instance, "save_%s_file" % self.name)(data.filename, data.content, save=False)
 844
 845     def formfield(self, **kwargs):
 846         defaults = {'form_class': forms.FileField}
 847         # If a file has been provided previously, then the form doesn't require
 848         # that a new file is provided this time.
 849         # The code to mark the form field as not required is used by
 850         # form_for_instance, but can probably be removed once form_for_instance
 851         # is gone. ModelForm uses a different method to check for an existing file.
 852         if 'initial' in kwargs:
 853             defaults['required'] = False
 854         defaults.update(kwargs)
 855         return super(FileField, self).formfield(**defaults)
 856
 857 class FilePathField(Field):
 858     def __init__(self, verbose_name=None, name=None, path='', match=None, recursive=False, **kwargs):
 859         self.path, self.match, self.recursive = path, match, recursive
 860         kwargs['max_length'] = kwargs.get('max_length', 100)
 861         Field.__init__(self, verbose_name, name, **kwargs)
 862
 863     def formfield(self, **kwargs):
 864         defaults = {
 865             'path': self.path,
 866             'match': self.match,
 867             'recursive': self.recursive,
 868             'form_class': forms.FilePathField,
 869         }
 870         defaults.update(kwargs)
 871         return super(FilePathField, self).formfield(**defaults)
 872
 873     def get_manipulator_field_objs(self):
 874         return [curry(oldforms.FilePathField, path=self.path, match=self.match, recursive=self.recursive)]
 875
 876     def get_internal_type(self):
 877         return "FilePathField"
 878
 879 class FloatField(Field):
 880     empty_strings_allowed = False
 881
 882     def get_manipulator_field_objs(self):
 883         return [oldforms.FloatField]
 884
 885     def get_internal_type(self):
 886         return "FloatField"
 887
 888     def formfield(self, **kwargs):
 889         defaults = {'form_class': forms.FloatField}
 890         defaults.update(kwargs)
 891         return super(FloatField, self).formfield(**defaults)
 892
 893 class ImageField(FileField):
 894     def __init__(self, verbose_name=None, name=None, width_field=None, height_field=None, **kwargs):
 895         self.width_field, self.height_field = width_field, height_field
 896         FileField.__init__(self, verbose_name, name, **kwargs)
 897
 898     def get_manipulator_field_objs(self):
 899         return [oldforms.ImageUploadField, oldforms.HiddenField]
 900
 901     def contribute_to_class(self, cls, name):
 902         super(ImageField, self).contribute_to_class(cls, name)
 903         # Add get_BLAH_width and get_BLAH_height methods, but only if the
 904         # image field doesn't have width and height cache fields.
 905         if not self.width_field:
 906             setattr(cls, 'get_%s_width' % self.name, curry(cls._get_FIELD_width, field=self))
 907         if not self.height_field:
 908             setattr(cls, 'get_%s_height' % self.name, curry(cls._get_FIELD_height, field=self))
 909
 910     def get_internal_type(self):
 911         return "ImageField"
 912
 913     def save_file(self, new_data, new_object, original_object, change, rel, save=True):
 914         FileField.save_file(self, new_data, new_object, original_object, change, rel, save)
 915         # If the image has height and/or width field(s) and they haven't
 916         # changed, set the width and/or height field(s) back to their original
 917         # values.
 918         if change and (self.width_field or self.height_field) and save:
 919             if self.width_field:
 920                 setattr(new_object, self.width_field, getattr(original_object, self.width_field))
 921             if self.height_field:
 922                 setattr(new_object, self.height_field, getattr(original_object, self.height_field))
 923             new_object.save()
 924
 925     def formfield(self, **kwargs):
 926         defaults = {'form_class': forms.ImageField}
 927         defaults.update(kwargs)
 928         return super(ImageField, self).formfield(**defaults)
 929
 930 class IntegerField(Field):
 931     empty_strings_allowed = False
 932     def get_manipulator_field_objs(self):
 933         return [oldforms.IntegerField]
 934
 935     def get_internal_type(self):
 936         return "IntegerField"
 937
 938     def formfield(self, **kwargs):
 939         defaults = {'form_class': forms.IntegerField}
 940         defaults.update(kwargs)
 941         return super(IntegerField, self).formfield(**defaults)
 942
 943 class IPAddressField(Field):
 944     empty_strings_allowed = False
 945     def __init__(self, *args, **kwargs):
 946         kwargs['max_length'] = 15
 947         Field.__init__(self, *args, **kwargs)
 948
 949     def get_manipulator_field_objs(self):
 950         return [oldforms.IPAddressField]
 951
 952     def get_internal_type(self):
 953         return "IPAddressField"
 954
 955     def validate(self, field_data, all_data):
 956         validators.isValidIPAddress4(field_data, None)
 957
 958     def formfield(self, **kwargs):
 959         defaults = {'form_class': forms.IPAddressField}
 960         defaults.update(kwargs)
 961         return super(IPAddressField, self).formfield(**defaults)
 962
 963 class NullBooleanField(Field):
 964     empty_strings_allowed = False
 965     def __init__(self, *args, **kwargs):
 966         kwargs['null'] = True
 967         Field.__init__(self, *args, **kwargs)
 968
 969     def get_internal_type(self):
 970         return "NullBooleanField"
 971
 972     def to_python(self, value):
 973         if value in (None, True, False): return value
 974         if value in ('None'): return None
 975         if value in ('t', 'True', '1'): return True
 976         if value in ('f', 'False', '0'): return False
 977         raise validators.ValidationError, _("This value must be either None, True or False.")
 978
 979     def get_manipulator_field_objs(self):
 980         return [oldforms.NullBooleanField]
 981
 982     def formfield(self, **kwargs):
 983         defaults = {'form_class': forms.NullBooleanField}
 984         defaults.update(kwargs)
 985         return super(NullBooleanField, self).formfield(**defaults)
 986
 987 class PhoneNumberField(IntegerField):
 988     def get_manipulator_field_objs(self):
 989         return [oldforms.PhoneNumberField]
 990
 991     def get_internal_type(self):
 992         return "PhoneNumberField"
 993
 994     def validate(self, field_data, all_data):
 995         validators.isValidPhone(field_data, all_data)
 996
 997     def formfield(self, **kwargs):
 998         from django.contrib.localflavor.us.forms import USPhoneNumberField
 999         defaults = {'form_class': USPhoneNumberField}
1000         defaults.update(kwargs)
1001         return super(PhoneNumberField, self).formfield(**defaults)
1002
1003 class PositiveIntegerField(IntegerField):
1004     def get_manipulator_field_objs(self):
1005         return [oldforms.PositiveIntegerField]
1006
1007     def get_internal_type(self):
1008         return "PositiveIntegerField"
1009
1010     def formfield(self, **kwargs):
1011         defaults = {'min_value': 0}
1012         defaults.update(kwargs)
1013         return super(PositiveIntegerField, self).formfield(**defaults)
1014
1015 class PositiveSmallIntegerField(IntegerField):
1016     def get_manipulator_field_objs(self):
1017         return [oldforms.PositiveSmallIntegerField]
1018
1019     def get_internal_type(self):
1020         return "PositiveSmallIntegerField"
1021
1022     def formfield(self, **kwargs):
1023         defaults = {'min_value': 0}
1024         defaults.update(kwargs)
1025         return super(PositiveSmallIntegerField, self).formfield(**defaults)
1026
1027 class SlugField(CharField):
1028     def __init__(self, *args, **kwargs):
1029         kwargs['max_length'] = kwargs.get('max_length', 50)
1030         kwargs.setdefault('validator_list', []).append(validators.isSlug)
1031         # Set db_index=True unless it's been set manually.
1032         if 'db_index' not in kwargs:
1033             kwargs['db_index'] = True
1034         super(SlugField, self).__init__(*args, **kwargs)
1035
1036     def get_internal_type(self):
1037         return "SlugField"
1038
1039 class SmallIntegerField(IntegerField):
1040     def get_manipulator_field_objs(self):
1041         return [oldforms.SmallIntegerField]
1042
1043     def get_internal_type(self):
1044         return "SmallIntegerField"
1045
1046 class TextField(Field):
1047     def get_manipulator_field_objs(self):
1048         return [oldforms.LargeTextField]
1049
1050     def get_internal_type(self):
1051         return "TextField"
1052
1053     def formfield(self, **kwargs):
1054         defaults = {'widget': forms.Textarea}
1055         defaults.update(kwargs)
1056         return super(TextField, self).formfield(**defaults)
1057
1058 class TimeField(Field):
1059     empty_strings_allowed = False
1060     def __init__(self, verbose_name=None, name=None, auto_now=False, auto_now_add=False, **kwargs):
1061         self.auto_now, self.auto_now_add = auto_now, auto_now_add
1062         if auto_now or auto_now_add:
1063             kwargs['editable'] = False
1064         Field.__init__(self, verbose_name, name, **kwargs)
1065
1066     def get_internal_type(self):
1067         return "TimeField"
1068
1069     def get_db_prep_lookup(self, lookup_type, value):
1070         if settings.DATABASE_ENGINE == 'oracle':
1071             # Oracle requires a date in order to parse.
1072             def prep(value):
1073                 if isinstance(value, datetime.time):
1074                     value = datetime.datetime.combine(datetime.date(1900, 1, 1), value)
1075                 return smart_unicode(value)
1076         else:
1077             prep = smart_unicode
1078         if lookup_type == 'range':
1079             value = [prep(v) for v in value]
1080         else:
1081             value = prep(value)
1082         return Field.get_db_prep_lookup(self, lookup_type, value)
1083
1084     def pre_save(self, model_instance, add):
1085         if self.auto_now or (self.auto_now_add and add):
1086             value = datetime.datetime.now().time()
1087             setattr(model_instance, self.attname, value)
1088             return value
1089         else:
1090             return super(TimeField, self).pre_save(model_instance, add)
1091
1092     def get_db_prep_save(self, value):
1093         # Casts dates into string format for entry into database.
1094         if value is not None:
1095             # MySQL will throw a warning if microseconds are given, because it
1096             # doesn't support microseconds.
1097             if settings.DATABASE_ENGINE == 'mysql' and hasattr(value, 'microsecond'):
1098                 value = value.replace(microsecond=0)
1099             if settings.DATABASE_ENGINE == 'oracle':
1100                 # cx_Oracle expects a datetime.datetime to persist into TIMESTAMP field.
1101                 if isinstance(value, datetime.time):
1102                     value = datetime.datetime(1900, 1, 1, value.hour, value.minute,
1103                                               value.second, value.microsecond)
1104                 elif isinstance(value, basestring):
1105                     value = datetime.datetime(*(time.strptime(value, '%H:%M:%S')[:6]))
1106             else:
1107                 value = smart_unicode(value)
1108         return Field.get_db_prep_save(self, value)
1109
1110     def get_manipulator_field_objs(self):
1111         return [oldforms.TimeField]
1112
1113     def flatten_data(self,follow, obj = None):
1114         val = self._get_val_from_obj(obj)
1115         return {self.attname: (val is not None and val.strftime("%H:%M:%S") or '')}
1116
1117     def formfield(self, **kwargs):
1118         defaults = {'form_class': forms.TimeField}
1119         defaults.update(kwargs)
1120         return super(TimeField, self).formfield(**defaults)
1121
1122 class URLField(CharField):
1123     def __init__(self, verbose_name=None, name=None, verify_exists=True, **kwargs):
1124         kwargs['max_length'] = kwargs.get('max_length', 200)
1125         if verify_exists:
1126             kwargs.setdefault('validator_list', []).append(validators.isExistingURL)
1127         self.verify_exists = verify_exists
1128         CharField.__init__(self, verbose_name, name, **kwargs)
1129
1130     def get_manipulator_field_objs(self):
1131         return [oldforms.URLField]
1132
1133     def formfield(self, **kwargs):
1134         defaults = {'form_class': forms.URLField, 'verify_exists': self.verify_exists}
1135         defaults.update(kwargs)
1136         return super(URLField, self).formfield(**defaults)
1137
1138 class USStateField(Field):
1139     def get_manipulator_field_objs(self):
1140         return [oldforms.USStateField]
1141
1142     def get_internal_type(self):
1143         return "USStateField"
1144
1145     def formfield(self, **kwargs):
1146         from django.contrib.localflavor.us.forms import USStateSelect
1147         defaults = {'widget': USStateSelect}
1148         defaults.update(kwargs)
1149         return super(USStateField, self).formfield(**defaults)
1150
1151 class XMLField(TextField):
1152     def __init__(self, verbose_name=None, name=None, schema_path=None, **kwargs):
1153         self.schema_path = schema_path
1154         Field.__init__(self, verbose_name, name, **kwargs)
1155
1156     def get_manipulator_field_objs(self):
1157         return [curry(oldforms.XMLLargeTextField, schema_path=self.schema_path)]
1158
1159 class OrderingField(IntegerField):
1160     empty_strings_allowed=False
1161     def __init__(self, with_respect_to, **kwargs):
1162         self.wrt = with_respect_to
1163         kwargs['null'] = True
1164         IntegerField.__init__(self, **kwargs )
1165
1166     def get_manipulator_fields(self, opts, manipulator, change, name_prefix='', rel=False, follow=True):
1167         return [oldforms.HiddenField(name_prefix + self.name)]