Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.10/site-packages/django/db/models/fields/__init_

1import copy

2import datetime

3import decimal

4import operator

5import uuid

6import warnings

7from base64 import b64decode, b64encode

8from collections.abc import Iterable

9from functools import partialmethod, total_ordering

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.db.utils import NotSupportedError

19from django.utils import timezone

20from django.utils.choices import (

21 BlankChoiceIterator,

22 CallableChoiceIterator,

23 flatten_choices,

24 normalize_choices,

25)

26from django.utils.datastructures import DictWrapper

27from django.utils.dateparse import (

28 parse_date,

29 parse_datetime,

30 parse_duration,

31 parse_time,

32)

33from django.utils.duration import duration_microseconds, duration_string

34from django.utils.functional import Promise, cached_property

35from django.utils.ipv6 import MAX_IPV6_ADDRESS_LENGTH, clean_ipv6_address

36from django.utils.text import capfirst

37from django.utils.translation import gettext_lazy as _

39__all__ = [

40 "AutoField",

41 "BLANK_CHOICE_DASH",

42 "BigAutoField",

43 "BigIntegerField",

44 "BinaryField",

45 "BooleanField",

46 "CharField",

47 "CommaSeparatedIntegerField",

48 "DateField",

49 "DateTimeField",

50 "DecimalField",

51 "DurationField",

52 "EmailField",

53 "Empty",

54 "Field",

55 "FilePathField",

56 "FloatField",

57 "GenericIPAddressField",

58 "IPAddressField",

59 "IntegerField",

60 "NOT_PROVIDED",

61 "NullBooleanField",

62 "PositiveBigIntegerField",

63 "PositiveIntegerField",

64 "PositiveSmallIntegerField",

65 "SlugField",

66 "SmallAutoField",

67 "SmallIntegerField",

68 "TextField",

69 "TimeField",

70 "URLField",

71 "UUIDField",

72]

75class Empty:

76 pass

79class NOT_PROVIDED:

80 pass

83# The values to use for "blank" in SelectFields. Will be appended to the start

84# of most "choices" lists.

85BLANK_CHOICE_DASH = [("", "---------")]

88def _load_field(app_label, model_name, field_name):

89 return apps.get_model(app_label, model_name)._meta.get_field(field_name)

92# A guide to Field parameters:

93#

94# * name: The name of the field specified in the model.

95# * attname: The attribute to use on the model object. This is the same as

96# "name", except in the case of ForeignKeys, where "_id" is

97# appended.

98# * db_column: The db_column specified in the model (or None).

99# * column: The database column for this field. This is the same as

100# "attname", except if db_column is specified.

101#

102# Code that introspects values, or does other dynamic things, should use

103# attname. For example, this gets the primary key value of object "obj":

104#

105# getattr(obj, opts.pk.attname)

106

107

108def _empty(of_cls):

109 new = Empty()

110 new.__class__ = of_cls

111 return new

112

113

114def return_None():

115 return None

116

117

118@total_ordering

119class Field(RegisterLookupMixin):

120 """Base class for all field types"""

121

122 # Designates whether empty strings fundamentally are allowed at the

123 # database level.

124 empty_strings_allowed = True

125 empty_values = list(validators.EMPTY_VALUES)

126

127 # These track each time a Field instance is created. Used to retain order.

128 # The auto_creation_counter is used for fields that Django implicitly

129 # creates, creation_counter is used for all user-specified fields.

130 creation_counter = 0

131 auto_creation_counter = -1

132 default_validators = [] # Default set of validators

133 default_error_messages = {

134 "invalid_choice": _("Value %(value)r is not a valid choice."),

135 "null": _("This field cannot be null."),

136 "blank": _("This field cannot be blank."),

137 "unique": _("%(model_name)s with this %(field_label)s already exists."),

138 "unique_for_date": _(

139 # Translators: The 'lookup_type' is one of 'date', 'year' or

140 # 'month'. Eg: "Title must be unique for pub_date year"

141 "%(field_label)s must be unique for "

142 "%(date_field_label)s %(lookup_type)s."

143 ),

144 }

145 system_check_deprecated_details = None

146 system_check_removed_details = None

147

148 # Attributes that don't affect a column definition.

149 # These attributes are ignored when altering the field.

150 non_db_attrs = (

151 "blank",

152 "choices",

153 "db_column",

154 "editable",

155 "error_messages",

156 "help_text",

157 "limit_choices_to",

158 # Database-level options are not supported, see #21961.

159 "on_delete",

160 "related_name",

161 "related_query_name",

162 "validators",

163 "verbose_name",

164 )

165

166 # Field flags

167 hidden = False

168

169 many_to_many = None

170 many_to_one = None

171 one_to_many = None

172 one_to_one = None

173 related_model = None

174 generated = False

175

176 descriptor_class = DeferredAttribute

177

178 # Generic field type description, usually overridden by subclasses

179 def _description(self):

180 return _("Field of type: %(field_type)s") % {

181 "field_type": self.__class__.__name__

182 }

183

184 description = property(_description)

185

186 def __init__(

187 self,

188 verbose_name=None,

189 name=None,

190 primary_key=False,

191 max_length=None,

192 unique=False,

193 blank=False,

194 null=False,

195 db_index=False,

196 rel=None,

197 default=NOT_PROVIDED,

198 editable=True,

199 serialize=True,

200 unique_for_date=None,

201 unique_for_month=None,

202 unique_for_year=None,

203 choices=None,

204 help_text="",

205 db_column=None,

206 db_tablespace=None,

207 auto_created=False,

208 validators=(),

209 error_messages=None,

210 db_comment=None,

211 db_default=NOT_PROVIDED,

212 ):

213 self.name = name

214 self.verbose_name = verbose_name # May be set by set_attributes_from_name

215 self._verbose_name = verbose_name # Store original for deconstruction

216 self.primary_key = primary_key

217 self.max_length, self._unique = max_length, unique

218 self.blank, self.null = blank, null

219 self.remote_field = rel

220 self.is_relation = self.remote_field is not None

221 self.default = default

222 self.db_default = db_default

223 self.editable = editable

224 self.serialize = serialize

225 self.unique_for_date = unique_for_date

226 self.unique_for_month = unique_for_month

227 self.unique_for_year = unique_for_year

228 self.choices = choices

229 self.help_text = help_text

230 self.db_index = db_index

231 self.db_column = db_column

232 self.db_comment = db_comment

233 self._db_tablespace = db_tablespace

234 self.auto_created = auto_created

235

236 # Adjust the appropriate creation counter, and save our local copy.

237 if auto_created:

238 self.creation_counter = Field.auto_creation_counter

239 Field.auto_creation_counter -= 1

240 else:

241 self.creation_counter = Field.creation_counter

242 Field.creation_counter += 1

243

244 self._validators = list(validators) # Store for deconstruction later

245

246 self._error_messages = error_messages # Store for deconstruction later

247

248 def __str__(self):

249 """

250 Return "app_label.model_label.field_name" for fields attached to

251 models.

252 """

253 if not hasattr(self, "model"):

254 return super().__str__()

255 model = self.model

256 return "%s.%s" % (model._meta.label, self.name)

257

258 def __repr__(self):

259 """Display the module, class, and name of the field."""

260 path = "%s.%s" % (self.__class__.__module__, self.__class__.__qualname__)

261 name = getattr(self, "name", None)

262 if name is not None:

263 return "<%s: %s>" % (path, name)

264 return "<%s>" % path

265

266 def check(self, **kwargs):

267 return [

268 *self._check_field_name(),

269 *self._check_choices(),

270 *self._check_db_default(**kwargs),

271 *self._check_db_index(),

272 *self._check_db_comment(**kwargs),

273 *self._check_null_allowed_for_primary_keys(),

274 *self._check_backend_specific_checks(**kwargs),

275 *self._check_validators(),

276 *self._check_deprecation_details(),

277 ]

278

279 def _check_field_name(self):

280 """

281 Check if field name is valid, i.e. 1) does not end with an

282 underscore, 2) does not contain "__" and 3) is not "pk".

283 """

284 if self.name is None:

285 return []

286 if self.name.endswith("_"):

287 return [

288 checks.Error(

289 "Field names must not end with an underscore.",

290 obj=self,

291 id="fields.E001",

292 )

293 ]

294 elif LOOKUP_SEP in self.name:

295 return [

296 checks.Error(

297 'Field names must not contain "%s".' % LOOKUP_SEP,

298 obj=self,

299 id="fields.E002",

300 )

301 ]

302 elif self.name == "pk":

303 return [

304 checks.Error(

305 "'pk' is a reserved word that cannot be used as a field name.",

306 obj=self,

307 id="fields.E003",

308 )

309 ]

310 else:

311 return []

312

313 @classmethod

314 def _choices_is_value(cls, value):

315 return isinstance(value, (str, Promise)) or not isinstance(value, Iterable)

316

317 def _check_choices(self):

318 if not self.choices:

319 return []

320

321 if not isinstance(self.choices, Iterable) or isinstance(self.choices, str):

322 return [

323 checks.Error(

324 "'choices' must be a mapping (e.g. a dictionary) or an iterable "

325 "(e.g. a list or tuple).",

326 obj=self,

327 id="fields.E004",

328 )

329 ]

330

331 choice_max_length = 0

332 # Expect [group_name, [value, display]]

333 for choices_group in self.choices:

334 try:

335 group_name, group_choices = choices_group

336 except (TypeError, ValueError):

337 # Containing non-pairs

338 break

339 try:

340 if not all(

341 self._choices_is_value(value) and self._choices_is_value(human_name)

342 for value, human_name in group_choices

343 ):

344 break

345 if self.max_length is not None and group_choices:

346 choice_max_length = max(

347 [

348 choice_max_length,

349 *(

350 len(value)

351 for value, _ in group_choices

352 if isinstance(value, str)

353 ),

354 ]

355 )

356 except (TypeError, ValueError):

357 # No groups, choices in the form [value, display]

358 value, human_name = group_name, group_choices

359 if not self._choices_is_value(value) or not self._choices_is_value(

360 human_name

361 ):

362 break

363 if self.max_length is not None and isinstance(value, str):

364 choice_max_length = max(choice_max_length, len(value))

365

366 # Special case: choices=['ab']

367 if isinstance(choices_group, str):

368 break

369 else:

370 if self.max_length is not None and choice_max_length > self.max_length:

371 return [

372 checks.Error(

373 "'max_length' is too small to fit the longest value "

374 "in 'choices' (%d characters)." % choice_max_length,

375 obj=self,

376 id="fields.E009",

377 ),

378 ]

379 return []

380

381 return [

382 checks.Error(

383 "'choices' must be a mapping of actual values to human readable names "

384 "or an iterable containing (actual value, human readable name) tuples.",

385 obj=self,

386 id="fields.E005",

387 )

388 ]

389

390 def _check_db_default(self, databases=None, **kwargs):

391 from django.db.models.expressions import Value

392

393 if (

394 not self.has_db_default()

395 or (

396 isinstance(self.db_default, Value)

397 or not hasattr(self.db_default, "resolve_expression")

398 )

399 or databases is None

400 ):

401 return []

402 errors = []

403 for db in databases:

404 if not router.allow_migrate_model(db, self.model):

