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