django.db.models.fields.Field

class documentation

Base class for all field types

Class Method	`_choices_is_value`	Undocumented
Method	`__copy__`	Undocumented
Method	`__deepcopy__`	Undocumented
Method	`__eq__`	Undocumented
Method	`__hash__`	Undocumented
Method	`__init__`	Undocumented
Method	`__lt__`	Undocumented
Method	`__reduce__`	Pickling should return the model._meta.fields instance of the field, not a new copy of that field. So, use the app registry to load the model and then the field back.
Method	`__repr__`	Display the module, class, and name of the field.
Method	`__str__`	Return "app_label.model_label.field_name" for fields attached to models.
Method	`_check_backend_specific_checks`	Undocumented
Method	`_check_choices`	Undocumented
Method	`_check_db_index`	Undocumented
Method	`_check_deprecation_details`	Undocumented
Method	`_check_field_name`	Check if field name is valid, i.e. 1) does not end with an underscore, 2) does not contain "__" and 3) is not "pk".
Method	`_check_null_allowed_for_primary_keys`	Undocumented
Method	`_check_validators`	Undocumented
Method	`_description`	Undocumented
Method	`_get_flatchoices`	Flattened version of choices tuple.
Method	`cast_db_type`	Return the data type to use in the Cast() function.
Method	`check`	Undocumented
Method	`clean`	Convert the value's type and run validation. Validation errors from to_python() and validate() are propagated. Return the correct value if no error is raised.
Method	`clone`	Uses deconstruct() to clone a new copy of this Field. Will not preserve any class attachments/attribute names.
Method	`contribute_to_class`	Register the field with the model class it belongs to.
Method	`db_check`	Return the database column check constraint for this field, for the provided connection. Works the same way as db_type() for the case that get_internal_type() does not map to a preexisting model field.
Method	`db_parameters`	Extension of db_type(), providing a range of different return values (type, checks). This will look at db_type(), allowing custom model fields to override it.
Method	`db_type`	Return the database column data type for this field, for the provided connection.
Method	`db_type_parameters`	Undocumented
Method	`db_type_suffix`	Undocumented
Method	`deconstruct`	Return enough information to recreate the field as a 4-tuple:
Method	`formfield`	Return a django.forms.Field instance for this field.
Method	`get_attname`	Undocumented
Method	`get_attname_column`	Undocumented
Method	`get_choices`	Return choices with a default blank choices included, for use as <select> choices for this field.
Method	`get_col`	Undocumented
Method	`get_db_converters`	Undocumented
Method	`get_db_prep_save`	Return field's value prepared for saving into a database.
Method	`get_db_prep_value`	Return field's value prepared for interacting with the database backend.
Method	`get_default`	Return the default value for this field.
Method	`get_filter_kwargs_for_object`	Return a dict that when passed as kwargs to self.model.filter(), would yield all instances having the same value for this field as obj has.
Method	`get_internal_type`	Undocumented
Method	`get_pk_value_on_save`	No summary
Method	`get_prep_value`	Perform preliminary non-db specific value checks and conversions.
Method	`has_default`	Return a boolean of whether this field has a default value.
Method	`pre_save`	Return field's value just before saving.
Method	`rel_db_type`	Return the data type that a related field pointing to this field should use. For example, this method is called by ForeignKey and OneToOneField to determine its data type.
Method	`run_validators`	Undocumented
Method	`save_form_data`	Undocumented
Method	`select_format`	Custom format for select clauses. For example, GIS columns need to be selected as AsText(table.col) on MySQL as the table.col data can't be used by Django.
Method	`set_attributes_from_name`	Undocumented
Method	`to_python`	Convert the input value into the expected Python data type, raising django.core.exceptions.ValidationError if the data can't be converted. Return the converted value. Subclasses should override this.
Method	`validate`	Validate value and raise ValidationError if necessary. Subclasses should override this to provide validation logic.
Method	`value_from_object`	Return the value of this field in the given model instance.
Method	`value_to_string`	Return a string value of this field from the passed obj. This is used by the serialization framework.
Class Variable	`auto_creation_counter`	Undocumented
Class Variable	`default_error_messages`	Undocumented
Class Variable	`default_validators`	Undocumented
Class Variable	`description`	Undocumented
Class Variable	`empty_strings_allowed`	Undocumented
Class Variable	`empty_values`	Undocumented
Class Variable	`flatchoices`	Undocumented
Class Variable	`hidden`	Undocumented
Class Variable	`many_to_many`	Undocumented
Class Variable	`many_to_one`	Undocumented
Class Variable	`one_to_many`	Undocumented
Class Variable	`one_to_one`	Undocumented
Class Variable	`related_model`	Undocumented
Class Variable	`system_check_deprecated_details`	Undocumented
Class Variable	`system_check_removed_details`	Undocumented
Instance Variable	`_db_tablespace`	Undocumented
Instance Variable	`_error_messages`	Undocumented
Instance Variable	`_unique`	Undocumented
Instance Variable	`_validators`	Undocumented
Instance Variable	`_verbose_name`	Undocumented
Instance Variable	`attname`	Undocumented
Instance Variable	`auto_created`	Undocumented
Instance Variable	`blank`	Undocumented
Instance Variable	`choices`	Undocumented
Instance Variable	`column`	Undocumented
Instance Variable	`concrete`	Undocumented
Instance Variable	`creation_counter`	Undocumented
Instance Variable	`db_column`	Undocumented
Instance Variable	`db_index`	Undocumented
Instance Variable	`default`	Undocumented
Instance Variable	`editable`	Undocumented
Instance Variable	`error_messages`	Undocumented
Instance Variable	`help_text`	Undocumented
Instance Variable	`is_relation`	Undocumented
Instance Variable	`max_length`	Undocumented
Instance Variable	`model`	Undocumented
Instance Variable	`name`	Undocumented
Instance Variable	`null`	Undocumented
Instance Variable	`primary_key`	Undocumented
Instance Variable	`remote_field`	Undocumented
Instance Variable	`serialize`	Undocumented
Instance Variable	`unique_for_date`	Undocumented
Instance Variable	`unique_for_month`	Undocumented
Instance Variable	`unique_for_year`	Undocumented
Instance Variable	`verbose_name`	Undocumented
Property	`_get_default`	Undocumented
Property	`cached_col`	Undocumented
Property	`db_returning`	Private API intended only to be used by Django itself. Currently only the PostgreSQL backend supports returning multiple fields on a model.
Property	`db_tablespace`	Undocumented
Property	`unique`	Undocumented
Property	`validators`	Some validators can't be created at field initialization time. This method provides a way to delay their creation until required.