405 continue

406 connection = connections[db]

407

408 if not getattr(self._db_default_expression, "allowed_default", False) and (

409 connection.features.supports_expression_defaults

410 ):

411 msg = f"{self.db_default} cannot be used in db_default."

412 errors.append(checks.Error(msg, obj=self, id="fields.E012"))

413

414 if not (

415 connection.features.supports_expression_defaults

416 or "supports_expression_defaults"

417 in self.model._meta.required_db_features

418 ):

419 msg = (

420 f"{connection.display_name} does not support default database "

421 "values with expressions (db_default)."

422 )

423 errors.append(checks.Error(msg, obj=self, id="fields.E011"))

424 return errors

425

426 def _check_db_index(self):

427 if self.db_index not in (None, True, False):

428 return [

429 checks.Error(

430 "'db_index' must be None, True or False.",

431 obj=self,

432 id="fields.E006",

433 )

434 ]

435 else:

436 return []

437

438 def _check_db_comment(self, databases=None, **kwargs):

439 if not self.db_comment or not databases:

440 return []

441 errors = []

442 for db in databases:

443 if not router.allow_migrate_model(db, self.model):

444 continue

445 connection = connections[db]

446 if not (

447 connection.features.supports_comments

448 or "supports_comments" in self.model._meta.required_db_features

449 ):

450 errors.append(

451 checks.Warning(

452 f"{connection.display_name} does not support comments on "

453 f"columns (db_comment).",

454 obj=self,

455 id="fields.W163",

456 )

457 )

458 return errors

459

460 def _check_null_allowed_for_primary_keys(self):

461 if (

462 self.primary_key

463 and self.null

464 and not connection.features.interprets_empty_strings_as_nulls

465 ):

466 # We cannot reliably check this for backends like Oracle which

467 # consider NULL and '' to be equal (and thus set up

468 # character-based fields a little differently).

469 return [

470 checks.Error(

471 "Primary keys must not have null=True.",

472 hint=(

473 "Set null=False on the field, or "

474 "remove primary_key=True argument."

475 ),

476 obj=self,

477 id="fields.E007",

478 )

479 ]

480 else:

481 return []

482

483 def _check_backend_specific_checks(self, databases=None, **kwargs):

484 if databases is None:

485 return []

486 errors = []

487 for alias in databases:

488 if router.allow_migrate_model(alias, self.model):

489 errors.extend(connections[alias].validation.check_field(self, **kwargs))

490 return errors

491

492 def _check_validators(self):

493 errors = []

494 for i, validator in enumerate(self.validators):

495 if not callable(validator):

496 errors.append(

497 checks.Error(

498 "All 'validators' must be callable.",

499 hint=(

500 "validators[{i}] ({repr}) isn't a function or "

501 "instance of a validator class.".format(

502 i=i,

503 repr=repr(validator),

504 )

505 ),

506 obj=self,

507 id="fields.E008",

508 )

509 )

510 return errors

511

512 def _check_deprecation_details(self):

513 if self.system_check_removed_details is not None:

514 return [

515 checks.Error(

516 self.system_check_removed_details.get(

517 "msg",

518 "%s has been removed except for support in historical "

519 "migrations." % self.__class__.__name__,

520 ),

521 hint=self.system_check_removed_details.get("hint"),

522 obj=self,

523 id=self.system_check_removed_details.get("id", "fields.EXXX"),

524 )

525 ]

526 elif self.system_check_deprecated_details is not None:

527 return [

528 checks.Warning(

529 self.system_check_deprecated_details.get(

530 "msg", "%s has been deprecated." % self.__class__.__name__

531 ),

532 hint=self.system_check_deprecated_details.get("hint"),

533 obj=self,

534 id=self.system_check_deprecated_details.get("id", "fields.WXXX"),

535 )

536 ]

537 return []

538

539 def get_col(self, alias, output_field=None):

540 if alias == self.model._meta.db_table and (

541 output_field is None or output_field == self

542 ):

543 return self.cached_col

544 from django.db.models.expressions import Col

545

546 return Col(alias, self, output_field)

547

548 @property

549 def choices(self):

550 return self._choices

551

552 @choices.setter

553 def choices(self, value):

554 self._choices = normalize_choices(value)

555

556 @cached_property

557 def cached_col(self):

558 from django.db.models.expressions import Col

559

560 return Col(self.model._meta.db_table, self)

561

562 def select_format(self, compiler, sql, params):

563 """

564 Custom format for select clauses. For example, GIS columns need to be

565 selected as AsText(table.col) on MySQL as the table.col data can't be

566 used by Django.

567 """

568 return sql, params

569

570 def deconstruct(self):

571 """

572 Return enough information to recreate the field as a 4-tuple:

573

574 * The name of the field on the model, if contribute_to_class() has

575 been run.

576 * The import path of the field, including the class, e.g.

577 django.db.models.IntegerField. This should be the most portable

578 version, so less specific may be better.

579 * A list of positional arguments.

580 * A dict of keyword arguments.

581

582 Note that the positional or keyword arguments must contain values of

583 the following types (including inner values of collection types):

584

585 * None, bool, str, int, float, complex, set, frozenset, list, tuple,

586 dict

587 * UUID

588 * datetime.datetime (naive), datetime.date

589 * top-level classes, top-level functions - will be referenced by their

590 full import path

591 * Storage instances - these have their own deconstruct() method

592

593 This is because the values here must be serialized into a text format

594 (possibly new Python code, possibly JSON) and these are the only types

595 with encoding handlers defined.

596

597 There's no need to return the exact way the field was instantiated this

598 time, just ensure that the resulting field is the same - prefer keyword

599 arguments over positional ones, and omit parameters with their default

600 values.

601 """

602 # Short-form way of fetching all the default parameters

603 keywords = {}

604 possibles = {

605 "verbose_name": None,

606 "primary_key": False,

607 "max_length": None,

608 "unique": False,

609 "blank": False,

610 "null": False,

611 "db_index": False,

612 "default": NOT_PROVIDED,

613 "db_default": NOT_PROVIDED,

614 "editable": True,

615 "serialize": True,

616 "unique_for_date": None,

617 "unique_for_month": None,

618 "unique_for_year": None,

619 "choices": None,

620 "help_text": "",

621 "db_column": None,

622 "db_comment": None,

623 "db_tablespace": None,

624 "auto_created": False,

625 "validators": [],

626 "error_messages": None,

627 }

628 attr_overrides = {

629 "unique": "_unique",

630 "error_messages": "_error_messages",

631 "validators": "_validators",

632 "verbose_name": "_verbose_name",

633 "db_tablespace": "_db_tablespace",

634 }

635 equals_comparison = {"choices", "validators"}

636 for name, default in possibles.items():

637 value = getattr(self, attr_overrides.get(name, name))

638 if isinstance(value, CallableChoiceIterator):

639 value = value.func

640 # Do correct kind of comparison

641 if name in equals_comparison:

642 if value != default:

643 keywords[name] = value

644 else:

645 if value is not default:

646 keywords[name] = value

647 # Work out path - we shorten it for known Django core fields

648 path = "%s.%s" % (self.__class__.__module__, self.__class__.__qualname__)

649 if path.startswith("django.db.models.fields.related"):

650 path = path.replace("django.db.models.fields.related", "django.db.models")

651 elif path.startswith("django.db.models.fields.files"):

652 path = path.replace("django.db.models.fields.files", "django.db.models")

653 elif path.startswith("django.db.models.fields.generated"):

654 path = path.replace("django.db.models.fields.generated", "django.db.models")

655 elif path.startswith("django.db.models.fields.json"):

656 path = path.replace("django.db.models.fields.json", "django.db.models")

657 elif path.startswith("django.db.models.fields.proxy"):

658 path = path.replace("django.db.models.fields.proxy", "django.db.models")

659 elif path.startswith("django.db.models.fields.composite"):

660 path = path.replace("django.db.models.fields.composite", "django.db.models")

661 elif path.startswith("django.db.models.fields"):

662 path = path.replace("django.db.models.fields", "django.db.models")

663 # Return basic info - other fields should override this.

664 return (self.name, path, [], keywords)

665

666 def clone(self):

667 """

668 Uses deconstruct() to clone a new copy of this Field.

669 Will not preserve any class attachments/attribute names.

670 """

671 name, path, args, kwargs = self.deconstruct()

672 return self.__class__(*args, **kwargs)

673

674 def __eq__(self, other):

675 # Needed for @total_ordering

676 if isinstance(other, Field):

677 return self.creation_counter == other.creation_counter and getattr(

678 self, "model", None

679 ) == getattr(other, "model", None)

680 return NotImplemented

681

682 def __lt__(self, other):

683 # This is needed because bisect does not take a comparison function.

684 # Order by creation_counter first for backward compatibility.

685 if isinstance(other, Field):

686 if (

687 self.creation_counter != other.creation_counter

688 or not hasattr(self, "model")

689 and not hasattr(other, "model")

690 ):

691 return self.creation_counter < other.creation_counter

692 elif hasattr(self, "model") != hasattr(other, "model"):

693 return not hasattr(self, "model") # Order no-model fields first

694 else:

695 # creation_counter's are equal, compare only models.

696 return (self.model._meta.app_label, self.model._meta.model_name) < (

697 other.model._meta.app_label,

698 other.model._meta.model_name,

699 )

700 return NotImplemented

701

702 def __hash__(self):

703 return hash(self.creation_counter)

704

705 def __deepcopy__(self, memodict):

706 # We don't have to deepcopy very much here, since most things are not

707 # intended to be altered after initial creation.

708 obj = copy.copy(self)

709 if self.remote_field:

710 obj.remote_field = copy.copy(self.remote_field)

711 if hasattr(self.remote_field, "field") and self.remote_field.field is self:

712 obj.remote_field.field = obj

713 memodict[id(self)] = obj

714 return obj

715

716 def __copy__(self):

717 # We need to avoid hitting __reduce__, so define this

718 # slightly weird copy construct.

719 obj = Empty()

720 obj.__class__ = self.__class__

721 obj.__dict__ = self.__dict__.copy()

722 return obj

723

724 def __reduce__(self):

725 """

726 Pickling should return the model._meta.fields instance of the field,

727 not a new copy of that field. So, use the app registry to load the

728 model and then the field back.

729 """

730 if not hasattr(self, "model"):

731 # Fields are sometimes used without attaching them to models (for

732 # example in aggregation). In this case give back a plain field

733 # instance. The code below will create a new empty instance of

734 # class self.__class__, then update its dict with self.__dict__

735 # values - so, this is very close to normal pickle.

736 state = self.__dict__.copy()

737 # The _get_default cached_property can't be pickled due to lambda

738 # usage.

739 state.pop("_get_default", None)

740 return _empty, (self.__class__,), state

741 return _load_field, (

742 self.model._meta.app_label,

743 self.model._meta.object_name,

744 self.name,

745 )

746

747 def get_pk_value_on_save(self, instance):

748 """

749 Hook to generate new PK values on save. This method is called when

750 saving instances with no primary key value set. If this method returns

751 something else than None, then the returned value is used when saving

752 the new instance.

753 """

754 if self.default:

755 return self.get_default()

756 return None

757

