The model reference documentation explains how to use\nDjango’s standard field classes – CharField,\nDateField, etc. For many purposes, those classes are\nall you’ll need. Sometimes, though, the Django version won’t meet your precise\nrequirements, or you’ll want to use a field that is entirely different from\nthose shipped with Django.
Django’s built-in field types don’t cover every possible database column type –\nonly the common types, such as VARCHAR and INTEGER. For more obscure\ncolumn types, such as geographic polygons or even user-created types such as\nPostgreSQL custom types, you can define your own Django Field subclasses.
Alternatively, you may have a complex Python object that can somehow be\nserialized to fit into a standard database column type. This is another case\nwhere a Field subclass will help you use your object with your models.
Creating custom fields requires a bit of attention to detail. To make things\neasier to follow, we’ll use a consistent example throughout this document:\nwrapping a Python object representing the deal of cards in a hand of Bridge.\nDon’t worry, you don’t have to know how to play Bridge to follow this example.\nYou only need to know that 52 cards are dealt out equally to four players, who\nare traditionally called north, east, south and west. Our class looks\nsomething like this:
\nclass Hand(object):\n """A hand of cards (bridge style)"""\n\n def __init__(self, north, east, south, west):\n # Input parameters are lists of cards ('Ah', '9s', etc.)\n self.north = north\n self.east = east\n self.south = south\n self.west = west\n\n # ... (other possibly useful methods omitted) ...\nThis is just an ordinary Python class, with nothing Django-specific about it.\nWe’d like to be able to do things like this in our models (we assume the\nhand attribute on the model is an instance of Hand):
example = MyModel.objects.get(pk=1)\nprint(example.hand.north)\n\nnew_hand = Hand(north, east, south, west)\nexample.hand = new_hand\nexample.save()\nWe assign to and retrieve from the hand attribute in our model just like\nany other Python class. The trick is to tell Django how to handle saving and\nloading such an object.
In order to use the Hand class in our models, we do not have to change\nthis class at all. This is ideal, because it means you can easily write\nmodel support for existing classes where you cannot change the source code.
The simplest way to think of a model field is that it provides a way to take a\nnormal Python object – string, boolean, datetime, or something more\ncomplex like Hand – and convert it to and from a format that is useful\nwhen dealing with the database (and serialization, but, as we’ll see later,\nthat falls out fairly naturally once you have the database side under control).
Fields in a model must somehow be converted to fit into an existing database\ncolumn type. Different databases provide different sets of valid column types,\nbut the rule is still the same: those are the only types you have to work\nwith. Anything you want to store in the database must fit into one of\nthose types.
\nNormally, you’re either writing a Django field to match a particular database\ncolumn type, or there’s a fairly straightforward way to convert your data to,\nsay, a string.
\nFor our Hand example, we could convert the card data to a string of 104\ncharacters by concatenating all the cards together in a pre-determined order –\nsay, all the north cards first, then the east, south and west cards. So\nHand objects can be saved to text or character columns in the database.
All of Django’s fields (and when we say fields in this document, we always\nmean model fields and not form fields) are subclasses\nof django.db.models.Field. Most of the information that Django records\nabout a field is common to all fields – name, help text, uniqueness and so\nforth. Storing all that information is handled by Field. We’ll get into the\nprecise details of what Field can do later on; for now, suffice it to say\nthat everything descends from Field and then customizes key pieces of the\nclass behavior.
It’s important to realize that a Django field class is not what is stored in\nyour model attributes. The model attributes contain normal Python objects. The\nfield classes you define in a model are actually stored in the Meta class\nwhen the model class is created (the precise details of how this is done are\nunimportant here). This is because the field classes aren’t necessary when\nyou’re just creating and modifying attributes. Instead, they provide the\nmachinery for converting between the attribute value and what is stored in the\ndatabase or sent to the serializer.
Keep this in mind when creating your own custom fields. The Django Field\nsubclass you write provides the machinery for converting between your Python\ninstances and the database/serializer values in various ways (there are\ndifferences between storing a value and using a value for lookups, for\nexample). If this sounds a bit tricky, don’t worry – it will become clearer in\nthe examples below. Just remember that you will often end up creating two\nclasses when you want a custom field:
The first class is the Python object that your users will manipulate.\nThey will assign it to the model attribute, they will read from it for\ndisplaying purposes, things like that. This is the Hand class in our\nexample.
The second class is the Field subclass. This is the class that knows\nhow to convert your first class back and forth between its permanent\nstorage form and the Python form.
When planning your Field subclass, first give some\nthought to which existing Field class your new field\nis most similar to. Can you subclass an existing Django field and save yourself\nsome work? If not, you should subclass the Field\nclass, from which everything is descended.
Initializing your new field is a matter of separating out any arguments that are\nspecific to your case from the common arguments and passing the latter to the\n__init__() method of Field (or your parent\nclass).
In our example, we’ll call our field HandField. (It’s a good idea to call\nyour Field subclass <Something>Field, so it’s\neasily identifiable as a Field subclass.) It doesn’t\nbehave like any existing field, so we’ll subclass directly from\nField:
from django.db import models\n\nclass HandField(models.Field):\n\n description = "A hand of cards (bridge style)"\n\n def __init__(self, *args, **kwargs):\n kwargs['max_length'] = 104\n super(HandField, self).__init__(*args, **kwargs)\nOur HandField accepts most of the standard field options (see the list\nbelow), but we ensure it has a fixed length, since it only needs to hold 52\ncard values plus their suits; 104 characters in total.
The Field.__init__() method takes the following parameters:
name
rel: Used for related fields (like ForeignKey). For advanced\nuse only.
serialize: If False, the field will not be serialized when the model\nis passed to Django’s serializers. Defaults to\nTrue.
db_tablespace: Only for index creation, if the\nbackend supports tablespaces. You can usually\nignore this option.
auto_created: True if the field was\nautomatically created, as for the OneToOneField\nused by model inheritance. For advanced use only.
All of the options without an explanation in the above list have the same\nmeaning they do for normal Django fields. See the field documentation for examples and details.
\nThe counterpoint to writing your __init__() method is writing the\ndeconstruct() method. This method tells Django how to take an instance\nof your new field and reduce it to a serialized form - in particular, what\narguments to pass to __init__() to re-create it.
If you haven’t added any extra options on top of the field you inherited from,\nthen there’s no need to write a new deconstruct() method. If, however,\nyou’re changing the arguments passed in __init__() (like we are in\nHandField), you’ll need to supplement the values being passed.
The contract of deconstruct() is simple; it returns a tuple of four items:\nthe field’s attribute name, the full import path of the field class, the\npositional arguments (as a list), and the keyword arguments (as a dict). Note\nthis is different from the deconstruct() method for custom classes which returns a tuple of three things.
As a custom field author, you don’t need to care about the first two values;\nthe base Field class has all the code to work out the field’s attribute\nname and import path. You do, however, have to care about the positional\nand keyword arguments, as these are likely the things you are changing.
For example, in our HandField class we’re always forcibly setting\nmax_length in __init__(). The deconstruct() method on the base Field\nclass will see this and try to return it in the keyword arguments; thus,\nwe can drop it from the keyword arguments for readability:
from django.db import models\n\nclass HandField(models.Field):\n\n def __init__(self, *args, **kwargs):\n kwargs['max_length'] = 104\n super(HandField, self).__init__(*args, **kwargs)\n\n def deconstruct(self):\n name, path, args, kwargs = super(HandField, self).deconstruct()\n del kwargs["max_length"]\n return name, path, args, kwargs\nIf you add a new keyword argument, you need to write code to put its value\ninto kwargs yourself:
from django.db import models\n\nclass CommaSepField(models.Field):\n "Implements comma-separated storage of lists"\n\n def __init__(self, separator=",", *args, **kwargs):\n self.separator = separator\n super(CommaSepField, self).__init__(*args, **kwargs)\n\n def deconstruct(self):\n name, path, args, kwargs = super(CommaSepField, self).deconstruct()\n # Only include kwarg if it's not the default\n if self.separator != ",":\n kwargs['separator'] = self.separator\n return name, path, args, kwargs\nMore complex examples are beyond the scope of this document, but remember -\nfor any configuration of your Field instance, deconstruct() must return\narguments that you can pass to __init__ to reconstruct that state.
Pay extra attention if you set new default values for arguments in the\nField superclass; you want to make sure they’re always included, rather\nthan disappearing if they take on the old default value.
In addition, try to avoid returning values as positional arguments; where\npossible, return values as keyword arguments for maximum future compatibility.\nOf course, if you change the names of things more often than their position\nin the constructor’s argument list, you might prefer positional, but bear in\nmind that people will be reconstructing your field from the serialized version\nfor quite a while (possibly years), depending how long your migrations live for.
\nYou can see the results of deconstruction by looking in migrations that include\nthe field, and you can test deconstruction in unit tests by just deconstructing\nand reconstructing the field:
\nname, path, args, kwargs = my_field_instance.deconstruct()\nnew_instance = MyField(*args, **kwargs)\nself.assertEqual(my_field_instance.some_attribute, new_instance.some_attribute)\nYou can’t change the base class of a custom field because Django won’t detect\nthe change and make a migration for it. For example, if you start with:
\nclass CustomCharField(models.CharField):\n ...\nand then decide that you want to use TextField instead, you can’t change\nthe subclass like this:
class CustomCharField(models.TextField):\n ...\nInstead, you must create a new custom field class and update your models to\nreference it:
\nclass CustomCharField(models.CharField):\n ...\n\nclass CustomTextField(models.TextField):\n ...\nAs discussed in removing fields, you\nmust retain the original CustomCharField class as long as you have\nmigrations that reference it.
As always, you should document your field type, so users will know what it is.\nIn addition to providing a docstring for it, which is useful for developers,\nyou can also allow users of the admin app to see a short description of the\nfield type via the django.contrib.admindocs application. To do this simply provide\ndescriptive text in a description class attribute of your custom\nfield. In the above example, the description displayed by the admindocs\napplication for a HandField will be “A hand of cards (bridge style)”.
In the django.contrib.admindocs display, the field description is\ninterpolated with field.__dict__ which allows the description to\nincorporate arguments of the field. For example, the description for\nCharField is:
description = _("String (up to %(max_length)s)")\nOnce you’ve created your Field subclass, you might\nconsider overriding a few standard methods, depending on your field’s behavior.\nThe list of methods below is in approximately decreasing order of importance,\nso start from the top.
Say you’ve created a PostgreSQL custom type called mytype. You can\nsubclass Field and implement the db_type() method, like so:
from django.db import models\n\nclass MytypeField(models.Field):\n def db_type(self, connection):\n return 'mytype'\nOnce you have MytypeField, you can use it in any model, just like any other\nField type:
class Person(models.Model):\n name = models.CharField(max_length=80)\n something_else = MytypeField()\nIf you aim to build a database-agnostic application, you should account for\ndifferences in database column types. For example, the date/time column type\nin PostgreSQL is called timestamp, while the same column in MySQL is called\ndatetime. The simplest way to handle this in a db_type()\nmethod is to check the connection.settings_dict['ENGINE'] attribute.
For example:
\nclass MyDateField(models.Field):\n def db_type(self, connection):\n if connection.settings_dict['ENGINE'] == 'django.db.backends.mysql':\n return 'datetime'\n else:\n return 'timestamp'\nThe db_type() method is called by Django when the framework\nconstructs the CREATE TABLE statements for your application – that is,\nwhen you first create your tables. It is also called when constructing a\nWHERE clause that includes the model field – that is, when you retrieve data\nusing QuerySet methods like get(), filter(), and exclude() and have\nthe model field as an argument. It’s not called at any other time, so it can afford to\nexecute slightly complex code, such as the connection.settings_dict check in\nthe above example.
Some database column types accept parameters, such as CHAR(25), where the\nparameter 25 represents the maximum column length. In cases like these,\nit’s more flexible if the parameter is specified in the model rather than being\nhard-coded in the db_type() method. For example, it wouldn’t make much\nsense to have a CharMaxlength25Field, shown here:
# This is a silly example of hard-coded parameters.\nclass CharMaxlength25Field(models.Field):\n def db_type(self, connection):\n return 'char(25)'\n\n# In the model:\nclass MyModel(models.Model):\n # ...\n my_field = CharMaxlength25Field()\nThe better way of doing this would be to make the parameter specifiable at run\ntime – i.e., when the class is instantiated. To do that, just implement\nField.__init__(), like so:
# This is a much more flexible example.\nclass BetterCharField(models.Field):\n def __init__(self, max_length, *args, **kwargs):\n self.max_length = max_length\n super(BetterCharField, self).__init__(*args, **kwargs)\n\n def db_type(self, connection):\n return 'char(%s)' % self.max_length\n\n# In the model:\nclass MyModel(models.Model):\n # ...\n my_field = BetterCharField(25)\nFinally, if your column requires truly complex SQL setup, return None from\ndb_type(). This will cause Django’s SQL creation code to skip\nover this field. You are then responsible for creating the column in the right\ntable in some other way, of course, but this gives you a way to tell Django to\nget out of the way.
If your custom Field class deals with data structures that are more\ncomplex than strings, dates, integers, or floats, then you may need to override\nfrom_db_value() and to_python().
If present for the field subclass, from_db_value() will be called in all\ncircumstances when the data is loaded from the database, including in\naggregates and values() calls.
to_python() is called by deserialization and during the\nclean() method used from forms.
As a general rule, to_python() should deal gracefully with any of the\nfollowing arguments:
An instance of the correct type (e.g., Hand in our ongoing example).
A string
None (if the field allows null=True)
In our HandField class, we’re storing the data as a VARCHAR field in the\ndatabase, so we need to be able to process strings and None in the\nfrom_db_value(). In to_python(), we need to also handle Hand\ninstances:
import re\n\nfrom django.core.exceptions import ValidationError\nfrom django.db import models\nfrom django.utils.translation import ugettext_lazy as _\n\ndef parse_hand(hand_string):\n """Takes a string of cards and splits into a full hand."""\n p1 = re.compile('.{26}')\n p2 = re.compile('..')\n args = [p2.findall(x) for x in p1.findall(hand_string)]\n if len(args) != 4:\n raise ValidationError(_("Invalid input for a Hand instance"))\n return Hand(*args)\n\nclass HandField(models.Field):\n # ...\n\n def from_db_value(self, value, expression, connection, context):\n if value is None:\n return value\n return parse_hand(value)\n\n def to_python(self, value):\n if isinstance(value, Hand):\n return value\n\n if value is None:\n return value\n\n return parse_hand(value)\nNotice that we always return a Hand instance from these methods. That’s the\nPython object type we want to store in the model’s attribute.
For to_python(), if anything goes wrong during value conversion, you should\nraise a ValidationError exception.
Since using a database requires conversion in both ways, if you override\nto_python() you also have to override get_prep_value()\nto convert Python objects back to query values.
For example:
\nclass HandField(models.Field):\n # ...\n\n def get_prep_value(self, value):\n return ''.join([''.join(l) for l in (value.north,\n value.east, value.south, value.west)])\nSome data types (for example, dates) need to be in a specific format\nbefore they can be used by a database backend.\nget_db_prep_value() is the method where those conversions should\nbe made. The specific connection that will be used for the query is\npassed as the connection parameter. This allows you to use\nbackend-specific conversion logic if it is required.
For example, Django uses the following method for its\nBinaryField:
def get_db_prep_value(self, value, connection, prepared=False):\n value = super(BinaryField, self).get_db_prep_value(value, connection, prepared)\n if value is not None:\n return connection.Database.Binary(value)\n return value\nIn case your custom field needs a special conversion when being saved that is\nnot the same as the conversion used for normal query parameters, you can\noverride get_db_prep_save().
If you want to preprocess the value just before saving, you can use\npre_save(). For example, Django’s\nDateTimeField uses this method to set the attribute\ncorrectly in the case of auto_now or\nauto_now_add.
If you do override this method, you must return the value of the attribute at\nthe end. You should also update the model’s attribute if you make any changes\nto the value so that code holding references to the model will always see the\ncorrect value.
\nAs with value conversions, preparing a value for database lookups is a\ntwo phase process.
\nget_prep_lookup() performs the first phase of lookup preparation:\ntype conversion and data validation.
Prepares the value for passing to the database when used in a lookup (a\nWHERE constraint in SQL). The lookup_type parameter will be one of the\nvalid Django filter lookups: exact, iexact, contains, icontains,\ngt, gte, lt, lte, in, startswith, istartswith,\nendswith, iendswith, range, year, month, day,\nisnull, search, regex, and iregex.
If you are using custom lookups, the\nlookup_type can be any lookup_name used by the project’s custom lookups.
Your method must be prepared to handle all of these lookup_type values and\nshould raise either a ValueError if the value is of the wrong sort (a\nlist when you were expecting an object, for example) or a TypeError if\nyour field does not support that type of lookup. For many fields, you can get\nby with handling the lookup types that need special handling for your field\nand pass the rest to the get_db_prep_lookup() method of the parent\nclass.
If you needed to implement get_db_prep_save(), you will usually need to\nimplement get_prep_lookup(). If you don’t, get_prep_value() will\nbe called by the default implementation, to manage exact, gt, gte,\nlt, lte, in and range lookups.
You may also want to implement this method to limit the lookup types that could\nbe used with your custom field type.
\nNote that, for "range" and "in" lookups, get_prep_lookup will receive\na list of objects (presumably of the right type) and will need to convert them\nto a list of things of the right type for passing to the database. Most of the\ntime, you can reuse get_prep_value(), or at least factor out some common\npieces.
For example, the following code implements get_prep_lookup to limit the\naccepted lookup types to exact and in:
class HandField(models.Field):\n # ...\n\n def get_prep_lookup(self, lookup_type, value):\n # We only handle 'exact' and 'in'. All others are errors.\n if lookup_type == 'exact':\n return self.get_prep_value(value)\n elif lookup_type == 'in':\n return [self.get_prep_value(v) for v in value]\n else:\n raise TypeError('Lookup type %r not supported.' % lookup_type)\nFor performing database-specific data conversions required by a lookup,\nyou can override get_db_prep_lookup().
To customize the form field used by ModelForm, you can\noverride formfield().
The form field class can be specified via the form_class and\nchoices_form_class arguments; the latter is used if the field has choices\nspecified, the former otherwise. If these arguments are not provided,\nCharField or TypedChoiceField\nwill be used.
All of the kwargs dictionary is passed directly to the form field’s\n__init__() method. Normally, all you need to do is set up a good default\nfor the form_class (and maybe choices_form_class) argument and then\ndelegate further handling to the parent class. This might require you to write\na custom form field (and even a form widget). See the forms documentation for information about this.
Continuing our ongoing example, we can write the formfield() method\nas:
class HandField(models.Field):\n # ...\n\n def formfield(self, **kwargs):\n # This is a fairly standard way to set up some defaults\n # while letting the caller override them.\n defaults = {'form_class': MyFormField}\n defaults.update(kwargs)\n return super(HandField, self).formfield(**defaults)\nThis assumes we’ve imported a MyFormField field class (which has its own\ndefault widget). This document doesn’t cover the details of writing custom form\nfields.
If you have created a db_type() method, you don’t need to worry about\nget_internal_type() – it won’t be used much. Sometimes, though, your\ndatabase storage is similar in type to some other field, so you can use that\nother field’s logic to create the right column.
For example:
\nclass HandField(models.Field):\n # ...\n\n def get_internal_type(self):\n return 'CharField'\nNo matter which database backend we are using, this will mean that\nmigrate and other SQL commands create the right column type for\nstoring a string.
If get_internal_type() returns a string that is not known to Django for\nthe database backend you are using – that is, it doesn’t appear in\ndjango.db.backends.<db_name>.base.DatabaseWrapper.data_types – the string\nwill still be used by the serializer, but the default db_type()\nmethod will return None. See the documentation of db_type()\nfor reasons why this might be useful. Putting a descriptive string in as the\ntype of the field for the serializer is a useful idea if you’re ever going to\nbe using the serializer output in some other place, outside of Django.
To customize how the values are serialized by a serializer, you can override\nvalue_to_string(). Using value_from_object() is the best way\nto get the field’s value prior to serialization. For example, since our\nHandField uses strings for its data storage anyway, we can reuse some\nexisting conversion code:
class HandField(models.Field):\n # ...\n\n def value_to_string(self, obj):\n value = self.value_from_object(obj)\n return self.get_prep_value(value)\nWriting a custom field can be a tricky process, particularly if you’re doing\ncomplex conversions between your Python types and your database and\nserialization formats. Here are a couple of tips to make things go more\nsmoothly:
\nLook at the existing Django fields (in\ndjango/db/models/fields/__init__.py) for inspiration. Try to find\na field that’s similar to what you want and extend it a little bit,\ninstead of creating an entirely new field from scratch.
Put a __str__() (__unicode__() on Python 2) method on the class you’re\nwrapping up as a field. There are a lot of places where the default\nbehavior of the field code is to call\nforce_text() on the value. (In our\nexamples in this document, value would be a Hand instance, not a\nHandField). So if your __str__() method (__unicode__() on\nPython 2) automatically converts to the string form of your Python object,\nyou can save yourself a lot of work.
FileField subclassLink to this heading#In addition to the above methods, fields that deal with files have a few other\nspecial requirements which must be taken into account. The majority of the\nmechanics provided by FileField, such as controlling database storage and\nretrieval, can remain unchanged, leaving subclasses to deal with the challenge\nof supporting a particular type of file.
Django provides a File class, which is used as a proxy to the file’s\ncontents and operations. This can be subclassed to customize how the file is\naccessed, and what methods are available. It lives at\ndjango.db.models.fields.files, and its default behavior is explained in the\nfile documentation.
Once a subclass of File is created, the new FileField subclass must be\ntold to use it. To do so, simply assign the new File subclass to the special\nattr_class attribute of the FileField subclass.
In addition to the above details, there are a few guidelines which can greatly\nimprove the efficiency and readability of the field’s code.
\nThe source for Django’s own ImageField (in\ndjango/db/models/fields/files.py) is a great example of how to\nsubclass FileField to support a particular type of file, as it\nincorporates all of the techniques described above.
Cache file attributes wherever possible. Since files may be stored in\nremote storage systems, retrieving them may cost extra time, or even\nmoney, that isn’t always necessary. Once a file is retrieved to obtain\nsome data about its content, cache as much of that data as possible to\nreduce the number of times the file must be retrieved on subsequent\ncalls for that information.