Inherited from RegisterLookupMixin:

Class Method	`get_lookups`	Undocumented
Class Method	`register_lookup`	Undocumented
Static Method	`merge_dicts`	Merge dicts in reverse to preference the order of the original list. e.g., merge_dicts([a, b]) will preference the keys in 'a' over those in 'b'.
Class Method	`_clear_cached_lookups`	Undocumented
Class Method	`_get_lookup`	Undocumented
Class Method	`_unregister_lookup`	Remove given lookup from cls lookups. For use in tests only as it's not thread-safe.
Method	`get_lookup`	Undocumented
Method	`get_transform`	Undocumented

@classmethod
def _choices_is_value(cls, value):

overridden in django.contrib.postgres.fields.ranges.RangeField

Undocumented

def __copy__(self):

Undocumented

def __deepcopy__(self, memodict):

Undocumented

def __eq__(self, other):

Undocumented

def __hash__(self):

Undocumented

def __init__(self, verbose_name=None, name=None, primary_key=False, max_length=None, unique=False, blank=False, null=False, db_index=False, rel=None, default=NOT_PROVIDED, editable=True, serialize=True, unique_for_date=None, unique_for_month=None, unique_for_year=None, choices=None, help_text='', db_column=None, db_tablespace=None, auto_created=False, validators=(), error_messages=None):