758 def to_python(self, value):

759 """

760 Convert the input value into the expected Python data type, raising

761 django.core.exceptions.ValidationError if the data can't be converted.

762 Return the converted value. Subclasses should override this.

763 """

764 return value

765

766 @cached_property

767 def error_messages(self):

768 messages = {}

769 for c in reversed(self.__class__.__mro__):

770 messages.update(getattr(c, "default_error_messages", {}))

771 messages.update(self._error_messages or {})

772 return messages

773

774 @cached_property

775 def validators(self):

776 """

777 Some validators can't be created at field initialization time.

778 This method provides a way to delay their creation until required.

779 """

780 return [*self.default_validators, *self._validators]

781

782 def run_validators(self, value):

783 if value in self.empty_values:

784 return

785

786 errors = []

787 for v in self.validators:

788 try:

789 v(value)

790 except exceptions.ValidationError as e:

791 if hasattr(e, "code") and e.code in self.error_messages:

792 e.message = self.error_messages[e.code]

793 errors.extend(e.error_list)

794

795 if errors:

796 raise exceptions.ValidationError(errors)

797

798 def validate(self, value, model_instance):

799 """

800 Validate value and raise ValidationError if necessary. Subclasses

801 should override this to provide validation logic.

802 """

803 if not self.editable:

804 # Skip validation for non-editable fields.

805 return

806

807 if self.choices is not None and value not in self.empty_values:

808 for option_key, option_value in self.choices:

809 if isinstance(option_value, (list, tuple)):

810 # This is an optgroup, so look inside the group for

811 # options.

812 for optgroup_key, optgroup_value in option_value:

813 if value == optgroup_key:

814 return

815 elif value == option_key:

816 return

817 raise exceptions.ValidationError(

818 self.error_messages["invalid_choice"],

819 code="invalid_choice",

820 params={"value": value},

821 )

822

823 if value is None and not self.null:

824 raise exceptions.ValidationError(self.error_messages["null"], code="null")

825

826 if not self.blank and value in self.empty_values:

827 raise exceptions.ValidationError(self.error_messages["blank"], code="blank")

828

829 def clean(self, value, model_instance):

830 """

831 Convert the value's type and run validation. Validation errors

832 from to_python() and validate() are propagated. Return the correct

833 value if no error is raised.

834 """

835 value = self.to_python(value)

836 self.validate(value, model_instance)

837 self.run_validators(value)

838 return value

839

840 def db_type_parameters(self, connection):

841 return DictWrapper(self.__dict__, connection.ops.quote_name, "qn_")

842

843 def db_check(self, connection):

844 """

845 Return the database column check constraint for this field, for the

846 provided connection. Works the same way as db_type() for the case that

847 get_internal_type() does not map to a preexisting model field.

848 """

849 data = self.db_type_parameters(connection)

850 try:

851 return (

852 connection.data_type_check_constraints[self.get_internal_type()] % data

853 )

854 except KeyError:

855 return None

856

857 def db_type(self, connection):

858 """

859 Return the database column data type for this field, for the provided

860 connection.

861 """

862 # The default implementation of this method looks at the

863 # backend-specific data_types dictionary, looking up the field by its

864 # "internal type".

865 #

866 # A Field class can implement the get_internal_type() method to specify

867 # which *preexisting* Django Field class it's most similar to -- i.e.,

868 # a custom field might be represented by a TEXT column type, which is

869 # the same as the TextField Django field type, which means the custom

870 # field's get_internal_type() returns 'TextField'.

871 #

872 # But the limitation of the get_internal_type() / data_types approach

873 # is that it cannot handle database column types that aren't already

874 # mapped to one of the built-in Django field types. In this case, you

875 # can implement db_type() instead of get_internal_type() to specify

876 # exactly which wacky database column type you want to use.

877 data = self.db_type_parameters(connection)

878 try:

879 column_type = connection.data_types[self.get_internal_type()]

880 except KeyError:

881 return None

882 else:

883 # column_type is either a single-parameter function or a string.

884 if callable(column_type):

885 return column_type(data)

886 return column_type % data

887

888 def rel_db_type(self, connection):

889 """

890 Return the data type that a related field pointing to this field should

891 use. For example, this method is called by ForeignKey and OneToOneField

892 to determine its data type.

893 """

894 return self.db_type(connection)

895

896 def cast_db_type(self, connection):

897 """Return the data type to use in the Cast() function."""

898 db_type = connection.ops.cast_data_types.get(self.get_internal_type())

899 if db_type:

900 return db_type % self.db_type_parameters(connection)

901 return self.db_type(connection)

902

903 def db_parameters(self, connection):

904 """

905 Extension of db_type(), providing a range of different return values

906 (type, checks). This will look at db_type(), allowing custom model

907 fields to override it.

908 """

909 type_string = self.db_type(connection)

910 check_string = self.db_check(connection)

911 return {

912 "type": type_string,

913 "check": check_string,

914 }

915

916 def db_type_suffix(self, connection):

917 return connection.data_types_suffix.get(self.get_internal_type())

918

919 def get_db_converters(self, connection):

920 if hasattr(self, "from_db_value"):

921 return [self.from_db_value]

922 return []

923

924 @cached_property

925 def unique(self):

926 return self._unique or self.primary_key

927

928 @property

929 def db_tablespace(self):

930 return self._db_tablespace or settings.DEFAULT_INDEX_TABLESPACE

931

932 @property

933 def db_returning(self):

934 """Private API intended only to be used by Django itself."""

935 return (

936 self.has_db_default() and connection.features.can_return_columns_from_insert

937 )

938

939 def set_attributes_from_name(self, name):

940 self.name = self.name or name

941 self.attname, self.column = self.get_attname_column()

942 self.concrete = self.column is not None

943 if self.verbose_name is None and self.name:

944 self.verbose_name = self.name.replace("_", " ")

945

946 def contribute_to_class(self, cls, name, private_only=False):

947 """

948 Register the field with the model class it belongs to.

949

950 If private_only is True, create a separate instance of this field

951 for every subclass of cls, even if cls is not an abstract model.

952 """

953 self.set_attributes_from_name(name)

954 self.model = cls

955 cls._meta.add_field(self, private=private_only)

956 if self.column:

957 setattr(cls, self.attname, self.descriptor_class(self))

958 if self.choices is not None:

959 # Don't override a get_FOO_display() method defined explicitly on

960 # this class, but don't check methods derived from inheritance, to

961 # allow overriding inherited choices. For more complex inheritance

962 # structures users should override contribute_to_class().

963 if "get_%s_display" % self.name not in cls.__dict__:

964 setattr(

965 cls,

966 "get_%s_display" % self.name,

967 partialmethod(cls._get_FIELD_display, field=self),

968 )

969

970 def get_filter_kwargs_for_object(self, obj):

971 """

972 Return a dict that when passed as kwargs to self.model.filter(), would

973 yield all instances having the same value for this field as obj has.

974 """

975 return {self.name: getattr(obj, self.attname)}

976

977 def get_attname(self):

978 return self.name

979

980 def get_attname_column(self):

981 attname = self.get_attname()

982 column = self.db_column or attname

983 return attname, column

984

985 def get_internal_type(self):

986 return self.__class__.__name__

987

988 def pre_save(self, model_instance, add):

989 """Return field's value just before saving."""

990 return getattr(model_instance, self.attname)

991

992 def get_prep_value(self, value):

993 """Perform preliminary non-db specific value checks and conversions."""

994 if isinstance(value, Promise):

995 value = value._proxy____cast()

996 return value

997

998 def get_db_prep_value(self, value, connection, prepared=False):

999 """

1000 Return field's value prepared for interacting with the database backend.

1001

1002 Used by the default implementations of get_db_prep_save().

1003 """

1004 if not prepared:

1005 value = self.get_prep_value(value)

1006 return value

1007

1008 def get_db_prep_save(self, value, connection):

1009 """Return field's value prepared for saving into a database."""

1010 if hasattr(value, "as_sql"):

1011 return value

1012 return self.get_db_prep_value(value, connection=connection, prepared=False)

1013

1014 def has_default(self):

1015 """Return a boolean of whether this field has a default value."""

1016 return self.default is not NOT_PROVIDED

1017

1018 def has_db_default(self):

1019 """Return a boolean of whether this field has a db_default value."""

1020 return self.db_default is not NOT_PROVIDED

1021

1022 def get_default(self):

1023 """Return the default value for this field."""

1024 return self._get_default()

1025

1026 @cached_property

1027 def _get_default(self):

1028 if self.has_default():

1029 if callable(self.default):

1030 return self.default

1031 return lambda: self.default

1032

1033 if self.has_db_default():

1034 from django.db.models.expressions import DatabaseDefault

1035

1036 return lambda: DatabaseDefault(

1037 self._db_default_expression, output_field=self

1038 )

1039

1040 if (

1041 not self.empty_strings_allowed

1042 or self.null

1043 and not connection.features.interprets_empty_strings_as_nulls

1044 ):

1045 return return_None

1046 return str # return empty string

1047

1048 @cached_property

1049 def _db_default_expression(self):

1050 db_default = self.db_default

1051 if self.has_db_default() and not hasattr(db_default, "resolve_expression"):

1052 from django.db.models.expressions import Value

1053

1054 db_default = Value(db_default, self)

1055 return db_default

1056

1057 def get_choices(

1058 self,

1059 include_blank=True,

1060 blank_choice=BLANK_CHOICE_DASH,

1061 limit_choices_to=None,

1062 ordering=(),

1063 ):

1064 """

1065 Return choices with a default blank choices included, for use

1066 as <select> choices for this field.

1067 """

1068 if self.choices is not None:

1069 if include_blank:

1070 return BlankChoiceIterator(self.choices, blank_choice)

1071 return self.choices

1072 rel_model = self.remote_field.model

1073 limit_choices_to = limit_choices_to or self.get_limit_choices_to()

1074 choice_func = operator.attrgetter(

1075 self.remote_field.get_related_field().attname

1076 if hasattr(self.remote_field, "get_related_field")

1077 else "pk"

1078 )

1079 qs = rel_model._default_manager.complex_filter(limit_choices_to)

1080 if ordering:

1081 qs = qs.order_by(*ordering)

1082 return (blank_choice if include_blank else []) + [

1083 (choice_func(x), str(x)) for x in qs

1084 ]

1085

1086 def value_to_string(self, obj):

1087 """

1088 Return a string value of this field from the passed obj.

1089 This is used by the serialization framework.

1090 """

1091 return str(self.value_from_object(obj))

1092

1093 @property

1094 def flatchoices(self):

1095 """Flattened version of choices tuple."""

1096 return list(flatten_choices(self.choices))

1097

1098 def save_form_data(self, instance, data):

1099 setattr(instance, self.name, data)

1100

1101 def formfield(self, form_class=None, choices_form_class=None, **kwargs):

1102 """Return a django.forms.Field instance for this field."""

1103 defaults = {

1104 "required": not self.blank,

1105 "label": capfirst(self.verbose_name),

1106 "help_text": self.help_text,

1107 }

1108 if self.has_default():

1109 if callable(self.default):

1110 defaults["initial"] = self.default

1111 defaults["show_hidden_initial"] = True

1112 else:

