Models Duration field ¶
See also
DurationField ¶
A field for storing periods of time - modeled in Python by timedelta.
When used on PostgreSQL, the data type used is an interval and on Oracle the data type is INTERVAL DAY(9) TO SECOND(6).
Otherwise a bigint of microseconds is used.
Note
Arithmetic with DurationField works in most cases. However on all databases other than PostgreSQL, comparing the value of a DurationField to arithmetic on DateTimeField instances will not work as expected.
Example ¶
class FicheTemps(models.Model):
"""La fiche de temps.
Le temps imputé dans une fiche de temps concerne:
- un employé
- un projet
- un jour
Une fiche de temps peut être dans l'état "FICHE_EN_CALCUL' dans le cas
où une tâche périodique met à jour le temps imputé.
$ python manage_dev.py shell_plus
>>> from datetime import datetime, timedelta
>>> from fiches_temps.models import FICHE_STATUS
>>> employe = Employe.objects.get(login='pvergain')
>>> employe
Out[4]: <Employe: Patrick VERGAIN>
>>> projet = Projet.objects.get(code_chrono='PSER5N001')
>>> projet
Out[5]: <Projet: PSER5N001>
>>> temps_impute=timedelta(seconds=1)
>>> fiches_temps = FicheTemps.objects.create(
employe=employe,
projet=projet,
created=timezone.now,
temps_impute=temps_impute,
etat=FICHE_STATUS['FICHE_EN_CALCUL']
)
>>> fiches_temps
Out[19]: <FicheTemps: FDT: PSER5N001/2016-02-26 14:28:30.494177 Patrick VERGAIN 0:00:01>
>>> liste_fiches_en_calcul_employe = FicheTemps.objects.all()\
.filter(created=now())\
.filter(etat=FICHE_STATUS['FICHE_EN_CALCUL'])\
.filter(employe=employe)
>>> les_fiches_en_calcul = FicheTemps.objects.all()\
.filter(etat=FICHE_STATUS['FICHE_EN_CALCUL'])
"""
class Meta:
managed = True
# Ancien nom de table sybase : 'TR_FICHE_TEMPS'
db_table = "fiche_temps"
verbose_name_plural = _("Fiches de temps")
ordering = ["-created"]
# https://docs.djangoproject.com/en/dev/ref/models/constraints/#uniqueconstraint
constraints = [
models.UniqueConstraint(
fields=["employe", "projet", "created"],
name="unique_employe_projet_created",
)
]
# https://docs.djangoproject.com/en/dev/ref/models/indexes/
indexes = [
models.Index(
fields=["employe", "projet", "created"],
name="employe_projet_created_index",
)
]
employe = models.ForeignKey(
"employes.Employe",
to_field="id",
limit_choices_to={"etat": StatusEmploye.EMPLOYE_ID3.value},
on_delete=models.CASCADE,
db_column="id_employe",
related_name="fiches_temps_employe",
related_query_name="fiche_temps_employe",
help_text=_("L'employé"),
verbose_name=_("L'employé"),
)
projet = models.ForeignKey(
"projets.Projet",
to_field="id",
db_column="id_projet",
related_name="fiches_temps_projet",
related_query_name="fiche_temps_projet",
on_delete=models.CASCADE,
help_text=_("Le projet sur lequel imputer le temps"),
verbose_name=_("Projet"),
)
# ancien nom sybase: temps
temps_impute = models.DurationField(
default=timedelta(hours=0),
help_text=_("Le temps impute"),
verbose_name=_("Temps imputé"),
)
commentaire = models.TextField(
default="", help_text=_("Commentaire"), verbose_name=_("Commentaire")
)
etat = models.PositiveSmallIntegerField(
choices=FICHE_STATUS,
# Valeur par défaut
default=FICHE_STATUS.FICHE_MODIFIABLE,
help_text=_("indique l'état de la fiche"),
verbose_name=_("Etat fiche"),
)
# https://docs.djangoproject.com/en/dev/ref/models/fields/#datetimefield
created = models.DateTimeField(
editable=True,
help_text=_("Date d'imputation"),
verbose_name=_("Date imputation"),
)
# https://docs.djangoproject.com/en/dev/ref/models/fields/#datetimefield
modified = models.DateTimeField(
null=True,
editable=True,
# auto_now=True,
help_text=_("Modifié le"),
verbose_name=_("Modifié le"),
)
def get_absolute_url(self):
"""
https://docs.djangoproject.com/en/dev/ref/class-based-views/generic-editing/
"""
return reverse("fiches_temps:detail", kwargs={"pk": self.pk})
def str_etat_fiche(self):
return FICHE_STATUS.for_value(self.etat).display
def __str__(self):
message = (
f"FDT: projet:{self.projet} created:{self.created} "
f"modified:{self.modified} employe:{self.employe} "
f"etat:{self.str_etat_fiche()} "
f"temps impute:{self.temps_impute}"
f"commentaire:{self.commentaire}"
)
return message
django.utils.parse_duration ¶
Models DurationField ¶
1 class DurationField(Field):
2 """
3 Store timedelta objects.
4 Use interval on PostgreSQL, INTERVAL DAY TO SECOND on Oracle, and bigint
5 of microseconds on other databases.
6 """
7 empty_strings_allowed = False
8 default_error_messages = {
9 'invalid': _('“%(value)s” value has an invalid format. It must be in '
10 '[DD] [[HH:]MM:]ss[.uuuuuu] format.')
11 }
12 description = _("Duration")
13
14 def get_internal_type(self):
15 return "DurationField"
16
17 def to_python(self, value):
18 if value is None:
19 return value
20 if isinstance(value, datetime.timedelta):
21 return value
22 try:
23 parsed = parse_duration(value)
24 except ValueError:
25 pass
26 else:
27 if parsed is not None:
28 return parsed
29
30 raise exceptions.ValidationError(
31 self.error_messages['invalid'],
32 code='invalid',
33 params={'value': value},
34 )
35
36 def get_db_prep_value(self, value, connection, prepared=False):
37 if connection.features.has_native_duration_field:
38 return value
39 if value is None:
40 return None
41 return duration_microseconds(value)
42
43 def get_db_converters(self, connection):
44 converters = []
45 if not connection.features.has_native_duration_field:
46 converters.append(connection.ops.convert_durationfield_value)
47 return converters + super().get_db_converters(connection)
48
49 def value_to_string(self, obj):
50 val = self.value_from_object(obj)
51 return '' if val is None else duration_string(val)
52
53 def formfield(self, **kwargs):
54 return super().formfield(**{
55 'form_class': forms.DurationField,
56 **kwargs,
57 })
django/db/models/fields/__init__.py ¶
1import collections.abc
2import copy
3import datetime
4import decimal
5import operator
6import uuid
7import warnings
8from base64 import b64decode, b64encode
9from functools import partialmethod, total_ordering
10
11from django import forms
12from django.apps import apps
13from django.conf import settings
14from django.core import checks, exceptions, validators
15from django.db import connection, connections, router
16from django.db.models.constants import LOOKUP_SEP
17from django.db.models.query_utils import DeferredAttribute, RegisterLookupMixin
18from django.utils import timezone
19from django.utils.datastructures import DictWrapper
20from django.utils.dateparse import (
21 parse_date,
22 parse_datetime,
23 parse_duration,
24 parse_time,
25)
26from django.utils.duration import duration_microseconds, duration_string
27from django.utils.functional import Promise, cached_property
28from django.utils.ipv6 import clean_ipv6_address
29from django.utils.itercompat import is_iterable
30from django.utils.text import capfirst
31from django.utils.translation import gettext_lazy as _
32
33__all__ = [
34 "AutoField",
35 "BLANK_CHOICE_DASH",
36 "BigAutoField",
37 "BigIntegerField",
38 "BinaryField",
39 "BooleanField",
40 "CharField",
41 "CommaSeparatedIntegerField",
42 "DateField",
43 "DateTimeField",
44 "DecimalField",
45 "DurationField",
46 "EmailField",
47 "Empty",
48 "Field",
49 "FilePathField",
50 "FloatField",
51 "GenericIPAddressField",
52 "IPAddressField",
53 "IntegerField",
54 "NOT_PROVIDED",
55 "NullBooleanField",
56 "PositiveBigIntegerField",
57 "PositiveIntegerField",
58 "PositiveSmallIntegerField",
59 "SlugField",
60 "SmallAutoField",
61 "SmallIntegerField",
62 "TextField",
63 "TimeField",
64 "URLField",
65 "UUIDField",
66]
67
68
69class Empty:
70 pass
71
72
73class NOT_PROVIDED:
74 pass
75
76
77# The values to use for "blank" in SelectFields. Will be appended to the start
78# of most "choices" lists.
79BLANK_CHOICE_DASH = [("", "---------")]
80
81
82def _load_field(app_label, model_name, field_name):
83 return apps.get_model(app_label, model_name)._meta.get_field(field_name)
84
85
86# A guide to Field parameters:
87#
88# * name: The name of the field specified in the model.
89# * attname: The attribute to use on the model object. This is the same as
90# "name", except in the case of ForeignKeys, where "_id" is
91# appended.
92# * db_column: The db_column specified in the model (or None).
93# * column: The database column for this field. This is the same as
94# "attname", except if db_column is specified.
95#
96# Code that introspects values, or does other dynamic things, should use
97# attname. For example, this gets the primary key value of object "obj":
98#
99# getattr(obj, opts.pk.attname)
100
101
102def _empty(of_cls):
103 new = Empty()
104 new.__class__ = of_cls
105 return new
106
107
108def return_None():
109 return None
110
111
112@total_ordering
113class Field(RegisterLookupMixin):
114 """Base class for all field types"""
115
116 # Designates whether empty strings fundamentally are allowed at the
117 # database level.
118 empty_strings_allowed = True
119 empty_values = list(validators.EMPTY_VALUES)
120
121 # These track each time a Field instance is created. Used to retain order.
122 # The auto_creation_counter is used for fields that Django implicitly
123 # creates, creation_counter is used for all user-specified fields.
124 creation_counter = 0
125 auto_creation_counter = -1
126 default_validators = [] # Default set of validators
127 default_error_messages = {
128 "invalid_choice": _("Value %(value)r is not a valid choice."),
129 "null": _("This field cannot be null."),
130 "blank": _("This field cannot be blank."),
131 "unique": _("%(model_name)s with this %(field_label)s " "already exists."),
132 # Translators: The 'lookup_type' is one of 'date', 'year' or 'month'.
133 # Eg: "Title must be unique for pub_date year"
134 "unique_for_date": _(
135 "%(field_label)s must be unique for "
136 "%(date_field_label)s %(lookup_type)s."
137 ),
138 }
139 system_check_deprecated_details = None
140 system_check_removed_details = None
141
142 # Field flags
143 hidden = False
144
145 many_to_many = None
146 many_to_one = None
147 one_to_many = None
148 one_to_one = None
149 related_model = None
150
151 descriptor_class = DeferredAttribute
152
153 # Generic field type description, usually overridden by subclasses
154 def _description(self):
155 return _("Field of type: %(field_type)s") % {
156 "field_type": self.__class__.__name__
157 }
158
159 description = property(_description)
160
161 def __init__(
162 self,
163 verbose_name=None,
164 name=None,
165 primary_key=False,
166 max_length=None,
167 unique=False,
168 blank=False,
169 null=False,
170 db_index=False,
171 rel=None,
172 default=NOT_PROVIDED,
173 editable=True,
174 serialize=True,
175 unique_for_date=None,
176 unique_for_month=None,
177 unique_for_year=None,
178 choices=None,
179 help_text="",
180 db_column=None,
181 db_tablespace=None,
182 auto_created=False,
183 validators=(),
184 error_messages=None,
185 ):
186 self.name = name
187 self.verbose_name = verbose_name # May be set by set_attributes_from_name
188 self._verbose_name = verbose_name # Store original for deconstruction
189 self.primary_key = primary_key
190 self.max_length, self._unique = max_length, unique
191 self.blank, self.null = blank, null
192 self.remote_field = rel
193 self.is_relation = self.remote_field is not None
194 self.default = default
195 self.editable = editable
196 self.serialize = serialize
197 self.unique_for_date = unique_for_date
198 self.unique_for_month = unique_for_month
199 self.unique_for_year = unique_for_year
200 if isinstance(choices, collections.abc.Iterator):
201 choices = list(choices)
202 self.choices = choices
203 self.help_text = help_text
204 self.db_index = db_index
205 self.db_column = db_column
206 self._db_tablespace = db_tablespace
207 self.auto_created = auto_created
208
209 # Adjust the appropriate creation counter, and save our local copy.
210 if auto_created:
211 self.creation_counter = Field.auto_creation_counter
212 Field.auto_creation_counter -= 1
213 else:
214 self.creation_counter = Field.creation_counter
215 Field.creation_counter += 1
216
217 self._validators = list(validators) # Store for deconstruction later
218
219 messages = {}
220 for c in reversed(self.__class__.__mro__):
221 messages.update(getattr(c, "default_error_messages", {}))
222 messages.update(error_messages or {})
223 self._error_messages = error_messages # Store for deconstruction later
224 self.error_messages = messages
225
226 def __str__(self):
227 """
228 Return "app_label.model_label.field_name" for fields attached to
229 models.
230 """
231 if not hasattr(self, "model"):
232 return super().__str__()
233 model = self.model
234 app = model._meta.app_label
235 return "%s.%s.%s" % (app, model._meta.object_name, self.name)
236
237 def __repr__(self):
238 """Display the module, class, and name of the field."""
239 path = "%s.%s" % (self.__class__.__module__, self.__class__.__qualname__)
240 name = getattr(self, "name", None)
241 if name is not None:
242 return "<%s: %s>" % (path, name)
243 return "<%s>" % path
244
245 def check(self, **kwargs):
246 return [
247 *self._check_field_name(),
248 *self._check_choices(),
249 *self._check_db_index(),
250 *self._check_null_allowed_for_primary_keys(),
251 *self._check_backend_specific_checks(**kwargs),
252 *self._check_validators(),
253 *self._check_deprecation_details(),
254 ]
255
256 def _check_field_name(self):
257 """
258 Check if field name is valid, i.e. 1) does not end with an
259 underscore, 2) does not contain "__" and 3) is not "pk".
260 """
261 if self.name.endswith("_"):
262 return [
263 checks.Error(
264 "Field names must not end with an underscore.",
265 obj=self,
266 id="fields.E001",
267 )
268 ]
269 elif LOOKUP_SEP in self.name:
270 return [
271 checks.Error(
272 'Field names must not contain "%s".' % (LOOKUP_SEP,),
273 obj=self,
274 id="fields.E002",
275 )
276 ]
277 elif self.name == "pk":
278 return [
279 checks.Error(
280 "'pk' is a reserved word that cannot be used as a field name.",
281 obj=self,
282 id="fields.E003",
283 )
284 ]
285 else:
286 return []
287
288 @classmethod
289 def _choices_is_value(cls, value):
290 return isinstance(value, (str, Promise)) or not is_iterable(value)
291
292 def _check_choices(self):
293 if not self.choices:
294 return []
295
296 if not is_iterable(self.choices) or isinstance(self.choices, str):
297 return [
298 checks.Error(
299 "'choices' must be an iterable (e.g., a list or tuple).",
300 obj=self,
301 id="fields.E004",
302 )
303 ]
304
305 choice_max_length = 0
306 # Expect [group_name, [value, display]]
307 for choices_group in self.choices:
308 try:
309 group_name, group_choices = choices_group
310 except (TypeError, ValueError):
311 # Containing non-pairs
312 break
313 try:
314 if not all(
315 self._choices_is_value(value) and self._choices_is_value(human_name)
316 for value, human_name in group_choices
317 ):
318 break
319 if self.max_length is not None and group_choices:
320 choice_max_length = max(
321 [
322 choice_max_length,
323 *(
324 len(value)
325 for value, _ in group_choices
326 if isinstance(value, str)
327 ),
328 ]
329 )
330 except (TypeError, ValueError):
331 # No groups, choices in the form [value, display]
332 value, human_name = group_name, group_choices
333 if not self._choices_is_value(value) or not self._choices_is_value(
334 human_name
335 ):
336 break
337 if self.max_length is not None and isinstance(value, str):
338 choice_max_length = max(choice_max_length, len(value))
339
340 # Special case: choices=['ab']
341 if isinstance(choices_group, str):
342 break
343 else:
344 if self.max_length is not None and choice_max_length > self.max_length:
345 return [
346 checks.Error(
347 "'max_length' is too small to fit the longest value "
348 "in 'choices' (%d characters)." % choice_max_length,
349 obj=self,
350 id="fields.E009",
351 ),
352 ]
353 return []
354
355 return [
356 checks.Error(
357 "'choices' must be an iterable containing "
358 "(actual value, human readable name) tuples.",
359 obj=self,
360 id="fields.E005",
361 )
362 ]
363
364 def _check_db_index(self):
365 if self.db_index not in (None, True, False):
366 return [
367 checks.Error(
368 "'db_index' must be None, True or False.",
369 obj=self,
370 id="fields.E006",
371 )
372 ]
373 else:
374 return []
375
376 def _check_null_allowed_for_primary_keys(self):
377 if (
378 self.primary_key
379 and self.null
380 and not connection.features.interprets_empty_strings_as_nulls
381 ):
382 # We cannot reliably check this for backends like Oracle which
383 # consider NULL and '' to be equal (and thus set up
384 # character-based fields a little differently).
385 return [
386 checks.Error(
387 "Primary keys must not have null=True.",
388 hint=(
389 "Set null=False on the field, or "
390 "remove primary_key=True argument."
391 ),
392 obj=self,
393 id="fields.E007",
394 )
395 ]
396 else:
397 return []
398
399 def _check_backend_specific_checks(self, databases=None, **kwargs):
400 if databases is None:
401 return []
402 app_label = self.model._meta.app_label
403 errors = []
404 for alias in databases:
405 if router.allow_migrate(
406 alias, app_label, model_name=self.model._meta.model_name
407 ):
408 errors.extend(connections[alias].validation.check_field(self, **kwargs))
409 return errors
410
411 def _check_validators(self):
412 errors = []
413 for i, validator in enumerate(self.validators):
414 if not callable(validator):
415 errors.append(
416 checks.Error(
417 "All 'validators' must be callable.",
418 hint=(
419 "validators[{i}] ({repr}) isn't a function or "
420 "instance of a validator class.".format(
421 i=i, repr=repr(validator),
422 )
423 ),
424 obj=self,
425 id="fields.E008",
426 )
427 )
428 return errors
429
430 def _check_deprecation_details(self):
431 if self.system_check_removed_details is not None:
432 return [
433 checks.Error(
434 self.system_check_removed_details.get(
435 "msg",
436 "%s has been removed except for support in historical "
437 "migrations." % self.__class__.__name__,
438 ),
439 hint=self.system_check_removed_details.get("hint"),
440 obj=self,
441 id=self.system_check_removed_details.get("id", "fields.EXXX"),
442 )
443 ]
444 elif self.system_check_deprecated_details is not None:
445 return [
446 checks.Warning(
447 self.system_check_deprecated_details.get(
448 "msg", "%s has been deprecated." % self.__class__.__name__
449 ),
450 hint=self.system_check_deprecated_details.get("hint"),
451 obj=self,
452 id=self.system_check_deprecated_details.get("id", "fields.WXXX"),
453 )
454 ]
455 return []
456
457 def get_col(self, alias, output_field=None):
458 if output_field is None:
459 output_field = self
460 if alias != self.model._meta.db_table or output_field != self:
461 from django.db.models.expressions import Col
462
463 return Col(alias, self, output_field)
464 else:
465 return self.cached_col
466
467 @cached_property
468 def cached_col(self):
469 from django.db.models.expressions import Col
470
471 return Col(self.model._meta.db_table, self)
472
473 def select_format(self, compiler, sql, params):
474 """
475 Custom format for select clauses. For example, GIS columns need to be
476 selected as AsText(table.col) on MySQL as the table.col data can't be
477 used by Django.
478 """
479 return sql, params
480
481 def deconstruct(self):
482 """
483 Return enough information to recreate the field as a 4-tuple:
484
485 * The name of the field on the model, if contribute_to_class() has
486 been run.
487 * The import path of the field, including the class:e.g.
488 django.db.models.IntegerField This should be the most portable
489 version, so less specific may be better.
490 * A list of positional arguments.
491 * A dict of keyword arguments.
492
493 Note that the positional or keyword arguments must contain values of
494 the following types (including inner values of collection types):
495
496 * None, bool, str, int, float, complex, set, frozenset, list, tuple,
497 dict
498 * UUID
499 * datetime.datetime (naive), datetime.date
500 * top-level classes, top-level functions - will be referenced by their
501 full import path
502 * Storage instances - these have their own deconstruct() method
503
504 This is because the values here must be serialized into a text format
505 (possibly new Python code, possibly JSON) and these are the only types
506 with encoding handlers defined.
507
508 There's no need to return the exact way the field was instantiated this
509 time, just ensure that the resulting field is the same - prefer keyword
510 arguments over positional ones, and omit parameters with their default
511 values.
512 """
513 # Short-form way of fetching all the default parameters
514 keywords = {}
515 possibles = {
516 "verbose_name": None,
517 "primary_key": False,
518 "max_length": None,
519 "unique": False,
520 "blank": False,
521 "null": False,
522 "db_index": False,
523 "default": NOT_PROVIDED,
524 "editable": True,
525 "serialize": True,
526 "unique_for_date": None,
527 "unique_for_month": None,
528 "unique_for_year": None,
529 "choices": None,
530 "help_text": "",
531 "db_column": None,
532 "db_tablespace": None,
533 "auto_created": False,
534 "validators": [],
535 "error_messages": None,
536 }
537 attr_overrides = {
538 "unique": "_unique",
539 "error_messages": "_error_messages",
540 "validators": "_validators",
541 "verbose_name": "_verbose_name",
542 "db_tablespace": "_db_tablespace",
543 }
544 equals_comparison = {"choices", "validators"}
545 for name, default in possibles.items():
546 value = getattr(self, attr_overrides.get(name, name))
547 # Unroll anything iterable for choices into a concrete list
548 if name == "choices" and isinstance(value, collections.abc.Iterable):
549 value = list(value)
550 # Do correct kind of comparison
551 if name in equals_comparison:
552 if value != default:
553 keywords[name] = value
554 else:
555 if value is not default:
556 keywords[name] = value
557 # Work out path - we shorten it for known Django core fields
558 path = "%s.%s" % (self.__class__.__module__, self.__class__.__qualname__)
559 if path.startswith("django.db.models.fields.related"):
560 path = path.replace("django.db.models.fields.related", "django.db.models")
561 elif path.startswith("django.db.models.fields.files"):
562 path = path.replace("django.db.models.fields.files", "django.db.models")
563 elif path.startswith("django.db.models.fields.proxy"):
564 path = path.replace("django.db.models.fields.proxy", "django.db.models")
565 elif path.startswith("django.db.models.fields"):
566 path = path.replace("django.db.models.fields", "django.db.models")
567 # Return basic info - other fields should override this.
568 return (self.name, path, [], keywords)
569
570 def clone(self):
571 """
572 Uses deconstruct() to clone a new copy of this Field.
573 Will not preserve any class attachments/attribute names.
574 """
575 name, path, args, kwargs = self.deconstruct()
576 return self.__class__(*args, **kwargs)
577
578 def __eq__(self, other):
579 # Needed for @total_ordering
580 if isinstance(other, Field):
581 return self.creation_counter == other.creation_counter
582 return NotImplemented
583
584 def __lt__(self, other):
585 # This is needed because bisect does not take a comparison function.
586 if isinstance(other, Field):
587 return self.creation_counter < other.creation_counter
588 return NotImplemented
589
590 def __hash__(self):
591 return hash(self.creation_counter)
592
593 def __deepcopy__(self, memodict):
594 # We don't have to deepcopy very much here, since most things are not
595 # intended to be altered after initial creation.
596 obj = copy.copy(self)
597 if self.remote_field:
598 obj.remote_field = copy.copy(self.remote_field)
599 if hasattr(self.remote_field, "field") and self.remote_field.field is self:
600 obj.remote_field.field = obj
601 memodict[id(self)] = obj
602 return obj
603
604 def __copy__(self):
605 # We need to avoid hitting __reduce__, so define this
606 # slightly weird copy construct.
607 obj = Empty()
608 obj.__class__ = self.__class__
609 obj.__dict__ = self.__dict__.copy()
610 return obj
611
612 def __reduce__(self):
613 """
614 Pickling should return the model._meta.fields instance of the field,
615 not a new copy of that field. So, use the app registry to load the
616 model and then the field back.
617 """
618 if not hasattr(self, "model"):
619 # Fields are sometimes used without attaching them to models (for
620 # example in aggregation). In this case give back a plain field
621 # instance. The code below will create a new empty instance of
622 # class self.__class__, then update its dict with self.__dict__
623 # values - so, this is very close to normal pickle.
624 state = self.__dict__.copy()
625 # The _get_default cached_property can't be pickled due to lambda
626 # usage.
627 state.pop("_get_default", None)
628 return _empty, (self.__class__,), state
629 return (
630 _load_field,
631 (self.model._meta.app_label, self.model._meta.object_name, self.name),
632 )
633
634 def get_pk_value_on_save(self, instance):
635 """
636 Hook to generate new PK values on save. This method is called when
637 saving instances with no primary key value set. If this method returns
638 something else than None, then the returned value is used when saving
639 the new instance.
640 """
641 if self.default:
642 return self.get_default()
643 return None
644
645 def to_python(self, value):
646 """
647 Convert the input value into the expected Python data type, raising
648 django.core.exceptions.ValidationError if the data can't be converted.
649 Return the converted value. Subclasses should override this.
650 """
651 return value
652
653 @cached_property
654 def validators(self):
655 """
656 Some validators can't be created at field initialization time.
657 This method provides a way to delay their creation until required.
658 """
659 return [*self.default_validators, *self._validators]
660
661 def run_validators(self, value):
662 if value in self.empty_values:
663 return
664
665 errors = []
666 for v in self.validators:
667 try:
668 v(value)
669 except exceptions.ValidationError as e:
670 if hasattr(e, "code") and e.code in self.error_messages:
671 e.message = self.error_messages[e.code]
672 errors.extend(e.error_list)
673
674 if errors:
675 raise exceptions.ValidationError(errors)
676
677 def validate(self, value, model_instance):
678 """
679 Validate value and raise ValidationError if necessary. Subclasses
680 should override this to provide validation logic.
681 """
682 if not self.editable:
683 # Skip validation for non-editable fields.
684 return
685
686 if self.choices is not None and value not in self.empty_values:
687 for option_key, option_value in self.choices:
688 if isinstance(option_value, (list, tuple)):
689 # This is an optgroup, so look inside the group for
690 # options.
691 for optgroup_key, optgroup_value in option_value:
692 if value == optgroup_key:
693 return
694 elif value == option_key:
695 return
696 raise exceptions.ValidationError(
697 self.error_messages["invalid_choice"],
698 code="invalid_choice",
699 params={"value": value},
700 )
701
702 if value is None and not self.null:
703 raise exceptions.ValidationError(self.error_messages["null"], code="null")
704
705 if not self.blank and value in self.empty_values:
706 raise exceptions.ValidationError(self.error_messages["blank"], code="blank")
707
708 def clean(self, value, model_instance):
709 """
710 Convert the value's type and run validation. Validation errors
711 from to_python() and validate() are propagated. Return the correct
712 value if no error is raised.
713 """
714 value = self.to_python(value)
715 self.validate(value, model_instance)
716 self.run_validators(value)
717 return value
718
719 def db_type_parameters(self, connection):
720 return DictWrapper(self.__dict__, connection.ops.quote_name, "qn_")
721
722 def db_check(self, connection):
723 """
724 Return the database column check constraint for this field, for the
725 provided connection. Works the same way as db_type() for the case that
726 get_internal_type() does not map to a preexisting model field.
727 """
728 data = self.db_type_parameters(connection)
729 try:
730 return (
731 connection.data_type_check_constraints[self.get_internal_type()] % data
732 )
733 except KeyError:
734 return None
735
736 def db_type(self, connection):
737 """
738 Return the database column data type for this field, for the provided
739 connection.
740 """
741 # The default implementation of this method looks at the
742 # backend-specific data_types dictionary, looking up the field by its
743 # "internal type".
744 #
745 # A Field class can implement the get_internal_type() method to specify
746 # which *preexisting* Django Field class it's most similar to -- i.e.,
747 # a custom field might be represented by a TEXT column type, which is
748 # the same as the TextField Django field type, which means the custom
749 # field's get_internal_type() returns 'TextField'.
750 #
751 # But the limitation of the get_internal_type() / data_types approach
752 # is that it cannot handle database column types that aren't already
753 # mapped to one of the built-in Django field types. In this case, you
754 # can implement db_type() instead of get_internal_type() to specify
755 # exactly which wacky database column type you want to use.
756 data = self.db_type_parameters(connection)
757 try:
758 return connection.data_types[self.get_internal_type()] % data
759 except KeyError:
760 return None
761
762 def rel_db_type(self, connection):
763 """
764 Return the data type that a related field pointing to this field should
765 use. For example, this method is called by ForeignKey and OneToOneField
766 to determine its data type.
767 """
768 return self.db_type(connection)
769
770 def cast_db_type(self, connection):
771 """Return the data type to use in the Cast() function."""
772 db_type = connection.ops.cast_data_types.get(self.get_internal_type())
773 if db_type:
774 return db_type % self.db_type_parameters(connection)
775 return self.db_type(connection)
776
777 def db_parameters(self, connection):
778 """
779 Extension of db_type(), providing a range of different return values
780 (type, checks). This will look at db_type(), allowing custom model
781 fields to override it.
782 """
783 type_string = self.db_type(connection)
784 check_string = self.db_check(connection)
785 return {
786 "type": type_string,
787 "check": check_string,
788 }
789
790 def db_type_suffix(self, connection):
791 return connection.data_types_suffix.get(self.get_internal_type())
792
793 def get_db_converters(self, connection):
794 if hasattr(self, "from_db_value"):
795 return [self.from_db_value]
796 return []
797
798 @property
799 def unique(self):
800 return self._unique or self.primary_key
801
802 @property
803 def db_tablespace(self):
804 return self._db_tablespace or settings.DEFAULT_INDEX_TABLESPACE
805
806 @property
807 def db_returning(self):
808 """
809 Private API intended only to be used by Django itself. Currently only
810 the PostgreSQL backend supports returning multiple fields on a model.
811 """
812 return False
813
814 def set_attributes_from_name(self, name):
815 self.name = self.name or name
816 self.attname, self.column = self.get_attname_column()
817 self.concrete = self.column is not None
818 if self.verbose_name is None and self.name:
819 self.verbose_name = self.name.replace("_", " ")
820
821 def contribute_to_class(self, cls, name, private_only=False):
822 """
823 Register the field with the model class it belongs to.
824
825 If private_only is True, create a separate instance of this field
826 for every subclass of cls, even if cls is not an abstract model.
827 """
828 self.set_attributes_from_name(name)
829 self.model = cls
830 cls._meta.add_field(self, private=private_only)
831 if self.column:
832 # Don't override classmethods with the descriptor. This means that
833 # if you have a classmethod and a field with the same name, then
834 # such fields can't be deferred (we don't have a check for this).
835 if not getattr(cls, self.attname, None):
836 setattr(cls, self.attname, self.descriptor_class(self))
837 if self.choices is not None:
838 # Don't override a get_FOO_display() method defined explicitly on
839 # this class, but don't check methods derived from inheritance, to
840 # allow overriding inherited choices. For more complex inheritance
841 # structures users should override contribute_to_class().
842 if "get_%s_display" % self.name not in cls.__dict__:
843 setattr(
844 cls,
845 "get_%s_display" % self.name,
846 partialmethod(cls._get_FIELD_display, field=self),
847 )
848
849 def get_filter_kwargs_for_object(self, obj):
850 """
851 Return a dict that when passed as kwargs to self.model.filter(), would
852 yield all instances having the same value for this field as obj has.
853 """
854 return {self.name: getattr(obj, self.attname)}
855
856 def get_attname(self):
857 return self.name
858
859 def get_attname_column(self):
860 attname = self.get_attname()
861 column = self.db_column or attname
862 return attname, column
863
864 def get_internal_type(self):
865 return self.__class__.__name__
866
867 def pre_save(self, model_instance, add):
868 """Return field's value just before saving."""
869 return getattr(model_instance, self.attname)
870
871 def get_prep_value(self, value):
872 """Perform preliminary non-db specific value checks and conversions."""
873 if isinstance(value, Promise):
874 value = value._proxy____cast()
875 return value
876
877 def get_db_prep_value(self, value, connection, prepared=False):
878 """
879 Return field's value prepared for interacting with the database backend.
880
881 Used by the default implementations of get_db_prep_save().
882 """
883 if not prepared:
884 value = self.get_prep_value(value)
885 return value
886
887 def get_db_prep_save(self, value, connection):
888 """Return field's value prepared for saving into a database."""
889 return self.get_db_prep_value(value, connection=connection, prepared=False)
890
891 def has_default(self):
892 """Return a boolean of whether this field has a default value."""
893 return self.default is not NOT_PROVIDED
894
895 def get_default(self):
896 """Return the default value for this field."""
897 return self._get_default()
898
899 @cached_property
900 def _get_default(self):
901 if self.has_default():
902 if callable(self.default):
903 return self.default
904 return lambda: self.default
905
906 if (
907 not self.empty_strings_allowed
908 or self.null
909 and not connection.features.interprets_empty_strings_as_nulls
910 ):
911 return return_None
912 return str # return empty string
913
914 def get_choices(
915 self,
916 include_blank=True,
917 blank_choice=BLANK_CHOICE_DASH,
918 limit_choices_to=None,
919 ordering=(),
920 ):
921 """
922 Return choices with a default blank choices included, for use
923 as <select> choices for this field.
924 """
925 if self.choices is not None:
926 choices = list(self.choices)
927 if include_blank:
928 blank_defined = any(
929 choice in ("", None) for choice, _ in self.flatchoices
930 )
931 if not blank_defined:
932 choices = blank_choice + choices
933 return choices
934 rel_model = self.remote_field.model
935 limit_choices_to = limit_choices_to or self.get_limit_choices_to()
936 choice_func = operator.attrgetter(
937 self.remote_field.get_related_field().attname
938 if hasattr(self.remote_field, "get_related_field")
939 else "pk"
940 )
941 qs = rel_model._default_manager.complex_filter(limit_choices_to)
942 if ordering:
943 qs = qs.order_by(*ordering)
944 return (blank_choice if include_blank else []) + [
945 (choice_func(x), str(x)) for x in qs
946 ]
947
948 def value_to_string(self, obj):
949 """
950 Return a string value of this field from the passed obj.
951 This is used by the serialization framework.
952 """
953 return str(self.value_from_object(obj))
954
955 def _get_flatchoices(self):
956 """Flattened version of choices tuple."""
957 if self.choices is None:
958 return []
959 flat = []
960 for choice, value in self.choices:
961 if isinstance(value, (list, tuple)):
962 flat.extend(value)
963 else:
964 flat.append((choice, value))
965 return flat
966
967 flatchoices = property(_get_flatchoices)
968
969 def save_form_data(self, instance, data):
970 setattr(instance, self.name, data)
971
972 def formfield(self, form_class=None, choices_form_class=None, **kwargs):
973 """Return a django.forms.Field instance for this field."""
974 defaults = {
975 "required": not self.blank,
976 "label": capfirst(self.verbose_name),
977 "help_text": self.help_text,
978 }
979 if self.has_default():
980 if callable(self.default):
981 defaults["initial"] = self.default
982 defaults["show_hidden_initial"] = True
983 else:
984 defaults["initial"] = self.get_default()
985 if self.choices is not None:
986 # Fields with choices get special treatment.
987 include_blank = self.blank or not (
988 self.has_default() or "initial" in kwargs
989 )
990 defaults["choices"] = self.get_choices(include_blank=include_blank)
991 defaults["coerce"] = self.to_python
992 if self.null:
993 defaults["empty_value"] = None
994 if choices_form_class is not None:
995 form_class = choices_form_class
996 else:
997 form_class = forms.TypedChoiceField
998 # Many of the subclass-specific formfield arguments (min_value,
999 # max_value) don't apply for choice fields, so be sure to only pass
1000 # the values that TypedChoiceField will understand.
1001 for k in list(kwargs):
1002 if k not in (
1003 "coerce",
1004 "empty_value",
1005 "choices",
1006 "required",
1007 "widget",
1008 "label",
1009 "initial",
1010 "help_text",
1011 "error_messages",
1012 "show_hidden_initial",
1013 "disabled",
1014 ):
1015 del kwargs[k]
1016 defaults.update(kwargs)
1017 if form_class is None:
1018 form_class = forms.CharField
1019 return form_class(**defaults)
1020
1021 def value_from_object(self, obj):
1022 """Return the value of this field in the given model instance."""
1023 return getattr(obj, self.attname)
1024
1025
1026class BooleanField(Field):
1027 empty_strings_allowed = False
1028 default_error_messages = {
1029 "invalid": _("“%(value)s” value must be either True or False."),
1030 "invalid_nullable": _("“%(value)s” value must be either True, False, or None."),
1031 }
1032 description = _("Boolean (Either True or False)")
1033
1034 def get_internal_type(self):
1035 return "BooleanField"
1036
1037 def to_python(self, value):
1038 if self.null and value in self.empty_values:
1039 return None
1040 if value in (True, False):
1041 # 1/0 are equal to True/False. bool() converts former to latter.
1042 return bool(value)
1043 if value in ("t", "True", "1"):
1044 return True
1045 if value in ("f", "False", "0"):
1046 return False
1047 raise exceptions.ValidationError(
1048 self.error_messages["invalid_nullable" if self.null else "invalid"],
1049 code="invalid",
1050 params={"value": value},
1051 )
1052
1053 def get_prep_value(self, value):
1054 value = super().get_prep_value(value)
1055 if value is None:
1056 return None
1057 return self.to_python(value)
1058
1059 def formfield(self, **kwargs):
1060 if self.choices is not None:
1061 include_blank = not (self.has_default() or "initial" in kwargs)
1062 defaults = {"choices": self.get_choices(include_blank=include_blank)}
1063 else:
1064 form_class = forms.NullBooleanField if self.null else forms.BooleanField
1065 # In HTML checkboxes, 'required' means "must be checked" which is
1066 # different from the choices case ("must select some value").
1067 # required=False allows unchecked checkboxes.
1068 defaults = {"form_class": form_class, "required": False}
1069 return super().formfield(**{**defaults, **kwargs})
1070
1071
1072class CharField(Field):
1073 description = _("String (up to %(max_length)s)")
1074
1075 def __init__(self, *args, **kwargs):
1076 super().__init__(*args, **kwargs)
1077 self.validators.append(validators.MaxLengthValidator(self.max_length))
1078
1079 def check(self, **kwargs):
1080 return [
1081 *super().check(**kwargs),
1082 *self._check_max_length_attribute(**kwargs),
1083 ]
1084
1085 def _check_max_length_attribute(self, **kwargs):
1086 if self.max_length is None:
1087 return [
1088 checks.Error(
1089 "CharFields must define a 'max_length' attribute.",
1090 obj=self,
1091 id="fields.E120",
1092 )
1093 ]
1094 elif (
1095 not isinstance(self.max_length, int)
1096 or isinstance(self.max_length, bool)
1097 or self.max_length <= 0
1098 ):
1099 return [
1100 checks.Error(
1101 "'max_length' must be a positive integer.",
1102 obj=self,
1103 id="fields.E121",
1104 )
1105 ]
1106 else:
1107 return []
1108
1109 def cast_db_type(self, connection):
1110 if self.max_length is None:
1111 return connection.ops.cast_char_field_without_max_length
1112 return super().cast_db_type(connection)
1113
1114 def get_internal_type(self):
1115 return "CharField"
1116
1117 def to_python(self, value):
1118 if isinstance(value, str) or value is None:
1119 return value
1120 return str(value)
1121
1122 def get_prep_value(self, value):
1123 value = super().get_prep_value(value)
1124 return self.to_python(value)
1125
1126 def formfield(self, **kwargs):
1127 # Passing max_length to forms.CharField means that the value's length
1128 # will be validated twice. This is considered acceptable since we want
1129 # the value in the form field (to pass into widget for example).
1130 defaults = {"max_length": self.max_length}
1131 # TODO: Handle multiple backends with different feature flags.
1132 if self.null and not connection.features.interprets_empty_strings_as_nulls:
1133 defaults["empty_value"] = None
1134 defaults.update(kwargs)
1135 return super().formfield(**defaults)
1136
1137
1138class CommaSeparatedIntegerField(CharField):
1139 default_validators = [validators.validate_comma_separated_integer_list]
1140 description = _("Comma-separated integers")
1141 system_check_removed_details = {
1142 "msg": (
1143 "CommaSeparatedIntegerField is removed except for support in "
1144 "historical migrations."
1145 ),
1146 "hint": (
1147 "Use CharField(validators=[validate_comma_separated_integer_list]) "
1148 "instead."
1149 ),
1150 "id": "fields.E901",
1151 }
1152
1153
1154class DateTimeCheckMixin:
1155 def check(self, **kwargs):
1156 return [
1157 *super().check(**kwargs),
1158 *self._check_mutually_exclusive_options(),
1159 *self._check_fix_default_value(),
1160 ]
1161
1162 def _check_mutually_exclusive_options(self):
1163 # auto_now, auto_now_add, and default are mutually exclusive
1164 # options. The use of more than one of these options together
1165 # will trigger an Error
1166 mutually_exclusive_options = [
1167 self.auto_now_add,
1168 self.auto_now,
1169 self.has_default(),
1170 ]
1171 enabled_options = [
1172 option not in (None, False) for option in mutually_exclusive_options
1173 ].count(True)
1174 if enabled_options > 1:
1175 return [
1176 checks.Error(
1177 "The options auto_now, auto_now_add, and default "
1178 "are mutually exclusive. Only one of these options "
1179 "may be present.",
1180 obj=self,
1181 id="fields.E160",
1182 )
1183 ]
1184 else:
1185 return []
1186
1187 def _check_fix_default_value(self):
1188 return []
1189
1190
1191class DateField(DateTimeCheckMixin, Field):
1192 empty_strings_allowed = False
1193 default_error_messages = {
1194 "invalid": _(
1195 "“%(value)s” value has an invalid date format. It must be "
1196 "in YYYY-MM-DD format."
1197 ),
1198 "invalid_date": _(
1199 "“%(value)s” value has the correct format (YYYY-MM-DD) "
1200 "but it is an invalid date."
1201 ),
1202 }
1203 description = _("Date (without time)")
1204
1205 def __init__(
1206 self, verbose_name=None, name=None, auto_now=False, auto_now_add=False, **kwargs
1207 ):
1208 self.auto_now, self.auto_now_add = auto_now, auto_now_add
1209 if auto_now or auto_now_add:
1210 kwargs["editable"] = False
1211 kwargs["blank"] = True
1212 super().__init__(verbose_name, name, **kwargs)
1213
1214 def _check_fix_default_value(self):
1215 """
1216 Warn that using an actual date or datetime value is probably wrong;
1217 it's only evaluated on server startup.
1218 """
1219 if not self.has_default():
1220 return []
1221
1222 now = timezone.now()
1223 if not timezone.is_naive(now):
1224 now = timezone.make_naive(now, timezone.utc)
1225 value = self.default
1226 if isinstance(value, datetime.datetime):
1227 if not timezone.is_naive(value):
1228 value = timezone.make_naive(value, timezone.utc)
1229 value = value.date()
1230 elif isinstance(value, datetime.date):
1231 # Nothing to do, as dates don't have tz information
1232 pass
1233 else:
1234 # No explicit date / datetime value -- no checks necessary
1235 return []
1236 offset = datetime.timedelta(days=1)
1237 lower = (now - offset).date()
1238 upper = (now + offset).date()
1239 if lower <= value <= upper:
1240 return [
1241 checks.Warning(
1242 "Fixed default value provided.",
1243 hint="It seems you set a fixed date / time / datetime "
1244 "value as default for this field. This may not be "
1245 "what you want. If you want to have the current date "
1246 "as default, use `django.utils.timezone.now`",
1247 obj=self,
1248 id="fields.W161",
1249 )
1250 ]
1251
1252 return []
1253
1254 def deconstruct(self):
1255 name, path, args, kwargs = super().deconstruct()
1256 if self.auto_now:
1257 kwargs["auto_now"] = True
1258 if self.auto_now_add:
1259 kwargs["auto_now_add"] = True
1260 if self.auto_now or self.auto_now_add:
1261 del kwargs["editable"]
1262 del kwargs["blank"]
1263 return name, path, args, kwargs
1264
1265 def get_internal_type(self):
1266 return "DateField"
1267
1268 def to_python(self, value):
1269 if value is None:
1270 return value
1271 if isinstance(value, datetime.datetime):
1272 if settings.USE_TZ and timezone.is_aware(value):
1273 # Convert aware datetimes to the default time zone
1274 # before casting them to dates (#17742).
1275 default_timezone = timezone.get_default_timezone()
1276 value = timezone.make_naive(value, default_timezone)
1277 return value.date()
1278 if isinstance(value, datetime.date):
1279 return value
1280
1281 try:
1282 parsed = parse_date(value)
1283 if parsed is not None:
1284 return parsed
1285 except ValueError:
1286 raise exceptions.ValidationError(
1287 self.error_messages["invalid_date"],
1288 code="invalid_date",
1289 params={"value": value},
1290 )
1291
1292 raise exceptions.ValidationError(
1293 self.error_messages["invalid"], code="invalid", params={"value": value},
1294 )
1295
1296 def pre_save(self, model_instance, add):
1297 if self.auto_now or (self.auto_now_add and add):
1298 value = datetime.date.today()
1299 setattr(model_instance, self.attname, value)
1300 return value
1301 else:
1302 return super().pre_save(model_instance, add)
1303
1304 def contribute_to_class(self, cls, name, **kwargs):
1305 super().contribute_to_class(cls, name, **kwargs)
1306 if not self.null:
1307 setattr(
1308 cls,
1309 "get_next_by_%s" % self.name,
1310 partialmethod(
1311 cls._get_next_or_previous_by_FIELD, field=self, is_next=True
1312 ),
1313 )
1314 setattr(
1315 cls,
1316 "get_previous_by_%s" % self.name,
1317 partialmethod(
1318 cls._get_next_or_previous_by_FIELD, field=self, is_next=False
1319 ),
1320 )
1321
1322 def get_prep_value(self, value):
1323 value = super().get_prep_value(value)
1324 return self.to_python(value)
1325
1326 def get_db_prep_value(self, value, connection, prepared=False):
1327 # Casts dates into the format expected by the backend
1328 if not prepared:
1329 value = self.get_prep_value(value)
1330 return connection.ops.adapt_datefield_value(value)
1331
1332 def value_to_string(self, obj):
1333 val = self.value_from_object(obj)
1334 return "" if val is None else val.isoformat()
1335
1336 def formfield(self, **kwargs):
1337 return super().formfield(**{"form_class": forms.DateField, **kwargs,})
1338
1339
1340class DateTimeField(DateField):
1341 empty_strings_allowed = False
1342 default_error_messages = {
1343 "invalid": _(
1344 "“%(value)s” value has an invalid format. It must be in "
1345 "YYYY-MM-DD HH:MM[:ss[.uuuuuu]][TZ] format."
1346 ),
1347 "invalid_date": _(
1348 "“%(value)s” value has the correct format "
1349 "(YYYY-MM-DD) but it is an invalid date."
1350 ),
1351 "invalid_datetime": _(
1352 "“%(value)s” value has the correct format "
1353 "(YYYY-MM-DD HH:MM[:ss[.uuuuuu]][TZ]) "
1354 "but it is an invalid date/time."
1355 ),
1356 }
1357 description = _("Date (with time)")
1358
1359 # __init__ is inherited from DateField
1360
1361 def _check_fix_default_value(self):
1362 """
1363 Warn that using an actual date or datetime value is probably wrong;
1364 it's only evaluated on server startup.
1365 """
1366 if not self.has_default():
1367 return []
1368
1369 now = timezone.now()
1370 if not timezone.is_naive(now):
1371 now = timezone.make_naive(now, timezone.utc)
1372 value = self.default
1373 if isinstance(value, datetime.datetime):
1374 second_offset = datetime.timedelta(seconds=10)
1375 lower = now - second_offset
1376 upper = now + second_offset
1377 if timezone.is_aware(value):
1378 value = timezone.make_naive(value, timezone.utc)
1379 elif isinstance(value, datetime.date):
1380 second_offset = datetime.timedelta(seconds=10)
1381 lower = now - second_offset
1382 lower = datetime.datetime(lower.year, lower.month, lower.day)
1383 upper = now + second_offset
1384 upper = datetime.datetime(upper.year, upper.month, upper.day)
1385 value = datetime.datetime(value.year, value.month, value.day)
1386 else:
1387 # No explicit date / datetime value -- no checks necessary
1388 return []
1389 if lower <= value <= upper:
1390 return [
1391 checks.Warning(
1392 "Fixed default value provided.",
1393 hint="It seems you set a fixed date / time / datetime "
1394 "value as default for this field. This may not be "
1395 "what you want. If you want to have the current date "
1396 "as default, use `django.utils.timezone.now`",
1397 obj=self,
1398 id="fields.W161",
1399 )
1400 ]
1401
1402 return []
1403
1404 def get_internal_type(self):
1405 return "DateTimeField"
1406
1407 def to_python(self, value):
1408 if value is None:
1409 return value
1410 if isinstance(value, datetime.datetime):
1411 return value
1412 if isinstance(value, datetime.date):
1413 value = datetime.datetime(value.year, value.month, value.day)
1414 if settings.USE_TZ:
1415 # For backwards compatibility, interpret naive datetimes in
1416 # local time. This won't work during DST change, but we can't
1417 # do much about it, so we let the exceptions percolate up the
1418 # call stack.
1419 warnings.warn(
1420 "DateTimeField %s.%s received a naive datetime "
1421 "(%s) while time zone support is active."
1422 % (self.model.__name__, self.name, value),
1423 RuntimeWarning,
1424 )
1425 default_timezone = timezone.get_default_timezone()
1426 value = timezone.make_aware(value, default_timezone)
1427 return value
1428
1429 try:
1430 parsed = parse_datetime(value)
1431 if parsed is not None:
1432 return parsed
1433 except ValueError:
1434 raise exceptions.ValidationError(
1435 self.error_messages["invalid_datetime"],
1436 code="invalid_datetime",
1437 params={"value": value},
1438 )
1439
1440 try:
1441 parsed = parse_date(value)
1442 if parsed is not None:
1443 return datetime.datetime(parsed.year, parsed.month, parsed.day)
1444 except ValueError:
1445 raise exceptions.ValidationError(
1446 self.error_messages["invalid_date"],
1447 code="invalid_date",
1448 params={"value": value},
1449 )
1450
1451 raise exceptions.ValidationError(
1452 self.error_messages["invalid"], code="invalid", params={"value": value},
1453 )
1454
1455 def pre_save(self, model_instance, add):
1456 if self.auto_now or (self.auto_now_add and add):
1457 value = timezone.now()
1458 setattr(model_instance, self.attname, value)
1459 return value
1460 else:
1461 return super().pre_save(model_instance, add)
1462
1463 # contribute_to_class is inherited from DateField, it registers
1464 # get_next_by_FOO and get_prev_by_FOO
1465
1466 def get_prep_value(self, value):
1467 value = super().get_prep_value(value)
1468 value = self.to_python(value)
1469 if value is not None and settings.USE_TZ and timezone.is_naive(value):
1470 # For backwards compatibility, interpret naive datetimes in local
1471 # time. This won't work during DST change, but we can't do much
1472 # about it, so we let the exceptions percolate up the call stack.
1473 try:
1474 name = "%s.%s" % (self.model.__name__, self.name)
1475 except AttributeError:
1476 name = "(unbound)"
1477 warnings.warn(
1478 "DateTimeField %s received a naive datetime (%s)"
1479 " while time zone support is active." % (name, value),
1480 RuntimeWarning,
1481 )
1482 default_timezone = timezone.get_default_timezone()
1483 value = timezone.make_aware(value, default_timezone)
1484 return value
1485
1486 def get_db_prep_value(self, value, connection, prepared=False):
1487 # Casts datetimes into the format expected by the backend
1488 if not prepared:
1489 value = self.get_prep_value(value)
1490 return connection.ops.adapt_datetimefield_value(value)
1491
1492 def value_to_string(self, obj):
1493 val = self.value_from_object(obj)
1494 return "" if val is None else val.isoformat()
1495
1496 def formfield(self, **kwargs):
1497 return super().formfield(**{"form_class": forms.DateTimeField, **kwargs,})
1498
1499
1500class DecimalField(Field):
1501 empty_strings_allowed = False
1502 default_error_messages = {
1503 "invalid": _("“%(value)s” value must be a decimal number."),
1504 }
1505 description = _("Decimal number")
1506
1507 def __init__(
1508 self,
1509 verbose_name=None,
1510 name=None,
1511 max_digits=None,
1512 decimal_places=None,
1513 **kwargs
1514 ):
1515 self.max_digits, self.decimal_places = max_digits, decimal_places
1516 super().__init__(verbose_name, name, **kwargs)
1517
1518 def check(self, **kwargs):
1519 errors = super().check(**kwargs)
1520
1521 digits_errors = [
1522 *self._check_decimal_places(),
1523 *self._check_max_digits(),
1524 ]
1525 if not digits_errors:
1526 errors.extend(self._check_decimal_places_and_max_digits(**kwargs))
1527 else:
1528 errors.extend(digits_errors)
1529 return errors
1530
1531 def _check_decimal_places(self):
1532 try:
1533 decimal_places = int(self.decimal_places)
1534 if decimal_places < 0:
1535 raise ValueError()
1536 except TypeError:
1537 return [
1538 checks.Error(
1539 "DecimalFields must define a 'decimal_places' attribute.",
1540 obj=self,
1541 id="fields.E130",
1542 )
1543 ]
1544 except ValueError:
1545 return [
1546 checks.Error(
1547 "'decimal_places' must be a non-negative integer.",
1548 obj=self,
1549 id="fields.E131",
1550 )
1551 ]
1552 else:
1553 return []
1554
1555 def _check_max_digits(self):
1556 try:
1557 max_digits = int(self.max_digits)
1558 if max_digits <= 0:
1559 raise ValueError()
1560 except TypeError:
1561 return [
1562 checks.Error(
1563 "DecimalFields must define a 'max_digits' attribute.",
1564 obj=self,
1565 id="fields.E132",
1566 )
1567 ]
1568 except ValueError:
1569 return [
1570 checks.Error(
1571 "'max_digits' must be a positive integer.",
1572 obj=self,
1573 id="fields.E133",
1574 )
1575 ]
1576 else:
1577 return []
1578
1579 def _check_decimal_places_and_max_digits(self, **kwargs):
1580 if int(self.decimal_places) > int(self.max_digits):
1581 return [
1582 checks.Error(
1583 "'max_digits' must be greater or equal to 'decimal_places'.",
1584 obj=self,
1585 id="fields.E134",
1586 )
1587 ]
1588 return []
1589
1590 @cached_property
1591 def validators(self):
1592 return super().validators + [
1593 validators.DecimalValidator(self.max_digits, self.decimal_places)
1594 ]
1595
1596 @cached_property
1597 def context(self):
1598 return decimal.Context(prec=self.max_digits)
1599
1600 def deconstruct(self):
1601 name, path, args, kwargs = super().deconstruct()
1602 if self.max_digits is not None:
1603 kwargs["max_digits"] = self.max_digits
1604 if self.decimal_places is not None:
1605 kwargs["decimal_places"] = self.decimal_places
1606 return name, path, args, kwargs
1607
1608 def get_internal_type(self):
1609 return "DecimalField"
1610
1611 def to_python(self, value):
1612 if value is None:
1613 return value
1614 if isinstance(value, float):
1615 return self.context.create_decimal_from_float(value)
1616 try:
1617 return decimal.Decimal(value)
1618 except decimal.InvalidOperation:
1619 raise exceptions.ValidationError(
1620 self.error_messages["invalid"], code="invalid", params={"value": value},
1621 )
1622
1623 def get_db_prep_save(self, value, connection):
1624 return connection.ops.adapt_decimalfield_value(
1625 self.to_python(value), self.max_digits, self.decimal_places
1626 )
1627
1628 def get_prep_value(self, value):
1629 value = super().get_prep_value(value)
1630 return self.to_python(value)
1631
1632 def formfield(self, **kwargs):
1633 return super().formfield(
1634 **{
1635 "max_digits": self.max_digits,
1636 "decimal_places": self.decimal_places,
1637 "form_class": forms.DecimalField,
1638 **kwargs,
1639 }
1640 )
1641
1642
1643class DurationField(Field):
1644 """
1645 Store timedelta objects.
1646
1647 Use interval on PostgreSQL, INTERVAL DAY TO SECOND on Oracle, and bigint
1648 of microseconds on other databases.
1649 """
1650
1651 empty_strings_allowed = False
1652 default_error_messages = {
1653 "invalid": _(
1654 "“%(value)s” value has an invalid format. It must be in "
1655 "[DD] [[HH:]MM:]ss[.uuuuuu] format."
1656 )
1657 }
1658 description = _("Duration")
1659
1660 def get_internal_type(self):
1661 return "DurationField"
1662
1663 def to_python(self, value):
1664 if value is None:
1665 return value
1666 if isinstance(value, datetime.timedelta):
1667 return value
1668 try:
1669 parsed = parse_duration(value)
1670 except ValueError:
1671 pass
1672 else:
1673 if parsed is not None:
1674 return parsed
1675
1676 raise exceptions.ValidationError(
1677 self.error_messages["invalid"], code="invalid", params={"value": value},
1678 )
1679
1680 def get_db_prep_value(self, value, connection, prepared=False):
1681 if connection.features.has_native_duration_field:
1682 return value
1683 if value is None:
1684 return None
1685 return duration_microseconds(value)
1686
1687 def get_db_converters(self, connection):
1688 converters = []
1689 if not connection.features.has_native_duration_field:
1690 converters.append(connection.ops.convert_durationfield_value)
1691 return converters + super().get_db_converters(connection)
1692
1693 def value_to_string(self, obj):
1694 val = self.value_from_object(obj)
1695 return "" if val is None else duration_string(val)
1696
1697 def formfield(self, **kwargs):
1698 return super().formfield(**{"form_class": forms.DurationField, **kwargs,})
1699
1700
1701class EmailField(CharField):
1702 default_validators = [validators.validate_email]
1703 description = _("Email address")
1704
1705 def __init__(self, *args, **kwargs):
1706 # max_length=254 to be compliant with RFCs 3696 and 5321
1707 kwargs.setdefault("max_length", 254)
1708 super().__init__(*args, **kwargs)
1709
1710 def deconstruct(self):
1711 name, path, args, kwargs = super().deconstruct()
1712 # We do not exclude max_length if it matches default as we want to change
1713 # the default in future.
1714 return name, path, args, kwargs
1715
1716 def formfield(self, **kwargs):
1717 # As with CharField, this will cause email validation to be performed
1718 # twice.
1719 return super().formfield(**{"form_class": forms.EmailField, **kwargs,})
1720
1721
1722class FilePathField(Field):
1723 description = _("File path")
1724
1725 def __init__(
1726 self,
1727 verbose_name=None,
1728 name=None,
1729 path="",
1730 match=None,
1731 recursive=False,
1732 allow_files=True,
1733 allow_folders=False,
1734 **kwargs
1735 ):
1736 self.path, self.match, self.recursive = path, match, recursive
1737 self.allow_files, self.allow_folders = allow_files, allow_folders
1738 kwargs.setdefault("max_length", 100)
1739 super().__init__(verbose_name, name, **kwargs)
1740
1741 def check(self, **kwargs):
1742 return [
1743 *super().check(**kwargs),
1744 *self._check_allowing_files_or_folders(**kwargs),
1745 ]
1746
1747 def _check_allowing_files_or_folders(self, **kwargs):
1748 if not self.allow_files and not self.allow_folders:
1749 return [
1750 checks.Error(
1751 "FilePathFields must have either 'allow_files' or 'allow_folders' set to True.",
1752 obj=self,
1753 id="fields.E140",
1754 )
1755 ]
1756 return []
1757
1758 def deconstruct(self):
1759 name, path, args, kwargs = super().deconstruct()
1760 if self.path != "":
1761 kwargs["path"] = self.path
1762 if self.match is not None:
1763 kwargs["match"] = self.match
1764 if self.recursive is not False:
1765 kwargs["recursive"] = self.recursive
1766 if self.allow_files is not True:
1767 kwargs["allow_files"] = self.allow_files
1768 if self.allow_folders is not False:
1769 kwargs["allow_folders"] = self.allow_folders
1770 if kwargs.get("max_length") == 100:
1771 del kwargs["max_length"]
1772 return name, path, args, kwargs
1773
1774 def get_prep_value(self, value):
1775 value = super().get_prep_value(value)
1776 if value is None:
1777 return None
1778 return str(value)
1779
1780 def formfield(self, **kwargs):
1781 return super().formfield(
1782 **{
1783 "path": self.path() if callable(self.path) else self.path,
1784 "match": self.match,
1785 "recursive": self.recursive,
1786 "form_class": forms.FilePathField,
1787 "allow_files": self.allow_files,
1788 "allow_folders": self.allow_folders,
1789 **kwargs,
1790 }
1791 )
1792
1793 def get_internal_type(self):
1794 return "FilePathField"
1795
1796
1797class FloatField(Field):
1798 empty_strings_allowed = False
1799 default_error_messages = {
1800 "invalid": _("“%(value)s” value must be a float."),
1801 }
1802 description = _("Floating point number")
1803
1804 def get_prep_value(self, value):
1805 value = super().get_prep_value(value)
1806 if value is None:
1807 return None
1808 try:
1809 return float(value)
1810 except (TypeError, ValueError) as e:
1811 raise e.__class__(
1812 "Field '%s' expected a number but got %r." % (self.name, value),
1813 ) from e
1814
1815 def get_internal_type(self):
1816 return "FloatField"
1817
1818 def to_python(self, value):
1819 if value is None:
1820 return value
1821 try:
1822 return float(value)
1823 except (TypeError, ValueError):
1824 raise exceptions.ValidationError(
1825 self.error_messages["invalid"], code="invalid", params={"value": value},
1826 )
1827
1828 def formfield(self, **kwargs):
1829 return super().formfield(**{"form_class": forms.FloatField, **kwargs,})
1830
1831
1832class IntegerField(Field):
1833 empty_strings_allowed = False
1834 default_error_messages = {
1835 "invalid": _("“%(value)s” value must be an integer."),
1836 }
1837 description = _("Integer")
1838
1839 def check(self, **kwargs):
1840 return [
1841 *super().check(**kwargs),
1842 *self._check_max_length_warning(),
1843 ]
1844
1845 def _check_max_length_warning(self):
1846 if self.max_length is not None:
1847 return [
1848 checks.Warning(
1849 "'max_length' is ignored when used with %s."
1850 % self.__class__.__name__,
1851 hint="Remove 'max_length' from field",
1852 obj=self,
1853 id="fields.W122",
1854 )
1855 ]
1856 return []
1857
1858 @cached_property
1859 def validators(self):
1860 # These validators can't be added at field initialization time since
1861 # they're based on values retrieved from `connection`.
1862 validators_ = super().validators
1863 internal_type = self.get_internal_type()
1864 min_value, max_value = connection.ops.integer_field_range(internal_type)
1865 if min_value is not None and not any(
1866 (
1867 isinstance(validator, validators.MinValueValidator)
1868 and (
1869 validator.limit_value()
1870 if callable(validator.limit_value)
1871 else validator.limit_value
1872 )
1873 >= min_value
1874 )
1875 for validator in validators_
1876 ):
1877 validators_.append(validators.MinValueValidator(min_value))
1878 if max_value is not None and not any(
1879 (
1880 isinstance(validator, validators.MaxValueValidator)
1881 and (
1882 validator.limit_value()
1883 if callable(validator.limit_value)
1884 else validator.limit_value
1885 )
1886 <= max_value
1887 )
1888 for validator in validators_
1889 ):
1890 validators_.append(validators.MaxValueValidator(max_value))
1891 return validators_
1892
1893 def get_prep_value(self, value):
1894 value = super().get_prep_value(value)
1895 if value is None:
1896 return None
1897 try:
1898 return int(value)
1899 except (TypeError, ValueError) as e:
1900 raise e.__class__(
1901 "Field '%s' expected a number but got %r." % (self.name, value),
1902 ) from e
1903
1904 def get_internal_type(self):
1905 return "IntegerField"
1906
1907 def to_python(self, value):
1908 if value is None:
1909 return value
1910 try:
1911 return int(value)
1912 except (TypeError, ValueError):
1913 raise exceptions.ValidationError(
1914 self.error_messages["invalid"], code="invalid", params={"value": value},
1915 )
1916
1917 def formfield(self, **kwargs):
1918 return super().formfield(**{"form_class": forms.IntegerField, **kwargs,})
1919
1920
1921class BigIntegerField(IntegerField):
1922 description = _("Big (8 byte) integer")
1923 MAX_BIGINT = 9223372036854775807
1924
1925 def get_internal_type(self):
1926 return "BigIntegerField"
1927
1928 def formfield(self, **kwargs):
1929 return super().formfield(
1930 **{
1931 "min_value": -BigIntegerField.MAX_BIGINT - 1,
1932 "max_value": BigIntegerField.MAX_BIGINT,
1933 **kwargs,
1934 }
1935 )
1936
1937
1938class IPAddressField(Field):
1939 empty_strings_allowed = False
1940 description = _("IPv4 address")
1941 system_check_removed_details = {
1942 "msg": (
1943 "IPAddressField has been removed except for support in "
1944 "historical migrations."
1945 ),
1946 "hint": "Use GenericIPAddressField instead.",
1947 "id": "fields.E900",
1948 }
1949
1950 def __init__(self, *args, **kwargs):
1951 kwargs["max_length"] = 15
1952 super().__init__(*args, **kwargs)
1953
1954 def deconstruct(self):
1955 name, path, args, kwargs = super().deconstruct()
1956 del kwargs["max_length"]
1957 return name, path, args, kwargs
1958
1959 def get_prep_value(self, value):
1960 value = super().get_prep_value(value)
1961 if value is None:
1962 return None
1963 return str(value)
1964
1965 def get_internal_type(self):
1966 return "IPAddressField"
1967
1968
1969class GenericIPAddressField(Field):
1970 empty_strings_allowed = False
1971 description = _("IP address")
1972 default_error_messages = {}
1973
1974 def __init__(
1975 self,
1976 verbose_name=None,
1977 name=None,
1978 protocol="both",
1979 unpack_ipv4=False,
1980 *args,
1981 **kwargs
1982 ):
1983 self.unpack_ipv4 = unpack_ipv4
1984 self.protocol = protocol
1985 (
1986 self.default_validators,
1987 invalid_error_message,
1988 ) = validators.ip_address_validators(protocol, unpack_ipv4)
1989 self.default_error_messages["invalid"] = invalid_error_message
1990 kwargs["max_length"] = 39
1991 super().__init__(verbose_name, name, *args, **kwargs)
1992
1993 def check(self, **kwargs):
1994 return [
1995 *super().check(**kwargs),
1996 *self._check_blank_and_null_values(**kwargs),
1997 ]
1998
1999 def _check_blank_and_null_values(self, **kwargs):
2000 if not getattr(self, "null", False) and getattr(self, "blank", False):
2001 return [
2002 checks.Error(
2003 "GenericIPAddressFields cannot have blank=True if null=False, "
2004 "as blank values are stored as nulls.",
2005 obj=self,
2006 id="fields.E150",
2007 )
2008 ]
2009 return []
2010
2011 def deconstruct(self):
2012 name, path, args, kwargs = super().deconstruct()
2013 if self.unpack_ipv4 is not False:
2014 kwargs["unpack_ipv4"] = self.unpack_ipv4
2015 if self.protocol != "both":
2016 kwargs["protocol"] = self.protocol
2017 if kwargs.get("max_length") == 39:
2018 del kwargs["max_length"]
2019 return name, path, args, kwargs
2020
2021 def get_internal_type(self):
2022 return "GenericIPAddressField"
2023
2024 def to_python(self, value):
2025 if value is None:
2026 return None
2027 if not isinstance(value, str):
2028 value = str(value)
2029 value = value.strip()
2030 if ":" in value:
2031 return clean_ipv6_address(
2032 value, self.unpack_ipv4, self.error_messages["invalid"]
2033 )
2034 return value
2035
2036 def get_db_prep_value(self, value, connection, prepared=False):
2037 if not prepared:
2038 value = self.get_prep_value(value)
2039 return connection.ops.adapt_ipaddressfield_value(value)
2040
2041 def get_prep_value(self, value):
2042 value = super().get_prep_value(value)
2043 if value is None:
2044 return None
2045 if value and ":" in value:
2046 try:
2047 return clean_ipv6_address(value, self.unpack_ipv4)
2048 except exceptions.ValidationError:
2049 pass
2050 return str(value)
2051
2052 def formfield(self, **kwargs):
2053 return super().formfield(
2054 **{
2055 "protocol": self.protocol,
2056 "form_class": forms.GenericIPAddressField,
2057 **kwargs,
2058 }
2059 )
2060
2061
2062class NullBooleanField(BooleanField):
2063 default_error_messages = {
2064 "invalid": _("“%(value)s” value must be either None, True or False."),
2065 "invalid_nullable": _("“%(value)s” value must be either None, True or False."),
2066 }
2067 description = _("Boolean (Either True, False or None)")
2068
2069 def __init__(self, *args, **kwargs):
2070 kwargs["null"] = True
2071 kwargs["blank"] = True
2072 super().__init__(*args, **kwargs)
2073
2074 def deconstruct(self):
2075 name, path, args, kwargs = super().deconstruct()
2076 del kwargs["null"]
2077 del kwargs["blank"]
2078 return name, path, args, kwargs
2079
2080 def get_internal_type(self):
2081 return "NullBooleanField"
2082
2083
2084class PositiveIntegerRelDbTypeMixin:
2085 def rel_db_type(self, connection):
2086 """
2087 Return the data type that a related field pointing to this field should
2088 use. In most cases, a foreign key pointing to a positive integer
2089 primary key will have an integer column data type but some databases
2090 (e.g. MySQL) have an unsigned integer type. In that case
2091 (related_fields_match_type=True), the primary key should return its
2092 db_type.
2093 """
2094 if connection.features.related_fields_match_type:
2095 return self.db_type(connection)
2096 else:
2097 return IntegerField().db_type(connection=connection)
2098
2099
2100class PositiveBigIntegerField(PositiveIntegerRelDbTypeMixin, IntegerField):
2101 description = _("Positive big integer")
2102
2103 def get_internal_type(self):
2104 return "PositiveBigIntegerField"
2105
2106 def formfield(self, **kwargs):
2107 return super().formfield(**{"min_value": 0, **kwargs,})
2108
2109
2110class PositiveIntegerField(PositiveIntegerRelDbTypeMixin, IntegerField):
2111 description = _("Positive integer")
2112
2113 def get_internal_type(self):
2114 return "PositiveIntegerField"
2115
2116 def formfield(self, **kwargs):
2117 return super().formfield(**{"min_value": 0, **kwargs,})
2118
2119
2120class PositiveSmallIntegerField(PositiveIntegerRelDbTypeMixin, IntegerField):
2121 description = _("Positive small integer")
2122
2123 def get_internal_type(self):
2124 return "PositiveSmallIntegerField"
2125
2126 def formfield(self, **kwargs):
2127 return super().formfield(**{"min_value": 0, **kwargs,})
2128
2129
2130class SlugField(CharField):
2131 default_validators = [validators.validate_slug]
2132 description = _("Slug (up to %(max_length)s)")
2133
2134 def __init__(
2135 self, *args, max_length=50, db_index=True, allow_unicode=False, **kwargs
2136 ):
2137 self.allow_unicode = allow_unicode
2138 if self.allow_unicode:
2139 self.default_validators = [validators.validate_unicode_slug]
2140 super().__init__(*args, max_length=max_length, db_index=db_index, **kwargs)
2141
2142 def deconstruct(self):
2143 name, path, args, kwargs = super().deconstruct()
2144 if kwargs.get("max_length") == 50:
2145 del kwargs["max_length"]
2146 if self.db_index is False:
2147 kwargs["db_index"] = False
2148 else:
2149 del kwargs["db_index"]
2150 if self.allow_unicode is not False:
2151 kwargs["allow_unicode"] = self.allow_unicode
2152 return name, path, args, kwargs
2153
2154 def get_internal_type(self):
2155 return "SlugField"
2156
2157 def formfield(self, **kwargs):
2158 return super().formfield(
2159 **{
2160 "form_class": forms.SlugField,
2161 "allow_unicode": self.allow_unicode,
2162 **kwargs,
2163 }
2164 )
2165
2166
2167class SmallIntegerField(IntegerField):
2168 description = _("Small integer")
2169
2170 def get_internal_type(self):
2171 return "SmallIntegerField"
2172
2173
2174class TextField(Field):
2175 description = _("Text")
2176
2177 def get_internal_type(self):
2178 return "TextField"
2179
2180 def to_python(self, value):
2181 if isinstance(value, str) or value is None:
2182 return value
2183 return str(value)
2184
2185 def get_prep_value(self, value):
2186 value = super().get_prep_value(value)
2187 return self.to_python(value)
2188
2189 def formfield(self, **kwargs):
2190 # Passing max_length to forms.CharField means that the value's length
2191 # will be validated twice. This is considered acceptable since we want
2192 # the value in the form field (to pass into widget for example).
2193 return super().formfield(
2194 **{
2195 "max_length": self.max_length,
2196 **({} if self.choices is not None else {"widget": forms.Textarea}),
2197 **kwargs,
2198 }
2199 )
2200
2201
2202class TimeField(DateTimeCheckMixin, Field):
2203 empty_strings_allowed = False
2204 default_error_messages = {
2205 "invalid": _(
2206 "“%(value)s” value has an invalid format. It must be in "
2207 "HH:MM[:ss[.uuuuuu]] format."
2208 ),
2209 "invalid_time": _(
2210 "“%(value)s” value has the correct format "
2211 "(HH:MM[:ss[.uuuuuu]]) but it is an invalid time."
2212 ),
2213 }
2214 description = _("Time")
2215
2216 def __init__(
2217 self, verbose_name=None, name=None, auto_now=False, auto_now_add=False, **kwargs
2218 ):
2219 self.auto_now, self.auto_now_add = auto_now, auto_now_add
2220 if auto_now or auto_now_add:
2221 kwargs["editable"] = False
2222 kwargs["blank"] = True
2223 super().__init__(verbose_name, name, **kwargs)
2224
2225 def _check_fix_default_value(self):
2226 """
2227 Warn that using an actual date or datetime value is probably wrong;
2228 it's only evaluated on server startup.
2229 """
2230 if not self.has_default():
2231 return []
2232
2233 now = timezone.now()
2234 if not timezone.is_naive(now):
2235 now = timezone.make_naive(now, timezone.utc)
2236 value = self.default
2237 if isinstance(value, datetime.datetime):
2238 second_offset = datetime.timedelta(seconds=10)
2239 lower = now - second_offset
2240 upper = now + second_offset
2241 if timezone.is_aware(value):
2242 value = timezone.make_naive(value, timezone.utc)
2243 elif isinstance(value, datetime.time):
2244 second_offset = datetime.timedelta(seconds=10)
2245 lower = now - second_offset
2246 upper = now + second_offset
2247 value = datetime.datetime.combine(now.date(), value)
2248 if timezone.is_aware(value):
2249 value = timezone.make_naive(value, timezone.utc).time()
2250 else:
2251 # No explicit time / datetime value -- no checks necessary
2252 return []
2253 if lower <= value <= upper:
2254 return [
2255 checks.Warning(
2256 "Fixed default value provided.",
2257 hint="It seems you set a fixed date / time / datetime "
2258 "value as default for this field. This may not be "
2259 "what you want. If you want to have the current date "
2260 "as default, use `django.utils.timezone.now`",
2261 obj=self,
2262 id="fields.W161",
2263 )
2264 ]
2265
2266 return []
2267
2268 def deconstruct(self):
2269 name, path, args, kwargs = super().deconstruct()
2270 if self.auto_now is not False:
2271 kwargs["auto_now"] = self.auto_now
2272 if self.auto_now_add is not False:
2273 kwargs["auto_now_add"] = self.auto_now_add
2274 if self.auto_now or self.auto_now_add:
2275 del kwargs["blank"]
2276 del kwargs["editable"]
2277 return name, path, args, kwargs
2278
2279 def get_internal_type(self):
2280 return "TimeField"
2281
2282 def to_python(self, value):
2283 if value is None:
2284 return None
2285 if isinstance(value, datetime.time):
2286 return value
2287 if isinstance(value, datetime.datetime):
2288 # Not usually a good idea to pass in a datetime here (it loses
2289 # information), but this can be a side-effect of interacting with a
2290 # database backend (e.g. Oracle), so we'll be accommodating.
2291 return value.time()
2292
2293 try:
2294 parsed = parse_time(value)
2295 if parsed is not None:
2296 return parsed
2297 except ValueError:
2298 raise exceptions.ValidationError(
2299 self.error_messages["invalid_time"],
2300 code="invalid_time",
2301 params={"value": value},
2302 )
2303
2304 raise exceptions.ValidationError(
2305 self.error_messages["invalid"], code="invalid", params={"value": value},
2306 )
2307
2308 def pre_save(self, model_instance, add):
2309 if self.auto_now or (self.auto_now_add and add):
2310 value = datetime.datetime.now().time()
2311 setattr(model_instance, self.attname, value)
2312 return value
2313 else:
2314 return super().pre_save(model_instance, add)
2315
2316 def get_prep_value(self, value):
2317 value = super().get_prep_value(value)
2318 return self.to_python(value)
2319
2320 def get_db_prep_value(self, value, connection, prepared=False):
2321 # Casts times into the format expected by the backend
2322 if not prepared:
2323 value = self.get_prep_value(value)
2324 return connection.ops.adapt_timefield_value(value)
2325
2326 def value_to_string(self, obj):
2327 val = self.value_from_object(obj)
2328 return "" if val is None else val.isoformat()
2329
2330 def formfield(self, **kwargs):
2331 return super().formfield(**{"form_class": forms.TimeField, **kwargs,})
2332
2333
2334class URLField(CharField):
2335 default_validators = [validators.URLValidator()]
2336 description = _("URL")
2337
2338 def __init__(self, verbose_name=None, name=None, **kwargs):
2339 kwargs.setdefault("max_length", 200)
2340 super().__init__(verbose_name, name, **kwargs)
2341
2342 def deconstruct(self):
2343 name, path, args, kwargs = super().deconstruct()
2344 if kwargs.get("max_length") == 200:
2345 del kwargs["max_length"]
2346 return name, path, args, kwargs
2347
2348 def formfield(self, **kwargs):
2349 # As with CharField, this will cause URL validation to be performed
2350 # twice.
2351 return super().formfield(**{"form_class": forms.URLField, **kwargs,})
2352
2353
2354class BinaryField(Field):
2355 description = _("Raw binary data")
2356 empty_values = [None, b""]
2357
2358 def __init__(self, *args, **kwargs):
2359 kwargs.setdefault("editable", False)
2360 super().__init__(*args, **kwargs)
2361 if self.max_length is not None:
2362 self.validators.append(validators.MaxLengthValidator(self.max_length))
2363
2364 def check(self, **kwargs):
2365 return [*super().check(**kwargs), *self._check_str_default_value()]
2366
2367 def _check_str_default_value(self):
2368 if self.has_default() and isinstance(self.default, str):
2369 return [
2370 checks.Error(
2371 "BinaryField's default cannot be a string. Use bytes "
2372 "content instead.",
2373 obj=self,
2374 id="fields.E170",
2375 )
2376 ]
2377 return []
2378
2379 def deconstruct(self):
2380 name, path, args, kwargs = super().deconstruct()
2381 if self.editable:
2382 kwargs["editable"] = True
2383 else:
2384 del kwargs["editable"]
2385 return name, path, args, kwargs
2386
2387 def get_internal_type(self):
2388 return "BinaryField"
2389
2390 def get_placeholder(self, value, compiler, connection):
2391 return connection.ops.binary_placeholder_sql(value)
2392
2393 def get_default(self):
2394 if self.has_default() and not callable(self.default):
2395 return self.default
2396 default = super().get_default()
2397 if default == "":
2398 return b""
2399 return default
2400
2401 def get_db_prep_value(self, value, connection, prepared=False):
2402 value = super().get_db_prep_value(value, connection, prepared)
2403 if value is not None:
2404 return connection.Database.Binary(value)
2405 return value
2406
2407 def value_to_string(self, obj):
2408 """Binary data is serialized as base64"""
2409 return b64encode(self.value_from_object(obj)).decode("ascii")
2410
2411 def to_python(self, value):
2412 # If it's a string, it should be base64-encoded data
2413 if isinstance(value, str):
2414 return memoryview(b64decode(value.encode("ascii")))
2415 return value
2416
2417
2418class UUIDField(Field):
2419 default_error_messages = {
2420 "invalid": _("“%(value)s” is not a valid UUID."),
2421 }
2422 description = _("Universally unique identifier")
2423 empty_strings_allowed = False
2424
2425 def __init__(self, verbose_name=None, **kwargs):
2426 kwargs["max_length"] = 32
2427 super().__init__(verbose_name, **kwargs)
2428
2429 def deconstruct(self):
2430 name, path, args, kwargs = super().deconstruct()
2431 del kwargs["max_length"]
2432 return name, path, args, kwargs
2433
2434 def get_internal_type(self):
2435 return "UUIDField"
2436
2437 def get_prep_value(self, value):
2438 value = super().get_prep_value(value)
2439 return self.to_python(value)
2440
2441 def get_db_prep_value(self, value, connection, prepared=False):
2442 if value is None:
2443 return None
2444 if not isinstance(value, uuid.UUID):
2445 value = self.to_python(value)
2446
2447 if connection.features.has_native_uuid_field:
2448 return value
2449 return value.hex
2450
2451 def to_python(self, value):
2452 if value is not None and not isinstance(value, uuid.UUID):
2453 input_form = "int" if isinstance(value, int) else "hex"
2454 try:
2455 return uuid.UUID(**{input_form: value})
2456 except (AttributeError, ValueError):
2457 raise exceptions.ValidationError(
2458 self.error_messages["invalid"],
2459 code="invalid",
2460 params={"value": value},
2461 )
2462 return value
2463
2464 def formfield(self, **kwargs):
2465 return super().formfield(**{"form_class": forms.UUIDField, **kwargs,})
2466
2467
2468class AutoFieldMixin:
2469 db_returning = True
2470
2471 def __init__(self, *args, **kwargs):
2472 kwargs["blank"] = True
2473 super().__init__(*args, **kwargs)
2474
2475 def check(self, **kwargs):
2476 return [
2477 *super().check(**kwargs),
2478 *self._check_primary_key(),
2479 ]
2480
2481 def _check_primary_key(self):
2482 if not self.primary_key:
2483 return [
2484 checks.Error(
2485 "AutoFields must set primary_key=True.", obj=self, id="fields.E100",
2486 ),
2487 ]
2488 else:
2489 return []
2490
2491 def deconstruct(self):
2492 name, path, args, kwargs = super().deconstruct()
2493 del kwargs["blank"]
2494 kwargs["primary_key"] = True
2495 return name, path, args, kwargs
2496
2497 def validate(self, value, model_instance):
2498 pass
2499
2500 def get_db_prep_value(self, value, connection, prepared=False):
2501 if not prepared:
2502 value = self.get_prep_value(value)
2503 value = connection.ops.validate_autopk_value(value)
2504 return value
2505
2506 def contribute_to_class(self, cls, name, **kwargs):
2507 assert not cls._meta.auto_field, (
2508 "Model %s can't have more than one auto-generated field." % cls._meta.label
2509 )
2510 super().contribute_to_class(cls, name, **kwargs)
2511 cls._meta.auto_field = self
2512
2513 def formfield(self, **kwargs):
2514 return None
2515
2516
2517class AutoFieldMeta(type):
2518 """
2519 Metaclass to maintain backward inheritance compatibility for AutoField.
2520
2521 It is intended that AutoFieldMixin become public API when it is possible to
2522 create a non-integer automatically-generated field using column defaults
2523 stored in the database.
2524
2525 In many areas Django also relies on using isinstance() to check for an
2526 automatically-generated field as a subclass of AutoField. A new flag needs
2527 to be implemented on Field to be used instead.
2528
2529 When these issues have been addressed, this metaclass could be used to
2530 deprecate inheritance from AutoField and use of isinstance() with AutoField
2531 for detecting automatically-generated fields.
2532 """
2533
2534 @property
2535 def _subclasses(self):
2536 return (BigAutoField, SmallAutoField)
2537
2538 def __instancecheck__(self, instance):
2539 return isinstance(instance, self._subclasses) or super().__instancecheck__(
2540 instance
2541 )
2542
2543 def __subclasscheck__(self, subclass):
2544 return subclass in self._subclasses or super().__subclasscheck__(subclass)
2545
2546
2547class AutoField(AutoFieldMixin, IntegerField, metaclass=AutoFieldMeta):
2548 def get_internal_type(self):
2549 return "AutoField"
2550
2551 def rel_db_type(self, connection):
2552 return IntegerField().db_type(connection=connection)
2553
2554
2555class BigAutoField(AutoFieldMixin, BigIntegerField):
2556 def get_internal_type(self):
2557 return "BigAutoField"
2558
2559 def rel_db_type(self, connection):
2560 return BigIntegerField().db_type(connection=connection)
2561
2562
2563class SmallAutoField(AutoFieldMixin, SmallIntegerField):
2564 def get_internal_type(self):
2565 return "SmallAutoField"
2566
2567 def rel_db_type(self, connection):
2568 return SmallIntegerField().db_type(connection=connection)