overridden in django.contrib.gis.db.models.sql.AreaField, django.contrib.gis.db.models.sql.DistanceField, django.contrib.postgres.fields.ranges.RangeField, django.db.models.fields.BinaryField, django.db.models.fields.CharField, django.db.models.fields.DateField, django.db.models.fields.DecimalField, django.db.models.fields.FilePathField, django.db.models.fields.files.FileField, django.db.models.fields.GenericIPAddressField, django.db.models.fields.IPAddressField, django.db.models.fields.json.JSONField, django.db.models.fields.NullBooleanField, django.db.models.fields.proxy.OrderWrt, django.db.models.fields.related.RelatedField, django.db.models.fields.TextField, django.db.models.fields.TimeField, django.db.models.fields.UUIDField

Undocumented

def __lt__(self, other):

Undocumented

def __reduce__(self):

Pickling should return the model._meta.fields instance of the field, not a new copy of that field. So, use the app registry to load the model and then the field back.

def __repr__(self):

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

def __str__(self):

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

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

Undocumented

def _check_choices(self):

Undocumented

def _check_db_index(self):

Undocumented

def _check_deprecation_details(self):

Undocumented

def _check_field_name(self):

Check if field name is valid, i.e. 1) does not end with an underscore, 2) does not contain "__" and 3) is not "pk".

def _check_null_allowed_for_primary_keys(self):

Undocumented

def _check_validators(self):

Undocumented

def _description(self):

Undocumented

def _get_flatchoices(self):

Flattened version of choices tuple.

def cast_db_type(self, connection):

overridden in django.db.models.fields.CharField

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

def check(self, **kwargs):

overridden in django.db.models.fields.BinaryField, django.db.models.fields.CharField, django.db.models.fields.DecimalField, django.db.models.fields.FilePathField, django.db.models.fields.files.FileField, django.db.models.fields.GenericIPAddressField, django.db.models.fields.IntegerField, django.db.models.fields.json.JSONField, django.db.models.fields.related.RelatedField, django.db.models.fields.TextField

Undocumented

def clean(self, value, model_instance):

Convert the value's type and run validation. Validation errors from to_python() and validate() are propagated. Return the correct value if no error is raised.

def clone(self):

Uses deconstruct() to clone a new copy of this Field. Will not preserve any class attachments/attribute names.

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

overridden in django.db.models.fields.DateField, django.db.models.fields.files.FileField, django.db.models.fields.related.RelatedField

If private_only is True, create a separate instance of this field for every subclass of cls, even if cls is not an abstract model.

def db_check(self, connection):

overridden in django.db.models.fields.related.ForeignKey, django.db.models.fields.related.ManyToManyField

Return the database column check constraint for this field, for the provided connection. Works the same way as db_type() for the case that get_internal_type() does not map to a preexisting model field.

def db_parameters(self, connection):

overridden in django.db.models.fields.related.ForeignKey, django.db.models.fields.related.ManyToManyField

Extension of db_type(), providing a range of different return values (type, checks). This will look at db_type(), allowing custom model fields to override it.

def db_type(self, connection):

overridden in django.contrib.postgres.fields.ranges.BigIntegerRangeField, django.contrib.postgres.fields.ranges.DateRangeField, django.contrib.postgres.fields.ranges.DateTimeRangeField, django.contrib.postgres.fields.ranges.DecimalRangeField, django.contrib.postgres.fields.ranges.IntegerRangeField, django.db.models.fields.related.RelatedField

Return the database column data type for this field, for the provided connection.

def db_type_parameters(self, connection):

Undocumented

def db_type_suffix(self, connection):

Undocumented

def deconstruct(self):