1113 defaults["initial"] = self.get_default()

1114 if self.choices is not None:

1115 # Fields with choices get special treatment.

1116 include_blank = self.blank or not (

1117 self.has_default() or "initial" in kwargs

1118 )

1119 defaults["choices"] = self.get_choices(include_blank=include_blank)

1120 defaults["coerce"] = self.to_python

1121 if self.null:

1122 defaults["empty_value"] = None

1123 if choices_form_class is not None:

1124 form_class = choices_form_class

1125 else:

1126 form_class = forms.TypedChoiceField

1127 # Many of the subclass-specific formfield arguments (min_value,

1128 # max_value) don't apply for choice fields, so be sure to only pass

1129 # the values that TypedChoiceField will understand.

1130 for k in list(kwargs):

1131 if k not in (

1132 "coerce",

1133 "empty_value",

1134 "choices",

1135 "required",

1136 "widget",

1137 "label",

1138 "initial",

1139 "help_text",

1140 "error_messages",

1141 "show_hidden_initial",

1142 "disabled",

1143 ):

1144 del kwargs[k]

1145 defaults.update(kwargs)

1146 if form_class is None:

1147 form_class = forms.CharField

1148 return form_class(**defaults)

1149

1150 def value_from_object(self, obj):

1151 """Return the value of this field in the given model instance."""

1152 return getattr(obj, self.attname)

1153

1154 def slice_expression(self, expression, start, length):

1155 """Return a slice of this field."""

1156 raise NotSupportedError("This field does not support slicing.")

1157

1158

1159class BooleanField(Field):

1160 empty_strings_allowed = False

1161 default_error_messages = {

1162 "invalid": _("“%(value)s” value must be either True or False."),

1163 "invalid_nullable": _("“%(value)s” value must be either True, False, or None."),

1164 }

1165 description = _("Boolean (Either True or False)")

1166

1167 def get_internal_type(self):

1168 return "BooleanField"

1169

1170 def to_python(self, value):

1171 if self.null and value in self.empty_values:

1172 return None

1173 if value in (True, False):

1174 # 1/0 are equal to True/False. bool() converts former to latter.

1175 return bool(value)

1176 if value in ("t", "True", "1"):

1177 return True

1178 if value in ("f", "False", "0"):

1179 return False

1180 raise exceptions.ValidationError(

1181 self.error_messages["invalid_nullable" if self.null else "invalid"],

1182 code="invalid",

1183 params={"value": value},

1184 )

1185

1186 def get_prep_value(self, value):

1187 value = super().get_prep_value(value)

1188 if value is None:

1189 return None

1190 return self.to_python(value)

1191

1192 def formfield(self, **kwargs):

1193 if self.choices is not None:

1194 include_blank = not (self.has_default() or "initial" in kwargs)

1195 defaults = {"choices": self.get_choices(include_blank=include_blank)}

1196 else:

1197 form_class = forms.NullBooleanField if self.null else forms.BooleanField

1198 # In HTML checkboxes, 'required' means "must be checked" which is

1199 # different from the choices case ("must select some value").

1200 # required=False allows unchecked checkboxes.

1201 defaults = {"form_class": form_class, "required": False}

1202 return super().formfield(**{**defaults, **kwargs})

1203

1204

1205class CharField(Field):

1206 def __init__(self, *args, db_collation=None, **kwargs):

1207 super().__init__(*args, **kwargs)

1208 self.db_collation = db_collation

1209 if self.max_length is not None:

1210 self.validators.append(validators.MaxLengthValidator(self.max_length))

1211

1212 @property

1213 def description(self):

1214 if self.max_length is not None:

1215 return _("String (up to %(max_length)s)")

1216 else:

1217 return _("String (unlimited)")

1218

1219 def check(self, **kwargs):

1220 databases = kwargs.get("databases") or []

1221 return [

1222 *super().check(**kwargs),

1223 *self._check_db_collation(databases),

1224 *self._check_max_length_attribute(**kwargs),

1225 ]

1226

1227 def _check_max_length_attribute(self, **kwargs):

1228 if self.max_length is None:

1229 if (

1230 connection.features.supports_unlimited_charfield

1231 or "supports_unlimited_charfield"

1232 in self.model._meta.required_db_features

1233 ):

1234 return []

1235 return [

1236 checks.Error(

1237 "CharFields must define a 'max_length' attribute.",

1238 obj=self,

1239 id="fields.E120",

1240 )

1241 ]

1242 elif (

1243 not isinstance(self.max_length, int)

1244 or isinstance(self.max_length, bool)

1245 or self.max_length <= 0

1246 ):

1247 return [

1248 checks.Error(

1249 "'max_length' must be a positive integer.",

1250 obj=self,

1251 id="fields.E121",

1252 )

1253 ]

1254 else:

1255 return []

1256

1257 def _check_db_collation(self, databases):

1258 errors = []

1259 for db in databases:

1260 if not router.allow_migrate_model(db, self.model):

1261 continue

1262 connection = connections[db]

1263 if not (

1264 self.db_collation is None

1265 or "supports_collation_on_charfield"

1266 in self.model._meta.required_db_features

1267 or connection.features.supports_collation_on_charfield

1268 ):

1269 errors.append(

1270 checks.Error(

1271 "%s does not support a database collation on "

1272 "CharFields." % connection.display_name,

1273 obj=self,

1274 id="fields.E190",

1275 ),

1276 )

1277 return errors

1278

1279 def cast_db_type(self, connection):

1280 if self.max_length is None:

1281 return connection.ops.cast_char_field_without_max_length

1282 return super().cast_db_type(connection)

1283

1284 def db_parameters(self, connection):

1285 db_params = super().db_parameters(connection)

1286 db_params["collation"] = self.db_collation

1287 return db_params

1288

1289 def get_internal_type(self):

1290 return "CharField"

1291

1292 def to_python(self, value):

1293 if isinstance(value, str) or value is None:

1294 return value

1295 return str(value)

1296

1297 def get_prep_value(self, value):

1298 value = super().get_prep_value(value)

1299 return self.to_python(value)

1300

1301 def formfield(self, **kwargs):

1302 # Passing max_length to forms.CharField means that the value's length

1303 # will be validated twice. This is considered acceptable since we want

1304 # the value in the form field (to pass into widget for example).

1305 defaults = {"max_length": self.max_length}

1306 # TODO: Handle multiple backends with different feature flags.

1307 if self.null and not connection.features.interprets_empty_strings_as_nulls:

1308 defaults["empty_value"] = None

1309 defaults.update(kwargs)

1310 return super().formfield(**defaults)

1311

1312 def deconstruct(self):

1313 name, path, args, kwargs = super().deconstruct()

1314 if self.db_collation:

1315 kwargs["db_collation"] = self.db_collation

1316 return name, path, args, kwargs

1317

1318 def slice_expression(self, expression, start, length):

1319 from django.db.models.functions import Substr

1320

1321 return Substr(expression, start, length)

1322

1323

1324class CommaSeparatedIntegerField(CharField):

1325 default_validators = [validators.validate_comma_separated_integer_list]

1326 description = _("Comma-separated integers")

1327 system_check_removed_details = {

1328 "msg": (

1329 "CommaSeparatedIntegerField is removed except for support in "

1330 "historical migrations."

1331 ),

1332 "hint": (

1333 "Use CharField(validators=[validate_comma_separated_integer_list]) "

1334 "instead."

1335 ),

1336 "id": "fields.E901",

1337 }

1338

1339

1340def _to_naive(value):

1341 if timezone.is_aware(value):

1342 value = timezone.make_naive(value, datetime.timezone.utc)

1343 return value

1344

1345

1346def _get_naive_now():

1347 return _to_naive(timezone.now())

1348

1349

1350class DateTimeCheckMixin:

1351 def check(self, **kwargs):

1352 return [

1353 *super().check(**kwargs),

1354 *self._check_mutually_exclusive_options(),

1355 *self._check_fix_default_value(),

1356 ]

1357

1358 def _check_mutually_exclusive_options(self):

1359 # auto_now, auto_now_add, and default are mutually exclusive

1360 # options. The use of more than one of these options together

1361 # will trigger an Error

1362 mutually_exclusive_options = [

1363 self.auto_now_add,

1364 self.auto_now,

1365 self.has_default(),

1366 ]

1367 enabled_options = [

1368 option not in (None, False) for option in mutually_exclusive_options

1369 ].count(True)

1370 if enabled_options > 1:

1371 return [

1372 checks.Error(

1373 "The options auto_now, auto_now_add, and default "

1374 "are mutually exclusive. Only one of these options "

1375 "may be present.",

1376 obj=self,

1377 id="fields.E160",

1378 )

1379 ]

1380 else:

1381 return []

1382

1383 def _check_fix_default_value(self):

1384 return []

1385

1386 # Concrete subclasses use this in their implementations of

1387 # _check_fix_default_value().

1388 def _check_if_value_fixed(self, value, now=None):

1389 """

1390 Check if the given value appears to have been provided as a "fixed"

1391 time value, and include a warning in the returned list if it does. The

1392 value argument must be a date object or aware/naive datetime object. If

1393 now is provided, it must be a naive datetime object.

1394 """

1395 if now is None:

1396 now = _get_naive_now()

1397 offset = datetime.timedelta(seconds=10)

1398 lower = now - offset

1399 upper = now + offset

1400 if isinstance(value, datetime.datetime):

1401 value = _to_naive(value)

1402 else:

1403 assert isinstance(value, datetime.date)

1404 lower = lower.date()

1405 upper = upper.date()

1406 if lower <= value <= upper:

1407 return [

1408 checks.Warning(

1409 "Fixed default value provided.",

1410 hint=(

1411 "It seems you set a fixed date / time / datetime "

1412 "value as default for this field. This may not be "

1413 "what you want. If you want to have the current date "

1414 "as default, use `django.utils.timezone.now`"

1415 ),

1416 obj=self,

1417 id="fields.W161",

1418 )

1419 ]

1420 return []

1421

1422

1423class DateField(DateTimeCheckMixin, Field):

1424 empty_strings_allowed = False

1425 default_error_messages = {

1426 "invalid": _(

1427 "“%(value)s” value has an invalid date format. It must be "

1428 "in YYYY-MM-DD format."

1429 ),

1430 "invalid_date": _(

1431 "“%(value)s” value has the correct format (YYYY-MM-DD) "

1432 "but it is an invalid date."

1433 ),

1434 }

1435 description = _("Date (without time)")

1436

1437 def __init__(

1438 self, verbose_name=None, name=None, auto_now=False, auto_now_add=False, **kwargs

1439 ):

1440 self.auto_now, self.auto_now_add = auto_now, auto_now_add

1441 if auto_now or auto_now_add:

1442 kwargs["editable"] = False

1443 kwargs["blank"] = True

1444 super().__init__(verbose_name, name, **kwargs)

1445

1446 def _check_fix_default_value(self):

1447 """

1448 Warn that using an actual date or datetime value is probably wrong;

1449 it's only evaluated on server startup.

1450 """

1451 if not self.has_default():

1452 return []

1453

1454 value = self.default

1455 if isinstance(value, datetime.datetime):

1456 value = _to_naive(value).date()

1457 elif isinstance(value, datetime.date):

