class Field
[source]
Field
is an abstract class that represents a database table column. Django uses fields to create the database table (db_type()
), to map Python types to database (get_prep_value()
) and vice-versa (from_db_value()
).
A field is thus a fundamental piece in different Django APIs, notably, models
and querysets
.
In models, a field is instantiated as a class attribute and represents a particular table column, see Models. It has attributes such as null
and unique
, and methods that Django uses to map the field value to database-specific values.
A Field
is a subclass of RegisterLookupMixin
and thus both Transform
and Lookup
can be registered on it to be used in QuerySet
s (e.g. field_name__exact="foo"
). All built-in lookups are registered by default.
All of Django’s built-in fields, such as CharField
, are particular implementations of Field
. If you need a custom field, you can either subclass any of the built-in fields or write a Field
from scratch. In either case, see Writing custom model fields.
-
description
-
A verbose description of the field, e.g. for the
django.contrib.admindocs
application.The description can be of the form:
description = _("String (up to %(max_length)s)")
where the arguments are interpolated from the field’s
__dict__
.
To map a Field
to a database-specific type, Django exposes several methods:
-
get_internal_type()
[source] -
Returns a string naming this field for backend specific purposes. By default, it returns the class name.
See Emulating built-in field types for usage in custom fields.
-
db_type(connection)
[source] -
Returns the database column data type for the
Field
, taking into account theconnection
.See Custom database types for usage in custom fields.
-
rel_db_type(connection)
[source] -
New in Django 1.10.
Returns the database column data type for fields such as
ForeignKey
andOneToOneField
that point to theField
, taking into account theconnection
.See Custom database types for usage in custom fields.
There are three main situations where Django needs to interact with the database backend and fields:
- when it queries the database (Python value -> database backend value)
- when it loads data from the database (database backend value -> Python value)
- when it saves to the database (Python value -> database backend value)
When querying, get_db_prep_value()
and get_prep_value()
are used:
-
get_prep_value(value)
[source] -
value
is the current value of the model’s attribute, and the method should return data in a format that has been prepared for use as a parameter in a query.See Converting Python objects to query values for usage.
-
get_db_prep_value(value, connection, prepared=False)
[source] -
Converts
value
to a backend-specific value. By default it returnsvalue
ifprepared=True
andget_prep_value()
if isFalse
.See Converting query values to database values for usage.
When loading data, from_db_value()
is used:
-
from_db_value(value, expression, connection, context)
-
Converts a value as returned by the database to a Python object. It is the reverse of
get_prep_value()
.This method is not used for most built-in fields as the database backend already returns the correct Python type, or the backend itself does the conversion.
See Converting values to Python objects for usage.
Note
For performance reasons,
from_db_value
is not implemented as a no-op on fields which do not require it (all Django fields). Consequently you may not callsuper
in your definition.
When saving, pre_save()
and get_db_prep_save()
are used:
-
get_db_prep_save(value, connection)
[source] -
Same as the
get_db_prep_value()
, but called when the field value must be saved to the database. By default returnsget_db_prep_value()
.
-
pre_save(model_instance, add)
[source] -
Method called prior to
get_db_prep_save()
to prepare the value before being saved (e.g. forDateField.auto_now
).model_instance
is the instance this field belongs to andadd
is whether the instance is being saved to the database for the first time.It should return the value of the appropriate attribute from
model_instance
for this field. The attribute name is inself.attname
(this is set up byField
).See Preprocessing values before saving for usage.
Fields often receive their values as a different type, either from serialization or from forms.
-
to_python(value)
[source] -
Converts the value into the correct Python object. It acts as the reverse of
value_to_string()
, and is also called inclean()
.See Converting values to Python objects for usage.
Besides saving to the database, the field also needs to know how to serialize its value:
-
value_to_string(obj)
[source] -
Converts
obj
to a string. Used to serialize the value of the field.See Converting field data for serialization for usage.
When using model forms
, the Field
needs to know which form field it should be represented by:
-
formfield(form_class=None, choices_form_class=None, **kwargs)
[source] -
Returns the default
django.forms.Field
of this field forModelForm
.By default, if both
form_class
andchoices_form_class
areNone
, it usesCharField
. If the field haschoices
andchoices_form_class
isn’t specified, it usesTypedChoiceField
.See Specifying the form field for a model field for usage.
-
deconstruct()
[source] -
Returns a 4-tuple with enough information to recreate the field:
- The name of the field on the model.
- The import path of the field (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.
This method must be added to fields prior to 1.7 to migrate its data using Migrations.
Every Field
instance contains several attributes that allow introspecting its behavior. Use these attributes instead of isinstance
checks when you need to write code that depends on a field’s functionality. These attributes can be used together with the Model._meta API to narrow down a search for specific field types. Custom model fields should implement these flags.
Please login to continue.