overridden in django.db.models.fields.BinaryField, django.db.models.fields.CharField, django.db.models.fields.DateField, django.db.models.fields.DecimalField, django.db.models.fields.FilePathField, django.db.models.fields.files.FileField, django.db.models.fields.GenericIPAddressField, django.db.models.fields.IPAddressField, django.db.models.fields.json.JSONField, django.db.models.fields.NullBooleanField, django.db.models.fields.related.RelatedField, django.db.models.fields.TextField, django.db.models.fields.TimeField, django.db.models.fields.UUIDField

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

The name of the field on the model, if contribute_to_class() has been run.

The import path of the field, including the class, e.g. django.db.models.IntegerField. This should be the most portable version, so less specific may be better.

A list of positional arguments.

A dict of keyword arguments.

Note that the positional or keyword arguments must contain values of the following types (including inner values of collection types):

None, bool, str, int, float, complex, set, frozenset, list, tuple, dict

UUID

datetime.datetime (naive), datetime.date

top-level classes, top-level functions - will be referenced by their full import path

Storage instances - these have their own deconstruct() method

This is because the values here must be serialized into a text format (possibly new Python code, possibly JSON) and these are the only types with encoding handlers defined.

There's no need to return the exact way the field was instantiated this time, just ensure that the resulting field is the same - prefer keyword arguments over positional ones, and omit parameters with their default values.

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

overridden in django.contrib.postgres.fields.ranges.RangeField, django.db.models.fields.BooleanField, django.db.models.fields.CharField, django.db.models.fields.DateField, django.db.models.fields.DecimalField, django.db.models.fields.DurationField, django.db.models.fields.FilePathField, django.db.models.fields.files.FileField, django.db.models.fields.FloatField, django.db.models.fields.GenericIPAddressField, django.db.models.fields.IntegerField, django.db.models.fields.json.JSONField, django.db.models.fields.related.RelatedField, django.db.models.fields.TextField, django.db.models.fields.TimeField, django.db.models.fields.UUIDField

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

def get_attname(self):

overridden in django.db.models.fields.related.ForeignKey

Undocumented

def get_attname_column(self):

overridden in django.db.models.fields.related.ForeignObject

Undocumented

def get_choices(self, include_blank=True, blank_choice=BLANK_CHOICE_DASH, limit_choices_to=None, ordering=()):

Return choices with a default blank choices included, for use as <select> choices for this field.

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

overridden in django.db.models.fields.related.ForeignKey

Undocumented

def get_db_converters(self, connection):

overridden in django.db.models.fields.DurationField, django.db.models.fields.related.ForeignKey

Undocumented

def get_db_prep_save(self, value, connection):

overridden in django.db.models.fields.DecimalField, django.db.models.fields.related.ForeignKey

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

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

overridden in django.contrib.gis.db.models.sql.AreaField, django.contrib.gis.db.models.sql.DistanceField, django.db.models.fields.BinaryField, django.db.models.fields.DateField, django.db.models.fields.DurationField, django.db.models.fields.GenericIPAddressField, django.db.models.fields.related.ForeignKey, django.db.models.fields.TimeField, django.db.models.fields.UUIDField

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

Used by the default implementations of get_db_prep_save().

def get_default(self):

overridden in django.db.models.fields.BinaryField, django.db.models.fields.related.ForeignKey

Return the default value for this field.

def get_filter_kwargs_for_object(self, obj):

Return a dict that when passed as kwargs to self.model.filter(), would yield all instances having the same value for this field as obj has.

def get_internal_type(self):

overridden in django.db.models.fields.BinaryField, django.db.models.fields.BooleanField, django.db.models.fields.CharField, django.db.models.fields.DateField, django.db.models.fields.DecimalField, django.db.models.fields.DurationField, django.db.models.fields.FilePathField, django.db.models.fields.files.FileField, django.db.models.fields.FloatField, django.db.models.fields.GenericIPAddressField, django.db.models.fields.IntegerField, django.db.models.fields.IPAddressField, django.db.models.fields.json.JSONField, django.db.models.fields.TextField, django.db.models.fields.TimeField, django.db.models.fields.UUIDField