1458 pass

1459 else:

1460 # No explicit date / datetime value -- no checks necessary

1461 return []

1462 # At this point, value is a date object.

1463 return self._check_if_value_fixed(value)

1464

1465 def deconstruct(self):

1466 name, path, args, kwargs = super().deconstruct()

1467 if self.auto_now:

1468 kwargs["auto_now"] = True

1469 if self.auto_now_add:

1470 kwargs["auto_now_add"] = True

1471 if self.auto_now or self.auto_now_add:

1472 del kwargs["editable"]

1473 del kwargs["blank"]

1474 return name, path, args, kwargs

1475

1476 def get_internal_type(self):

1477 return "DateField"

1478

1479 def to_python(self, value):

1480 if value is None:

1481 return value

1482 if isinstance(value, datetime.datetime):

1483 if settings.USE_TZ and timezone.is_aware(value):

1484 # Convert aware datetimes to the default time zone

1485 # before casting them to dates (#17742).

1486 default_timezone = timezone.get_default_timezone()

1487 value = timezone.make_naive(value, default_timezone)

1488 return value.date()

1489 if isinstance(value, datetime.date):

1490 return value

1491

1492 try:

1493 parsed = parse_date(value)

1494 if parsed is not None:

1495 return parsed

1496 except ValueError:

1497 raise exceptions.ValidationError(

1498 self.error_messages["invalid_date"],

1499 code="invalid_date",

1500 params={"value": value},

1501 )

1502

1503 raise exceptions.ValidationError(

1504 self.error_messages["invalid"],

1505 code="invalid",

1506 params={"value": value},

1507 )

1508

1509 def pre_save(self, model_instance, add):

1510 if self.auto_now or (self.auto_now_add and add):

1511 value = datetime.date.today()

1512 setattr(model_instance, self.attname, value)

1513 return value

1514 else:

1515 return super().pre_save(model_instance, add)

1516

1517 def contribute_to_class(self, cls, name, **kwargs):

1518 super().contribute_to_class(cls, name, **kwargs)

1519 if not self.null:

1520 setattr(

1521 cls,

1522 "get_next_by_%s" % self.name,

1523 partialmethod(

1524 cls._get_next_or_previous_by_FIELD, field=self, is_next=True

1525 ),

1526 )

1527 setattr(

1528 cls,

1529 "get_previous_by_%s" % self.name,

1530 partialmethod(

1531 cls._get_next_or_previous_by_FIELD, field=self, is_next=False

1532 ),

1533 )

1534

1535 def get_prep_value(self, value):

1536 value = super().get_prep_value(value)

1537 return self.to_python(value)

1538

1539 def get_db_prep_value(self, value, connection, prepared=False):

1540 # Casts dates into the format expected by the backend

1541 if not prepared:

1542 value = self.get_prep_value(value)

1543 return connection.ops.adapt_datefield_value(value)

1544

1545 def value_to_string(self, obj):

1546 val = self.value_from_object(obj)

1547 return "" if val is None else val.isoformat()

1548

1549 def formfield(self, **kwargs):

1550 return super().formfield(

1551 **{

1552 "form_class": forms.DateField,

1553 **kwargs,

1554 }

1555 )

1556

1557

1558class DateTimeField(DateField):

1559 empty_strings_allowed = False

1560 default_error_messages = {

1561 "invalid": _(

1562 "“%(value)s” value has an invalid format. It must be in "

1563 "YYYY-MM-DD HH:MM[:ss[.uuuuuu]][TZ] format."

1564 ),

1565 "invalid_date": _(

1566 "“%(value)s” value has the correct format "

1567 "(YYYY-MM-DD) but it is an invalid date."

1568 ),

1569 "invalid_datetime": _(

1570 "“%(value)s” value has the correct format "

1571 "(YYYY-MM-DD HH:MM[:ss[.uuuuuu]][TZ]) "

1572 "but it is an invalid date/time."

1573 ),

1574 }

1575 description = _("Date (with time)")

1576

1577 # __init__ is inherited from DateField

1578

1579 def _check_fix_default_value(self):

1580 """

1581 Warn that using an actual date or datetime value is probably wrong;

1582 it's only evaluated on server startup.

1583 """

1584 if not self.has_default():

1585 return []

1586

1587 value = self.default

1588 if isinstance(value, (datetime.datetime, datetime.date)):

1589 return self._check_if_value_fixed(value)

1590 # No explicit date / datetime value -- no checks necessary.

1591 return []

1592

1593 def get_internal_type(self):

1594 return "DateTimeField"

1595

1596 def to_python(self, value):

1597 if value is None:

1598 return value

1599 if isinstance(value, datetime.datetime):

1600 return value

1601 if isinstance(value, datetime.date):

1602 value = datetime.datetime(value.year, value.month, value.day)

1603 if settings.USE_TZ:

1604 # For backwards compatibility, interpret naive datetimes in

1605 # local time. This won't work during DST change, but we can't

1606 # do much about it, so we let the exceptions percolate up the

1607 # call stack.

1608 try:

1609 name = f"{self.model.__name__}.{self.name}"

1610 except AttributeError:

1611 name = "(unbound)"

1612 warnings.warn(

1613 f"DateTimeField {name} received a naive datetime ({value}) while "

1614 "time zone support is active.",

1615 RuntimeWarning,

1616 )

1617 default_timezone = timezone.get_default_timezone()

1618 value = timezone.make_aware(value, default_timezone)

1619 return value

1620

1621 try:

1622 parsed = parse_datetime(value)

1623 if parsed is not None:

1624 return parsed

1625 except ValueError:

1626 raise exceptions.ValidationError(

1627 self.error_messages["invalid_datetime"],

1628 code="invalid_datetime",

1629 params={"value": value},

1630 )

1631

1632 try:

1633 parsed = parse_date(value)

1634 if parsed is not None:

1635 return datetime.datetime(parsed.year, parsed.month, parsed.day)

1636 except ValueError:

1637 raise exceptions.ValidationError(

1638 self.error_messages["invalid_date"],

1639 code="invalid_date",

1640 params={"value": value},

1641 )

1642

1643 raise exceptions.ValidationError(

1644 self.error_messages["invalid"],

1645 code="invalid",

1646 params={"value": value},

1647 )

1648

1649 def pre_save(self, model_instance, add):

1650 if self.auto_now or (self.auto_now_add and add):

1651 value = timezone.now()

1652 setattr(model_instance, self.attname, value)

1653 return value

1654 else:

1655 return super().pre_save(model_instance, add)

1656

1657 # contribute_to_class is inherited from DateField, it registers

1658 # get_next_by_FOO and get_prev_by_FOO

1659

1660 def get_prep_value(self, value):

1661 value = super().get_prep_value(value)

1662 value = self.to_python(value)

1663 if value is not None and settings.USE_TZ and timezone.is_naive(value):

1664 # For backwards compatibility, interpret naive datetimes in local

1665 # time. This won't work during DST change, but we can't do much

1666 # about it, so we let the exceptions percolate up the call stack.

1667 try:

1668 name = "%s.%s" % (self.model.__name__, self.name)

1669 except AttributeError:

1670 name = "(unbound)"

1671 warnings.warn(

1672 "DateTimeField %s received a naive datetime (%s)"

1673 " while time zone support is active." % (name, value),

1674 RuntimeWarning,

1675 )

1676 default_timezone = timezone.get_default_timezone()

1677 value = timezone.make_aware(value, default_timezone)

1678 return value

1679

1680 def get_db_prep_value(self, value, connection, prepared=False):

1681 # Casts datetimes into the format expected by the backend

1682 if not prepared:

1683 value = self.get_prep_value(value)

1684 return connection.ops.adapt_datetimefield_value(value)

1685

1686 def value_to_string(self, obj):

1687 val = self.value_from_object(obj)

1688 return "" if val is None else val.isoformat()

1689

1690 def formfield(self, **kwargs):

1691 return super().formfield(

1692 **{

1693 "form_class": forms.DateTimeField,

1694 **kwargs,

1695 }

1696 )

1697

1698

1699class DecimalField(Field):

1700 empty_strings_allowed = False

1701 default_error_messages = {

1702 "invalid": _("“%(value)s” value must be a decimal number."),

1703 }

1704 description = _("Decimal number")

1705

1706 def __init__(

1707 self,

1708 verbose_name=None,

1709 name=None,

1710 max_digits=None,

1711 decimal_places=None,

1712 **kwargs,

1713 ):

1714 self.max_digits, self.decimal_places = max_digits, decimal_places

1715 super().__init__(verbose_name, name, **kwargs)

1716

1717 def check(self, **kwargs):

1718 errors = super().check(**kwargs)

1719

1720 digits_errors = [

1721 *self._check_decimal_places(),

1722 *self._check_max_digits(),

1723 ]

1724 if not digits_errors:

1725 errors.extend(self._check_decimal_places_and_max_digits(**kwargs))

1726 else:

1727 errors.extend(digits_errors)

1728 return errors

1729

1730 def _check_decimal_places(self):

1731 try:

1732 decimal_places = int(self.decimal_places)

1733 if decimal_places < 0:

1734 raise ValueError()

1735 except TypeError:

1736 return [

1737 checks.Error(

1738 "DecimalFields must define a 'decimal_places' attribute.",

1739 obj=self,

1740 id="fields.E130",

1741 )

1742 ]

1743 except ValueError:

1744 return [

1745 checks.Error(

1746 "'decimal_places' must be a non-negative integer.",

1747 obj=self,

1748 id="fields.E131",

1749 )

1750 ]

1751 else:

1752 return []

1753

1754 def _check_max_digits(self):

1755 try:

1756 max_digits = int(self.max_digits)

1757 if max_digits <= 0:

1758 raise ValueError()

1759 except TypeError:

1760 return [

1761 checks.Error(

1762 "DecimalFields must define a 'max_digits' attribute.",

1763 obj=self,

1764 id="fields.E132",

1765 )

1766 ]

1767 except ValueError:

1768 return [

1769 checks.Error(

1770 "'max_digits' must be a positive integer.",

1771 obj=self,

1772 id="fields.E133",

1773 )

1774 ]

1775 else:

1776 return []

1777

1778 def _check_decimal_places_and_max_digits(self, **kwargs):

1779 if int(self.decimal_places) > int(self.max_digits):

1780 return [

1781 checks.Error(

1782 "'max_digits' must be greater or equal to 'decimal_places'.",

1783 obj=self,

1784 id="fields.E134",

1785 )

1786 ]

1787 return []

1788

1789 @cached_property

1790 def validators(self):

1791 return super().validators + [

1792 validators.DecimalValidator(self.max_digits, self.decimal_places)

1793 ]

1794

1795 @cached_property

1796 def context(self):

1797 return decimal.Context(prec=self.max_digits)

1798

1799 def deconstruct(self):

1800 name, path, args, kwargs = super().deconstruct()

1801 if self.max_digits is not None:

1802 kwargs["max_digits"] = self.max_digits

1803 if self.decimal_places is not None:

1804 kwargs["decimal_places"] = self.decimal_places

1805 return name, path, args, kwargs

1806

1807 def get_internal_type(self):

1808 return "DecimalField"

1809

1810 def to_python(self, value):

1811 if value is None:

1812 return value

1813 try:

1814 if isinstance(value, float):

1815 decimal_value = self.context.create_decimal_from_float(value)

1816 else:

1817 decimal_value = decimal.Decimal(value)

1818 except (decimal.InvalidOperation, TypeError, ValueError):

1819 raise exceptions.ValidationError(

1820 self.error_messages["invalid"],

1821 code="invalid",

1822 params={"value": value},

1823 )

1824 if not decimal_value.is_finite():

1825 raise exceptions.ValidationError(

1826 self.error_messages["invalid"],

1827 code="invalid",

1828 params={"value": value},

1829 )

1830 return decimal_value

1831

1832 def get_db_prep_value(self, value, connection, prepared=False):

1833 value = super().get_db_prep_value(value, connection, prepared)

1834 return connection.ops.adapt_decimalfield_value(

1835 self.to_python(value), self.max_digits, self.decimal_places

1836 )

1837

1838 def get_prep_value(self, value):

1839 value = super().get_prep_value(value)

1840 return self.to_python(value)

1841

1842 def formfield(self, **kwargs):

1843 return super().formfield(

1844 **{

1845 "max_digits": self.max_digits,

1846 "decimal_places": self.decimal_places,

1847 "form_class": forms.DecimalField,

1848 **kwargs,

1849 }

1850 )

1851

1852

1853class DurationField(Field):

1854 """

1855 Store timedelta objects.

1856

1857 Use interval on PostgreSQL, INTERVAL DAY TO SECOND on Oracle, and bigint

1858 of microseconds on other databases.

1859 """

1860

1861 empty_strings_allowed = False

1862 default_error_messages = {

1863 "invalid": _(

1864 "“%(value)s” value has an invalid format. It must be in "

1865 "[DD] [[HH:]MM:]ss[.uuuuuu] format."

1866 )

1867 }

1868 description = _("Duration")

1869

1870 def get_internal_type(self):

1871 return "DurationField"

1872

1873 def to_python(self, value):

1874 if value is None:

1875 return value

1876 if isinstance(value, datetime.timedelta):

1877 return value

1878 try:

1879 parsed = parse_duration(value)

1880 except ValueError:

1881 pass

1882 else:

1883 if parsed is not None:

1884 return parsed

1885

1886 raise exceptions.ValidationError(

1887 self.error_messages["invalid"],

1888 code="invalid",

1889 params={"value": value},

1890 )

1891

1892 def get_db_prep_value(self, value, connection, prepared=False):

1893 if connection.features.has_native_duration_field:

1894 return value

1895 if value is None:

1896 return None

1897 return duration_microseconds(value)

1898

1899 def get_db_converters(self, connection):

1900 converters = []

1901 if not connection.features.has_native_duration_field:

1902 converters.append(connection.ops.convert_durationfield_value)

1903 return converters + super().get_db_converters(connection)

1904

1905 def value_to_string(self, obj):

1906 val = self.value_from_object(obj)

1907 return "" if val is None else duration_string(val)

1908

1909 def formfield(self, **kwargs):

1910 return super().formfield(

1911 **{

1912 "form_class": forms.DurationField,

1913 **kwargs,

1914 }

1915 )

1916

1917

1918class EmailField(CharField):

1919 default_validators = [validators.validate_email]

1920 description = _("Email address")

1921

1922 def __init__(self, *args, **kwargs):

1923 # max_length=254 to be compliant with RFCs 3696 and 5321

1924 kwargs.setdefault("max_length", 254)

1925 super().__init__(*args, **kwargs)

1926

1927 def deconstruct(self):

1928 name, path, args, kwargs = super().deconstruct()

1929 # We do not exclude max_length if it matches default as we want to change

1930 # the default in future.

1931 return name, path, args, kwargs

1932

1933 def formfield(self, **kwargs):

1934 # As with CharField, this will cause email validation to be performed

1935 # twice.

1936 return super().formfield(

1937 **{

1938 "form_class": forms.EmailField,

1939 **kwargs,

1940 }

1941 )

1942

1943

1944class FilePathField(Field):

1945 description = _("File path")

1946

1947 def __init__(

1948 self,

1949 verbose_name=None,

1950 name=None,

1951 path="",

1952 match=None,

1953 recursive=False,

1954 allow_files=True,

1955 allow_folders=False,

1956 **kwargs,

1957 ):

1958 self.path, self.match, self.recursive = path, match, recursive

1959 self.allow_files, self.allow_folders = allow_files, allow_folders

1960 kwargs.setdefault("max_length", 100)

1961 super().__init__(verbose_name, name, **kwargs)

1962

1963 def check(self, **kwargs):

1964 return [

1965 *super().check(**kwargs),

1966 *self._check_allowing_files_or_folders(**kwargs),

1967 ]

1968

1969 def _check_allowing_files_or_folders(self, **kwargs):

1970 if not self.allow_files and not self.allow_folders:

1971 return [

1972 checks.Error(

1973 "FilePathFields must have either 'allow_files' or 'allow_folders' "

1974 "set to True.",

1975 obj=self,

1976 id="fields.E140",

1977 )

1978 ]

1979 return []

1980

1981 def deconstruct(self):

1982 name, path, args, kwargs = super().deconstruct()

1983 if self.path != "":

1984 kwargs["path"] = self.path

1985 if self.match is not None:

1986 kwargs["match"] = self.match

1987 if self.recursive is not False:

1988 kwargs["recursive"] = self.recursive

1989 if self.allow_files is not True:

1990 kwargs["allow_files"] = self.allow_files

1991 if self.allow_folders is not False:

1992 kwargs["allow_folders"] = self.allow_folders

1993 if kwargs.get("max_length") == 100:

1994 del kwargs["max_length"]

1995 return name, path, args, kwargs

1996

1997 def get_prep_value(self, value):

1998 value = super().get_prep_value(value)

1999 if value is None:

2000 return None

2001 return str(value)

2002

2003 def formfield(self, **kwargs):

2004 return super().formfield(

2005 **{

2006 "path": self.path() if callable(self.path) else self.path,

2007 "match": self.match,

2008 "recursive": self.recursive,

2009 "form_class": forms.FilePathField,

2010 "allow_files": self.allow_files,

2011 "allow_folders": self.allow_folders,

2012 **kwargs,

2013 }

2014 )

2015

2016 def get_internal_type(self):

2017 return "FilePathField"

2018

2019

2020class FloatField(Field):

2021 empty_strings_allowed = False

2022 default_error_messages = {

2023 "invalid": _("“%(value)s” value must be a float."),

2024 }

2025 description = _("Floating point number")

2026

2027 def get_prep_value(self, value):

2028 value = super().get_prep_value(value)

2029 if value is None:

2030 return None

2031 try:

2032 return float(value)

2033 except (TypeError, ValueError) as e:

2034 raise e.__class__(

2035 "Field '%s' expected a number but got %r." % (self.name, value),

2036 ) from e

2037

2038 def get_internal_type(self):

2039 return "FloatField"

2040

2041 def to_python(self, value):

2042 if value is None:

2043 return value

2044 try:

2045 return float(value)

2046 except (TypeError, ValueError):

2047 raise exceptions.ValidationError(

2048 self.error_messages["invalid"],

2049 code="invalid",

2050 params={"value": value},

2051 )

2052

2053 def formfield(self, **kwargs):

2054 return super().formfield(

2055 **{

2056 "form_class": forms.FloatField,

2057 **kwargs,

2058 }

2059 )

2060

2061

2062class IntegerField(Field):

2063 empty_strings_allowed = False

2064 default_error_messages = {

2065 "invalid": _("“%(value)s” value must be an integer."),

2066 }

2067 description = _("Integer")

2068

2069 def check(self, **kwargs):

2070 return [

2071 *super().check(**kwargs),

2072 *self._check_max_length_warning(),

2073 ]

2074

2075 def _check_max_length_warning(self):

2076 if self.max_length is not None:

2077 return [

2078 checks.Warning(

2079 "'max_length' is ignored when used with %s."

2080 % self.__class__.__name__,

2081 hint="Remove 'max_length' from field",

2082 obj=self,

2083 id="fields.W122",

2084 )

2085 ]

2086 return []

2087

2088 @cached_property

2089 def validators(self):

2090 # These validators can't be added at field initialization time since

2091 # they're based on values retrieved from `connection`.

2092 validators_ = super().validators

2093 internal_type = self.get_internal_type()

2094 min_value, max_value = connection.ops.integer_field_range(internal_type)

2095 if min_value is not None and not any(

2096 (

2097 isinstance(validator, validators.MinValueValidator)

2098 and (

2099 validator.limit_value()

2100 if callable(validator.limit_value)

2101 else validator.limit_value

2102 )

2103 >= min_value

2104 )

2105 for validator in validators_

2106 ):

2107 validators_.append(validators.MinValueValidator(min_value))

2108 if max_value is not None and not any(

2109 (

2110 isinstance(validator, validators.MaxValueValidator)

2111 and (

2112 validator.limit_value()

2113 if callable(validator.limit_value)

2114 else validator.limit_value

2115 )

2116 <= max_value

2117 )

2118 for validator in validators_

2119 ):

2120 validators_.append(validators.MaxValueValidator(max_value))

2121 return validators_

2122

2123 def get_prep_value(self, value):

2124 value = super().get_prep_value(value)

2125 if value is None:

2126 return None

2127 try:

2128 return int(value)

2129 except (TypeError, ValueError) as e:

2130 raise e.__class__(

2131 "Field '%s' expected a number but got %r." % (self.name, value),

2132 ) from e

2133

2134 def get_db_prep_value(self, value, connection, prepared=False):

2135 value = super().get_db_prep_value(value, connection, prepared)

2136 return connection.ops.adapt_integerfield_value(value, self.get_internal_type())

2137

2138 def get_internal_type(self):

2139 return "IntegerField"

2140

2141 def to_python(self, value):

2142 if value is None:

2143 return value

2144 try:

2145 return int(value)

2146 except (TypeError, ValueError):

2147 raise exceptions.ValidationError(

2148 self.error_messages["invalid"],

2149 code="invalid",

2150 params={"value": value},

2151 )

2152

2153 def formfield(self, **kwargs):

2154 return super().formfield(

2155 **{

2156 "form_class": forms.IntegerField,

2157 **kwargs,

2158 }

2159 )

2160

2161

2162class BigIntegerField(IntegerField):

2163 description = _("Big (8 byte) integer")

2164 MAX_BIGINT = 9223372036854775807

2165

2166 def get_internal_type(self):

2167 return "BigIntegerField"

2168

2169 def formfield(self, **kwargs):

2170 return super().formfield(

2171 **{

2172 "min_value": -BigIntegerField.MAX_BIGINT - 1,

2173 "max_value": BigIntegerField.MAX_BIGINT,

2174 **kwargs,

2175 }

2176 )

2177

2178

2179class SmallIntegerField(IntegerField):

2180 description = _("Small integer")

2181

2182 def get_internal_type(self):

2183 return "SmallIntegerField"

2184

2185

2186class IPAddressField(Field):

2187 empty_strings_allowed = False

2188 description = _("IPv4 address")