Undocumented

def get_pk_value_on_save(self, instance):

Hook to generate new PK values on save. This method is called when saving instances with no primary key value set. If this method returns something else than None, then the returned value is used when saving the new instance.

def get_prep_value(self, value):

overridden in django.contrib.postgres.fields.ranges.RangeField, django.db.models.fields.BooleanField, django.db.models.fields.CharField, django.db.models.fields.DateField, django.db.models.fields.DecimalField, django.db.models.fields.FilePathField, django.db.models.fields.files.FileField, django.db.models.fields.FloatField, django.db.models.fields.GenericIPAddressField, django.db.models.fields.IntegerField, django.db.models.fields.IPAddressField, django.db.models.fields.json.JSONField, django.db.models.fields.related.ForeignKey, django.db.models.fields.TextField, django.db.models.fields.TimeField, django.db.models.fields.UUIDField

Perform preliminary non-db specific value checks and conversions.

def has_default(self):

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

def pre_save(self, model_instance, add):

overridden in django.db.models.fields.DateField, django.db.models.fields.files.FileField, django.db.models.fields.TimeField

Return field's value just before saving.

def rel_db_type(self, connection):

overridden in django.db.models.fields.AutoField, django.db.models.fields.BigAutoField, django.db.models.fields.SmallAutoField

Return the data type that a related field pointing to this field should use. For example, this method is called by ForeignKey and OneToOneField to determine its data type.

def run_validators(self, value):

Undocumented

def save_form_data(self, instance, data):

overridden in django.db.models.fields.files.FileField, django.db.models.fields.related.ManyToManyField, django.db.models.fields.related.OneToOneField

Undocumented

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

Custom format for select clauses. For example, GIS columns need to be selected as AsText(table.col) on MySQL as the table.col data can't be used by Django.

def set_attributes_from_name(self, name):

overridden in django.contrib.postgres.fields.ranges.RangeField

Undocumented

def to_python(self, value):

overridden in django.contrib.postgres.fields.ranges.RangeField, django.db.models.fields.BinaryField, django.db.models.fields.BooleanField, django.db.models.fields.CharField, django.db.models.fields.DateField, django.db.models.fields.DecimalField, django.db.models.fields.DurationField, django.db.models.fields.FloatField, django.db.models.fields.GenericIPAddressField, django.db.models.fields.IntegerField, django.db.models.fields.related.ForeignKey, django.db.models.fields.TextField, django.db.models.fields.TimeField, django.db.models.fields.UUIDField

Convert the input value into the expected Python data type, raising django.core.exceptions.ValidationError if the data can't be converted. Return the converted value. Subclasses should override this.

def validate(self, value, model_instance):

overridden in django.db.models.fields.json.JSONField, django.db.models.fields.related.ForeignKey

Validate value and raise ValidationError if necessary. Subclasses should override this to provide validation logic.

def value_from_object(self, obj):

overridden in django.db.models.fields.related.ManyToManyField

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

def value_to_string(self, obj):

overridden in django.contrib.postgres.fields.ranges.RangeField, django.db.models.fields.BinaryField, django.db.models.fields.DateField, django.db.models.fields.DurationField, django.db.models.fields.json.JSONField, django.db.models.fields.TimeField

Return a string value of this field from the passed obj. This is used by the serialization framework.

auto_creation_counter: int =

Undocumented

default_error_messages =

overridden in django.db.models.fields.BooleanField, django.db.models.fields.DateField, django.db.models.fields.DecimalField, django.db.models.fields.DurationField, django.db.models.fields.FloatField, django.db.models.fields.GenericIPAddressField, django.db.models.fields.IntegerField, django.db.models.fields.json.JSONField, django.db.models.fields.related.ForeignKey, django.db.models.fields.TimeField, django.db.models.fields.UUIDField