2189 system_check_removed_details = {

2190 "msg": (

2191 "IPAddressField has been removed except for support in "

2192 "historical migrations."

2193 ),

2194 "hint": "Use GenericIPAddressField instead.",

2195 "id": "fields.E900",

2196 }

2197

2198 def __init__(self, *args, **kwargs):

2199 kwargs["max_length"] = 15

2200 super().__init__(*args, **kwargs)

2201

2202 def deconstruct(self):

2203 name, path, args, kwargs = super().deconstruct()

2204 del kwargs["max_length"]

2205 return name, path, args, kwargs

2206

2207 def get_prep_value(self, value):

2208 value = super().get_prep_value(value)

2209 if value is None:

2210 return None

2211 return str(value)

2212

2213 def get_internal_type(self):

2214 return "IPAddressField"

2215

2216

2217class GenericIPAddressField(Field):

2218 empty_strings_allowed = False

2219 description = _("IP address")

2220 default_error_messages = {"invalid": _("Enter a valid %(protocol)s address.")}

2221

2222 def __init__(

2223 self,

2224 verbose_name=None,

2225 name=None,

2226 protocol="both",

2227 unpack_ipv4=False,

2228 *args,

2229 **kwargs,

2230 ):

2231 self.unpack_ipv4 = unpack_ipv4

2232 self.protocol = protocol

2233 self.default_validators = validators.ip_address_validators(

2234 protocol, unpack_ipv4

2235 )

2236 kwargs["max_length"] = MAX_IPV6_ADDRESS_LENGTH

2237 super().__init__(verbose_name, name, *args, **kwargs)

2238

2239 def check(self, **kwargs):

2240 return [

2241 *super().check(**kwargs),

2242 *self._check_blank_and_null_values(**kwargs),

2243 ]

2244

2245 def _check_blank_and_null_values(self, **kwargs):

2246 if not getattr(self, "null", False) and getattr(self, "blank", False):

2247 return [

2248 checks.Error(

2249 "GenericIPAddressFields cannot have blank=True if null=False, "

2250 "as blank values are stored as nulls.",

2251 obj=self,

2252 id="fields.E150",

2253 )

2254 ]

2255 return []

2256

2257 def deconstruct(self):

2258 name, path, args, kwargs = super().deconstruct()

2259 if self.unpack_ipv4 is not False:

2260 kwargs["unpack_ipv4"] = self.unpack_ipv4

2261 if self.protocol != "both":

2262 kwargs["protocol"] = self.protocol

2263 if kwargs.get("max_length") == self.max_length:

2264 del kwargs["max_length"]

2265 return name, path, args, kwargs

2266

2267 def get_internal_type(self):

2268 return "GenericIPAddressField"

2269

2270 def to_python(self, value):

2271 if value is None:

2272 return None

2273 if not isinstance(value, str):

2274 value = str(value)

2275 value = value.strip()

2276 if ":" in value:

2277 return clean_ipv6_address(

2278 value, self.unpack_ipv4, self.error_messages["invalid"]

2279 )

2280 return value

2281

2282 def get_db_prep_value(self, value, connection, prepared=False):

2283 if not prepared:

2284 value = self.get_prep_value(value)

2285 return connection.ops.adapt_ipaddressfield_value(value)

2286

2287 def get_prep_value(self, value):

2288 value = super().get_prep_value(value)

2289 if value is None:

2290 return None

2291 if value and ":" in value:

2292 try:

2293 return clean_ipv6_address(value, self.unpack_ipv4)

2294 except exceptions.ValidationError:

2295 pass

2296 return str(value)

2297

2298 def formfield(self, **kwargs):

2299 return super().formfield(

2300 **{

2301 "protocol": self.protocol,

2302 "form_class": forms.GenericIPAddressField,

2303 **kwargs,

2304 }

2305 )

2306

2307

2308class NullBooleanField(BooleanField):

2309 default_error_messages = {

2310 "invalid": _("“%(value)s” value must be either None, True or False."),

2311 "invalid_nullable": _("“%(value)s” value must be either None, True or False."),

2312 }

2313 description = _("Boolean (Either True, False or None)")

2314 system_check_removed_details = {

2315 "msg": (

2316 "NullBooleanField is removed except for support in historical "

2317 "migrations."

2318 ),

2319 "hint": "Use BooleanField(null=True, blank=True) instead.",

2320 "id": "fields.E903",

2321 }

2322

2323 def __init__(self, *args, **kwargs):

2324 kwargs["null"] = True

2325 kwargs["blank"] = True

2326 super().__init__(*args, **kwargs)

2327

2328 def deconstruct(self):

2329 name, path, args, kwargs = super().deconstruct()

2330 del kwargs["null"]

2331 del kwargs["blank"]

2332 return name, path, args, kwargs

2333

2334

2335class PositiveIntegerRelDbTypeMixin:

2336 def __init_subclass__(cls, **kwargs):

2337 super().__init_subclass__(**kwargs)

2338 if not hasattr(cls, "integer_field_class"):

2339 cls.integer_field_class = next(

2340 (

2341 parent

2342 for parent in cls.__mro__[1:]

2343 if issubclass(parent, IntegerField)

2344 ),

2345 None,

2346 )

2347

2348 def rel_db_type(self, connection):

2349 """

2350 Return the data type that a related field pointing to this field should

2351 use. In most cases, a foreign key pointing to a positive integer

2352 primary key will have an integer column data type but some databases

2353 (e.g. MySQL) have an unsigned integer type. In that case

2354 (related_fields_match_type=True), the primary key should return its

2355 db_type.

2356 """

2357 if connection.features.related_fields_match_type:

2358 return self.db_type(connection)

2359 else:

2360 return self.integer_field_class().db_type(connection=connection)

2361

2362

2363class PositiveBigIntegerField(PositiveIntegerRelDbTypeMixin, BigIntegerField):

2364 description = _("Positive big integer")

2365

2366 def get_internal_type(self):

2367 return "PositiveBigIntegerField"

2368

2369 def formfield(self, **kwargs):

2370 return super().formfield(

2371 **{

2372 "min_value": 0,

2373 **kwargs,

2374 }

2375 )

2376

2377

2378class PositiveIntegerField(PositiveIntegerRelDbTypeMixin, IntegerField):

2379 description = _("Positive integer")

2380

2381 def get_internal_type(self):

2382 return "PositiveIntegerField"

2383

2384 def formfield(self, **kwargs):

2385 return super().formfield(

2386 **{

2387 "min_value": 0,

2388 **kwargs,

2389 }

2390 )

2391

2392

2393class PositiveSmallIntegerField(PositiveIntegerRelDbTypeMixin, SmallIntegerField):

2394 description = _("Positive small integer")

2395

2396 def get_internal_type(self):

2397 return "PositiveSmallIntegerField"

2398

2399 def formfield(self, **kwargs):

2400 return super().formfield(

2401 **{

2402 "min_value": 0,

2403 **kwargs,

2404 }

2405 )

2406

2407

2408class SlugField(CharField):

2409 default_validators = [validators.validate_slug]

2410 description = _("Slug (up to %(max_length)s)")

2411

2412 def __init__(

2413 self, *args, max_length=50, db_index=True, allow_unicode=False, **kwargs

2414 ):

2415 self.allow_unicode = allow_unicode

2416 if self.allow_unicode:

2417 self.default_validators = [validators.validate_unicode_slug]

2418 super().__init__(*args, max_length=max_length, db_index=db_index, **kwargs)

2419

2420 def deconstruct(self):

2421 name, path, args, kwargs = super().deconstruct()

2422 if kwargs.get("max_length") == 50:

2423 del kwargs["max_length"]

2424 if self.db_index is False:

2425 kwargs["db_index"] = False

2426 else:

2427 del kwargs["db_index"]

2428 if self.allow_unicode is not False:

2429 kwargs["allow_unicode"] = self.allow_unicode

2430 return name, path, args, kwargs

2431

2432 def get_internal_type(self):

2433 return "SlugField"

2434

2435 def formfield(self, **kwargs):

2436 return super().formfield(

2437 **{

2438 "form_class": forms.SlugField,

2439 "allow_unicode": self.allow_unicode,

2440 **kwargs,

2441 }

2442 )

2443

2444

2445class TextField(Field):

2446 description = _("Text")

2447

2448 def __init__(self, *args, db_collation=None, **kwargs):

2449 super().__init__(*args, **kwargs)

2450 self.db_collation = db_collation

2451

2452 def check(self, **kwargs):

2453 databases = kwargs.get("databases") or []

2454 return [

2455 *super().check(**kwargs),

2456 *self._check_db_collation(databases),

2457 ]

2458

2459 def _check_db_collation(self, databases):

2460 errors = []

2461 for db in databases:

2462 if not router.allow_migrate_model(db, self.model):

2463 continue

2464 connection = connections[db]

2465 if not (

2466 self.db_collation is None

2467 or "supports_collation_on_textfield"

2468 in self.model._meta.required_db_features

2469 or connection.features.supports_collation_on_textfield

2470 ):

2471 errors.append(

2472 checks.Error(

2473 "%s does not support a database collation on "

2474 "TextFields." % connection.display_name,

2475 obj=self,

2476 id="fields.E190",

2477 ),

2478 )

2479 return errors

2480

2481 def db_parameters(self, connection):

2482 db_params = super().db_parameters(connection)

2483 db_params["collation"] = self.db_collation

2484 return db_params

2485

2486 def get_internal_type(self):

2487 return "TextField"

2488

2489 def to_python(self, value):

2490 if isinstance(value, str) or value is None:

2491 return value

2492 return str(value)

2493

2494 def get_prep_value(self, value):

2495 value = super().get_prep_value(value)

2496 return self.to_python(value)

2497

2498 def formfield(self, **kwargs):

2499 # Passing max_length to forms.CharField means that the value's length

2500 # will be validated twice. This is considered acceptable since we want

2501 # the value in the form field (to pass into widget for example).

2502 return super().formfield(

2503 **{

2504 "max_length": self.max_length,

2505 **({} if self.choices is not None else {"widget": forms.Textarea}),

2506 **kwargs,

2507 }

2508 )

2509

2510 def deconstruct(self):

2511 name, path, args, kwargs = super().deconstruct()

2512 if self.db_collation:

2513 kwargs["db_collation"] = self.db_collation

2514 return name, path, args, kwargs

2515

2516 def slice_expression(self, expression, start, length):

2517 from django.db.models.functions import Substr

2518

2519 return Substr(expression, start, length)

2520

2521

2522class TimeField(DateTimeCheckMixin, Field):

2523 empty_strings_allowed = False

2524 default_error_messages = {

2525 "invalid": _(

2526 "“%(value)s” value has an invalid format. It must be in "

2527 "HH:MM[:ss[.uuuuuu]] format."

2528 ),

2529 "invalid_time": _(

2530 "“%(value)s” value has the correct format "

2531 "(HH:MM[:ss[.uuuuuu]]) but it is an invalid time."

2532 ),

2533 }

2534 description = _("Time")

2535

2536 def __init__(

2537 self, verbose_name=None, name=None, auto_now=False, auto_now_add=False, **kwargs

2538 ):

2539 self.auto_now, self.auto_now_add = auto_now, auto_now_add

2540 if auto_now or auto_now_add:

2541 kwargs["editable"] = False

2542 kwargs["blank"] = True

2543 super().__init__(verbose_name, name, **kwargs)

2544

2545 def _check_fix_default_value(self):

2546 """

2547 Warn that using an actual date or datetime value is probably wrong;

2548 it's only evaluated on server startup.

2549 """

2550 if not self.has_default():

2551 return []

2552

2553 value = self.default

2554 if isinstance(value, datetime.datetime):

2555 now = None

2556 elif isinstance(value, datetime.time):

2557 now = _get_naive_now()

2558 # This will not use the right date in the race condition where now

2559 # is just before the date change and value is just past 0:00.

2560 value = datetime.datetime.combine(now.date(), value)

2561 else:

2562 # No explicit time / datetime value -- no checks necessary

2563 return []

2564 # At this point, value is a datetime object.

2565 return self._check_if_value_fixed(value, now=now)

2566

2567 def deconstruct(self):

2568 name, path, args, kwargs = super().deconstruct()

2569 if self.auto_now is not False:

2570 kwargs["auto_now"] = self.auto_now

2571 if self.auto_now_add is not False:

2572 kwargs["auto_now_add"] = self.auto_now_add

2573 if self.auto_now or self.auto_now_add:

2574 del kwargs["blank"]

2575 del kwargs["editable"]

2576 return name, path, args, kwargs

2577

2578 def get_internal_type(self):

2579 return "TimeField"

2580

2581 def to_python(self, value):

2582 if value is None:

2583 return None

2584 if isinstance(value, datetime.time):

2585 return value

2586 if isinstance(value, datetime.datetime):

2587 # Not usually a good idea to pass in a datetime here (it loses

2588 # information), but this can be a side-effect of interacting with a

2589 # database backend (e.g. Oracle), so we'll be accommodating.

2590 return value.time()

2591

2592 try:

2593 parsed = parse_time(value)

2594 if parsed is not None:

2595 return parsed

2596 except ValueError:

2597 raise exceptions.ValidationError(

2598 self.error_messages["invalid_time"],

2599 code="invalid_time",

2600 params={"value": value},

2601 )

2602

2603 raise exceptions.ValidationError(

2604 self.error_messages["invalid"],

2605 code="invalid",

2606 params={"value": value},

2607 )

2608

2609 def pre_save(self, model_instance, add):

2610 if self.auto_now or (self.auto_now_add and add):

2611 value = datetime.datetime.now().time()

2612 setattr(model_instance, self.attname, value)

2613 return value

2614 else:

2615 return super().pre_save(model_instance, add)

2616

2617 def get_prep_value(self, value):

2618 value = super().get_prep_value(value)

2619 return self.to_python(value)

2620

2621 def get_db_prep_value(self, value, connection, prepared=False):

2622 # Casts times into the format expected by the backend

2623 if not prepared:

2624 value = self.get_prep_value(value)

2625 return connection.ops.adapt_timefield_value(value)

2626

2627 def value_to_string(self, obj):

2628 val = self.value_from_object(obj)

2629 return "" if val is None else val.isoformat()

2630

2631 def formfield(self, **kwargs):

2632 return super().formfield(

2633 **{

2634 "form_class": forms.TimeField,

2635 **kwargs,

2636 }

2637 )

2638

2639

2640class URLField(CharField):

2641 default_validators = [validators.URLValidator()]

2642 description = _("URL")

2643

2644 def __init__(self, verbose_name=None, name=None, **kwargs):

2645 kwargs.setdefault("max_length", 200)

2646 super().__init__(verbose_name, name, **kwargs)

2647

2648 def deconstruct(self):

2649 name, path, args, kwargs = super().deconstruct()

2650 if kwargs.get("max_length") == 200:

2651 del kwargs["max_length"]

2652 return name, path, args, kwargs

2653

2654 def formfield(self, **kwargs):

2655 # As with CharField, this will cause URL validation to be performed

2656 # twice.

2657 return super().formfield(

2658 **{

2659 "form_class": forms.URLField,

2660 **kwargs,

2661 }

2662 )

2663

2664

2665class BinaryField(Field):

2666 description = _("Raw binary data")

2667 empty_values = [None, b""]

2668

2669 def __init__(self, *args, **kwargs):

2670 kwargs.setdefault("editable", False)

2671 super().__init__(*args, **kwargs)

2672 if self.max_length is not None:

2673 self.validators.append(validators.MaxLengthValidator(self.max_length))

2674

2675 def check(self, **kwargs):

2676 return [*super().check(**kwargs), *self._check_str_default_value()]

2677

2678 def _check_str_default_value(self):

2679 if self.has_default() and isinstance(self.default, str):

2680 return [

2681 checks.Error(

2682 "BinaryField's default cannot be a string. Use bytes "

2683 "content instead.",

2684 obj=self,

2685 id="fields.E170",

2686 )

2687 ]

2688 return []

2689

2690 def deconstruct(self):

2691 name, path, args, kwargs = super().deconstruct()

2692 if self.editable:

2693 kwargs["editable"] = True

2694 else:

2695 del kwargs["editable"]

2696 return name, path, args, kwargs

2697

2698 def get_internal_type(self):

2699 return "BinaryField"

2700

2701 def get_placeholder(self, value, compiler, connection):

2702 return connection.ops.binary_placeholder_sql(value)

2703

2704 def get_default(self):

2705 if self.has_default() and not callable(self.default):

2706 return self.default

2707 default = super().get_default()

2708 if default == "":

2709 return b""

2710 return default

2711

2712 def get_db_prep_value(self, value, connection, prepared=False):

2713 value = super().get_db_prep_value(value, connection, prepared)

2714 if value is not None:

2715 return connection.Database.Binary(value)

2716 return value

2717

2718 def value_to_string(self, obj):

2719 """Binary data is serialized as base64"""

2720 return b64encode(self.value_from_object(obj)).decode("ascii")

2721

2722 def to_python(self, value):

2723 # If it's a string, it should be base64-encoded data

2724 if isinstance(value, str):

2725 return memoryview(b64decode(value.encode("ascii")))

2726 return value

2727

2728

2729class UUIDField(Field):

2730 default_error_messages = {

2731 "invalid": _("“%(value)s” is not a valid UUID."),

2732 }

2733 description = _("Universally unique identifier")

2734 empty_strings_allowed = False

2735

2736 def __init__(self, verbose_name=None, **kwargs):

2737 kwargs["max_length"] = 32

2738 super().__init__(verbose_name, **kwargs)

2739

2740 def deconstruct(self):

2741 name, path, args, kwargs = super().deconstruct()

2742 del kwargs["max_length"]

2743 return name, path, args, kwargs

2744

2745 def get_internal_type(self):

2746 return "UUIDField"

2747

2748 def get_prep_value(self, value):

2749 value = super().get_prep_value(value)

2750 return self.to_python(value)

2751

2752 def get_db_prep_value(self, value, connection, prepared=False):

2753 if value is None:

2754 return None

2755 if not isinstance(value, uuid.UUID):

2756 value = self.to_python(value)

2757

2758 if connection.features.has_native_uuid_field:

2759 return value

2760 return value.hex

2761

2762 def to_python(self, value):

2763 if value is not None and not isinstance(value, uuid.UUID):

2764 input_form = "int" if isinstance(value, int) else "hex"

2765 try:

2766 return uuid.UUID(**{input_form: value})

2767 except (AttributeError, ValueError):

2768 raise exceptions.ValidationError(

2769 self.error_messages["invalid"],

2770 code="invalid",

2771 params={"value": value},

2772 )

2773 return value

2774

2775 def formfield(self, **kwargs):

2776 return super().formfield(

2777 **{

2778 "form_class": forms.UUIDField,

2779 **kwargs,

2780 }

2781 )

2782

2783

2784class AutoFieldMixin:

2785 db_returning = True

2786

2787 def __init__(self, *args, **kwargs):

2788 kwargs["blank"] = True

2789 super().__init__(*args, **kwargs)

2790

2791 def check(self, **kwargs):

2792 return [

2793 *super().check(**kwargs),

2794 *self._check_primary_key(),

2795 ]

2796

2797 def _check_primary_key(self):

2798 if not self.primary_key:

2799 return [

2800 checks.Error(

2801 "AutoFields must set primary_key=True.",

2802 obj=self,

2803 id="fields.E100",

2804 ),

2805 ]

2806 else:

2807 return []

2808

2809 def deconstruct(self):

2810 name, path, args, kwargs = super().deconstruct()

2811 del kwargs["blank"]

2812 kwargs["primary_key"] = True

2813 return name, path, args, kwargs

2814

2815 def validate(self, value, model_instance):

2816 pass

2817

2818 def get_db_prep_value(self, value, connection, prepared=False):

2819 if not prepared:

2820 value = self.get_prep_value(value)

2821 value = connection.ops.validate_autopk_value(value)

2822 return value

2823

2824 def contribute_to_class(self, cls, name, **kwargs):

2825 if cls._meta.auto_field:

2826 raise ValueError(

2827 "Model %s can't have more than one auto-generated field."

2828 % cls._meta.label

2829 )

2830 super().contribute_to_class(cls, name, **kwargs)

2831 cls._meta.auto_field = self

2832

2833 def formfield(self, **kwargs):

2834 return None

2835

2836

2837class AutoFieldMeta(type):

2838 """

2839 Metaclass to maintain backward inheritance compatibility for AutoField.

2840

2841 It is intended that AutoFieldMixin become public API when it is possible to

2842 create a non-integer automatically-generated field using column defaults

2843 stored in the database.

2844

2845 In many areas Django also relies on using isinstance() to check for an

2846 automatically-generated field as a subclass of AutoField. A new flag needs

2847 to be implemented on Field to be used instead.

2848

2849 When these issues have been addressed, this metaclass could be used to

2850 deprecate inheritance from AutoField and use of isinstance() with AutoField

2851 for detecting automatically-generated fields.

2852 """

2853

2854 @property

2855 def _subclasses(self):

2856 return (BigAutoField, SmallAutoField)

2857

2858 def __instancecheck__(self, instance):

2859 return isinstance(instance, self._subclasses) or super().__instancecheck__(

2860 instance

2861 )

2862

2863 def __subclasscheck__(self, subclass):

2864 return issubclass(subclass, self._subclasses) or super().__subclasscheck__(

2865 subclass

2866 )

2867

2868

2869class AutoField(AutoFieldMixin, IntegerField, metaclass=AutoFieldMeta):

2870 def get_internal_type(self):

2871 return "AutoField"

2872

2873 def rel_db_type(self, connection):

2874 return IntegerField().db_type(connection=connection)

2875

2876

2877class BigAutoField(AutoFieldMixin, BigIntegerField):

2878 def get_internal_type(self):

2879 return "BigAutoField"

2880

2881 def rel_db_type(self, connection):

2882 return BigIntegerField().db_type(connection=connection)

2883

2884

2885class SmallAutoField(AutoFieldMixin, SmallIntegerField):

2886 def get_internal_type(self):

2887 return "SmallAutoField"

2888

2889 def rel_db_type(self, connection):

2890 return SmallIntegerField().db_type(connection=connection)

Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.10/site-packages/django/db/models/fields/init.py: 30%

1363 statements