Undocumented

default_validators: list =

overridden in django.db.models.fields.CommaSeparatedIntegerField, django.db.models.fields.EmailField, django.db.models.fields.GenericIPAddressField, django.db.models.fields.SlugField, django.db.models.fields.URLField

Undocumented

description =

overridden in django.db.models.fields.BinaryField, django.db.models.fields.BooleanField, django.db.models.fields.CharField, django.db.models.fields.DateField, django.db.models.fields.DecimalField, django.db.models.fields.DurationField, django.db.models.fields.FilePathField, django.db.models.fields.files.FileField, django.db.models.fields.FloatField, django.db.models.fields.GenericIPAddressField, django.db.models.fields.IntegerField, django.db.models.fields.IPAddressField, django.db.models.fields.json.JSONField, django.db.models.fields.related.ForeignKey, django.db.models.fields.related.ManyToManyField, django.db.models.fields.TextField, django.db.models.fields.TimeField, django.db.models.fields.UUIDField

Undocumented

empty_strings_allowed: bool =

overridden in django.contrib.postgres.fields.ranges.RangeField, django.db.models.fields.BooleanField, django.db.models.fields.DateField, django.db.models.fields.DecimalField, django.db.models.fields.DurationField, django.db.models.fields.FloatField, django.db.models.fields.GenericIPAddressField, django.db.models.fields.IntegerField, django.db.models.fields.IPAddressField, django.db.models.fields.json.JSONField, django.db.models.fields.related.ForeignKey, django.db.models.fields.TimeField, django.db.models.fields.UUIDField

Undocumented

empty_values =

overridden in django.db.models.fields.BinaryField

Undocumented

flatchoices =

Undocumented

hidden: bool =

Undocumented

many_to_many =

overridden in django.db.models.fields.related.RelatedField

Undocumented

many_to_one =

overridden in django.db.models.fields.related.RelatedField

Undocumented

one_to_many =

overridden in django.db.models.fields.related.RelatedField

Undocumented

one_to_one =

overridden in django.db.models.fields.related.RelatedField

Undocumented

related_model =

overridden in django.db.models.fields.related.RelatedField

Undocumented

system_check_deprecated_details =

Undocumented

system_check_removed_details =

overridden in django.db.models.fields.CommaSeparatedIntegerField, django.db.models.fields.IPAddressField, django.db.models.fields.NullBooleanField

Undocumented

_db_tablespace =

Undocumented

_error_messages =

Undocumented

_unique =

Undocumented

_validators =

Undocumented

_verbose_name =

Undocumented

attname =

Undocumented

auto_created =

Undocumented

blank =

Undocumented

choices =

Undocumented

column =

Undocumented

concrete =

Undocumented

creation_counter =

Undocumented

db_column =

Undocumented

db_index =

Undocumented

default =

Undocumented

editable =

Undocumented

error_messages =

Undocumented

help_text =

Undocumented

is_relation =

Undocumented

max_length =

Undocumented

model =

overridden in django.contrib.postgres.fields.ranges.RangeField

Undocumented

name =

overridden in django.db.models.fields.related.RelatedField

Undocumented

null =

Undocumented

primary_key =

Undocumented

remote_field =

Undocumented

serialize =

Undocumented

unique_for_date =

Undocumented

unique_for_month =

Undocumented

unique_for_year =

Undocumented

verbose_name =

overridden in django.db.models.fields.related.RelatedField

Undocumented

@cached_property
_get_default =

Undocumented

@cached_property
cached_col =

Undocumented

@property
db_returning =

Private API intended only to be used by Django itself. Currently only the PostgreSQL backend supports returning multiple fields on a model.

@property
db_tablespace =

Undocumented

@property
unique =

Undocumented

@cached_property
validators =

overridden in django.db.models.fields.DecimalField, django.db.models.fields.IntegerField

Some validators can't be created at field initialization time. This method provides a way to delay their creation until required.