custom-model-fields.txt 33.5 KB
Newer Older
1 2 3
===========================
Writing custom model fields
===========================
4

5
.. currentmodule:: django.db.models
6 7 8 9

Introduction
============

10
The :doc:`model reference </topics/db/models>` documentation explains how to use
11 12 13 14 15
Django's standard field classes -- :class:`~django.db.models.CharField`,
:class:`~django.db.models.DateField`, etc. For many purposes, those classes are
all you'll need. Sometimes, though, the Django version won't meet your precise
requirements, or you'll want to use a field that is entirely different from
those shipped with Django.
16 17 18 19 20 21

Django's built-in field types don't cover every possible database column type --
only the common types, such as ``VARCHAR`` and ``INTEGER``. For more obscure
column types, such as geographic polygons or even user-created types such as
`PostgreSQL custom types`_, you can define your own Django ``Field`` subclasses.

22
.. _PostgreSQL custom types: http://www.postgresql.org/docs/current/interactive/sql-createtype.html
23

24 25 26 27 28 29 30 31
Alternatively, you may have a complex Python object that can somehow be
serialized to fit into a standard database column type. This is another case
where a ``Field`` subclass will help you use your object with your models.

Our example object
------------------

Creating custom fields requires a bit of attention to detail. To make things
32 33
easier to follow, we'll use a consistent example throughout this document:
wrapping a Python object representing the deal of cards in a hand of Bridge_.
34
Don't worry, you don't have to know how to play Bridge to follow this example.
35 36 37
You only need to know that 52 cards are dealt out equally to four players, who
are traditionally called *north*, *east*, *south* and *west*.  Our class looks
something like this::
38 39

    class Hand(object):
40 41
        """A hand of cards (bridge style)"""

42
        def __init__(self, north, east, south, west):
pp's avatar
pp committed
43
            # Input parameters are lists of cards ('Ah', '9s', etc.)
44 45 46 47
            self.north = north
            self.east = east
            self.south = south
            self.west = west
48

49 50
        # ... (other possibly useful methods omitted) ...

51
.. _Bridge: https://en.wikipedia.org/wiki/Contract_bridge
52

53
This is just an ordinary Python class, with nothing Django-specific about it.
54 55
We'd like to be able to do things like this in our models (we assume the
``hand`` attribute on the model is an instance of ``Hand``)::
56 57

    example = MyModel.objects.get(pk=1)
58
    print(example.hand.north)
59 60 61 62 63 64 65

    new_hand = Hand(north, east, south, west)
    example.hand = new_hand
    example.save()

We assign to and retrieve from the ``hand`` attribute in our model just like
any other Python class. The trick is to tell Django how to handle saving and
66
loading such an object.
67 68 69 70 71 72 73 74 75 76 77

In order to use the ``Hand`` class in our models, we **do not** have to change
this class at all. This is ideal, because it means you can easily write
model support for existing classes where you cannot change the source code.

.. note::
    You might only be wanting to take advantage of custom database column
    types and deal with the data as standard Python types in your models;
    strings, or floats, for example. This case is similar to our ``Hand``
    example and we'll note any differences as we go along.

78
Background theory
79 80 81 82 83 84 85 86 87 88 89 90 91 92
=================

Database storage
----------------

The simplest way to think of a model field is that it provides a way to take a
normal Python object -- string, boolean, ``datetime``, or something more
complex like ``Hand`` -- and convert it to and from a format that is useful
when dealing with the database (and serialization, but, as we'll see later,
that 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
column type. Different databases provide different sets of valid column types,
but the rule is still the same: those are the only types you have to work
93
with. Anything you want to store in the database must fit into one of
94 95 96 97 98 99 100
those types.

Normally, you're either writing a Django field to match a particular database
column type, or there's a fairly straightforward way to convert your data to,
say, a string.

For our ``Hand`` example, we could convert the card data to a string of 104
101 102 103
characters by concatenating all the cards together in a pre-determined order --
say, all the *north* cards first, then the *east*, *south* and *west* cards. So
``Hand`` objects can be saved to text or character columns in the database.
104 105 106 107 108

What does a field class do?
---------------------------

All of Django's fields (and when we say *fields* in this document, we always
109
mean model fields and not :doc:`form fields </ref/forms/fields>`) are subclasses
110
of :class:`django.db.models.Field`. Most of the information that Django records
111 112 113 114 115
about a field is common to all fields -- name, help text, uniqueness and so
forth. Storing all that information is handled by ``Field``. We'll get into the
precise details of what ``Field`` can do later on; for now, suffice it to say
that everything descends from ``Field`` and then customizes key pieces of the
class behavior.
116

117
It's important to realize that a Django field class is not what is stored in
118 119 120 121 122 123
your model attributes. The model attributes contain normal Python objects. The
field classes you define in a model are actually stored in the ``Meta`` class
when the model class is created (the precise details of how this is done are
unimportant here). This is because the field classes aren't necessary when
you're just creating and modifying attributes. Instead, they provide the
machinery for converting between the attribute value and what is stored in the
124
database or sent to the :doc:`serializer </topics/serialization>`.
125 126 127 128 129

Keep this in mind when creating your own custom fields. The Django ``Field``
subclass you write provides the machinery for converting between your Python
instances and the database/serializer values in various ways (there are
differences between storing a value and using a value for lookups, for
130 131 132 133
example). If this sounds a bit tricky, don't worry -- it will become clearer in
the examples below. Just remember that you will often end up creating two
classes when you want a custom field:

134 135 136 137
* The first class is the Python object that your users will manipulate.
  They will assign it to the model attribute, they will read from it for
  displaying purposes, things like that. This is the ``Hand`` class in our
  example.
138

139 140 141
* The second class is the ``Field`` subclass. This is the class that knows
  how to convert your first class back and forth between its permanent
  storage form and the Python form.
142

143 144
Writing a field subclass
========================
145

146 147 148 149 150
When planning your :class:`~django.db.models.Field` subclass, first give some
thought to which existing :class:`~django.db.models.Field` class your new field
is most similar to. Can you subclass an existing Django field and save yourself
some work? If not, you should subclass the :class:`~django.db.models.Field`
class, from which everything is descended.
151

152 153
Initializing your new field is a matter of separating out any arguments that are
specific to your case from the common arguments and passing the latter to the
154 155
``__init__()`` method of :class:`~django.db.models.Field` (or your parent
class).
156

157
In our example, we'll call our field ``HandField``. (It's a good idea to call
158 159 160 161
your :class:`~django.db.models.Field` subclass ``<Something>Field``, so it's
easily identifiable as a :class:`~django.db.models.Field` subclass.) It doesn't
behave like any existing field, so we'll subclass directly from
:class:`~django.db.models.Field`::
162 163 164 165

    from django.db import models

    class HandField(models.Field):
166 167

        description = "A hand of cards (bridge style)"
168

169 170 171 172
        def __init__(self, *args, **kwargs):
            kwargs['max_length'] = 104
            super(HandField, self).__init__(*args, **kwargs)

173
Our ``HandField`` accepts most of the standard field options (see the list
174 175 176 177
below), but we ensure it has a fixed length, since it only needs to hold 52
card values plus their suits; 104 characters in total.

.. note::
178

179
    Many of Django's model fields accept options that they don't do anything
180 181
    with. For example, you can pass both
    :attr:`~django.db.models.Field.editable` and
182
    :attr:`~django.db.models.DateField.auto_now` to a
183 184
    :class:`django.db.models.DateField` and it will simply ignore the
    :attr:`~django.db.models.Field.editable` parameter
185
    (:attr:`~django.db.models.DateField.auto_now` being set implies
186
    ``editable=False``). No error is raised in this case.
187

188
    This behavior simplifies the field classes, because they don't need to
189
    check for options that aren't necessary. They just pass all the options to
190
    the parent class and then don't use them later on. It's up to you whether
191 192
    you want your fields to be more strict about the options they select, or to
    use the simpler, more permissive behavior of the current fields.
193

194
The ``Field.__init__()`` method takes the following parameters:
195

196
* :attr:`~django.db.models.Field.verbose_name`
197
* ``name``
198
* :attr:`~django.db.models.Field.primary_key`
199
* :attr:`~django.db.models.CharField.max_length`
200 201 202 203
* :attr:`~django.db.models.Field.unique`
* :attr:`~django.db.models.Field.blank`
* :attr:`~django.db.models.Field.null`
* :attr:`~django.db.models.Field.db_index`
204 205
* ``rel``: Used for related fields (like :class:`ForeignKey`). For advanced
  use only.
206 207
* :attr:`~django.db.models.Field.default`
* :attr:`~django.db.models.Field.editable`
208 209 210
* ``serialize``: If ``False``, the field will not be serialized when the model
  is passed to Django's :doc:`serializers </topics/serialization>`. Defaults to
  ``True``.
211 212 213 214 215 216
* :attr:`~django.db.models.Field.unique_for_date`
* :attr:`~django.db.models.Field.unique_for_month`
* :attr:`~django.db.models.Field.unique_for_year`
* :attr:`~django.db.models.Field.choices`
* :attr:`~django.db.models.Field.help_text`
* :attr:`~django.db.models.Field.db_column`
217 218 219
* :attr:`~django.db.models.Field.db_tablespace`: Only for index creation, if the
  backend supports :doc:`tablespaces </topics/db/tablespaces>`. You can usually
  ignore this option.
220 221 222
* :attr:`~django.db.models.Field.auto_created`: ``True`` if the field was
  automatically created, as for the :class:`~django.db.models.OneToOneField`
  used by model inheritance. For advanced use only.
223 224

All of the options without an explanation in the above list have the same
225 226
meaning they do for normal Django fields. See the :doc:`field documentation
</ref/models/fields>` for examples and details.
227

228 229
.. _custom-field-deconstruct-method:

230 231 232
Field deconstruction
--------------------

233 234
The counterpoint to writing your ``__init__()`` method is writing the
``deconstruct()`` method. This method tells Django how to take an instance
235
of your new field and reduce it to a serialized form - in particular, what
236
arguments to pass to ``__init__()`` to re-create it.
237 238

If you haven't added any extra options on top of the field you inherited from,
239
then there's no need to write a new ``deconstruct()`` method. If, however,
240
you're changing the arguments passed in ``__init__()`` (like we are in
241
``HandField``), you'll need to supplement the values being passed.
242

243
The contract of ``deconstruct()`` is simple; it returns a tuple of four items:
244
the field's attribute name, the full import path of the field class, the
245 246 247
positional arguments (as a list), and the keyword arguments (as a dict). Note
this is different from the ``deconstruct()`` method :ref:`for custom classes
<custom-deconstruct-method>` which returns a tuple of three things.
248 249 250 251 252 253 254

As a custom field author, you don't need to care about the first two values;
the base ``Field`` class has all the code to work out the field's attribute
name and import path. You do, however, have to care about the positional
and keyword arguments, as these are likely the things you are changing.

For example, in our ``HandField`` class we're always forcibly setting
255
max_length in ``__init__()``. The ``deconstruct()`` method on the base ``Field``
256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280
class will see this and try to return it in the keyword arguments; thus,
we can drop it from the keyword arguments for readability::

    from django.db import models

    class HandField(models.Field):

        def __init__(self, *args, **kwargs):
            kwargs['max_length'] = 104
            super(HandField, self).__init__(*args, **kwargs)

        def deconstruct(self):
            name, path, args, kwargs = super(HandField, self).deconstruct()
            del kwargs["max_length"]
            return name, path, args, kwargs

If you add a new keyword argument, you need to write code to put its value
into ``kwargs`` yourself::

    from django.db import models

    class CommaSepField(models.Field):
        "Implements comma-separated storage of lists"

        def __init__(self, separator=",", *args, **kwargs):
281
            self.separator = separator
282 283 284 285 286 287 288 289 290 291
            super(CommaSepField, self).__init__(*args, **kwargs)

        def deconstruct(self):
            name, path, args, kwargs = super(CommaSepField, self).deconstruct()
            # Only include kwarg if it's not the default
            if self.separator != ",":
                kwargs['separator'] = self.separator
            return name, path, args, kwargs

More complex examples are beyond the scope of this document, but remember -
292
for any configuration of your Field instance, ``deconstruct()`` must return
293 294 295 296 297 298 299
arguments that you can pass to ``__init__`` to reconstruct that state.

Pay extra attention if you set new default values for arguments in the
``Field`` superclass; you want to make sure they're always included, rather
than disappearing if they take on the old default value.

In addition, try to avoid returning values as positional arguments; where
300
possible, return values as keyword arguments for maximum future compatibility.
301 302 303 304 305 306 307 308 309 310 311 312 313
Of course, if you change the names of things more often than their position
in the constructor's argument list, you might prefer positional, but bear in
mind that people will be reconstructing your field from the serialized version
for quite a while (possibly years), depending how long your migrations live for.

You can see the results of deconstruction by looking in migrations that include
the field, and you can test deconstruction in unit tests by just deconstructing
and reconstructing the field::

    name, path, args, kwargs = my_field_instance.deconstruct()
    new_instance = MyField(*args, **kwargs)
    self.assertEqual(my_field_instance.some_attribute, new_instance.some_attribute)

314
Documenting your custom field
315 316 317
-----------------------------

As always, you should document your field type, so users will know what it is.
318 319
In addition to providing a docstring for it, which is useful for developers,
you can also allow users of the admin app to see a short description of the
320 321
field type via the :doc:`django.contrib.admindocs
</ref/contrib/admin/admindocs>` application. To do this simply provide
322 323
descriptive text in a :attr:`~Field.description` class attribute of your custom
field. In the above example, the description displayed by the ``admindocs``
324
application for a ``HandField`` will be 'A hand of cards (bridge style)'.
325

326 327 328 329 330 331 332
In the :mod:`django.contrib.admindocs` display, the field description is
interpolated with ``field.__dict__`` which allows the description to
incorporate arguments of the field. For example, the description for
:class:`~django.db.models.CharField` is::

    description = _("String (up to %(max_length)s)")

333 334 335
Useful methods
--------------

336 337 338 339
Once you've created your :class:`~django.db.models.Field` subclass, you might
consider overriding a few standard methods, depending on your field's behavior.
The list of methods below is in approximately decreasing order of importance,
so start from the top.
340

341 342
.. _custom-database-types:

343 344 345
Custom database types
~~~~~~~~~~~~~~~~~~~~~

346 347
Say you've created a PostgreSQL custom type called ``mytype``. You can
subclass ``Field`` and implement the :meth:`~Field.db_type` method, like so::
348 349 350 351

    from django.db import models

    class MytypeField(models.Field):
352
        def db_type(self, connection):
353 354 355 356 357 358 359 360 361 362 363 364
            return 'mytype'

Once you have ``MytypeField``, you can use it in any model, just like any other
``Field`` type::

    class Person(models.Model):
        name = models.CharField(max_length=80)
        something_else = MytypeField()

If you aim to build a database-agnostic application, you should account for
differences in database column types. For example, the date/time column type
in PostgreSQL is called ``timestamp``, while the same column in MySQL is called
365
``datetime``. The simplest way to handle this in a :meth:`~Field.db_type`
366
method is to check the ``connection.settings_dict['ENGINE']`` attribute.
367

368 369 370
For example::

    class MyDateField(models.Field):
371 372
        def db_type(self, connection):
            if connection.settings_dict['ENGINE'] == 'django.db.backends.mysql':
373 374 375 376
                return 'datetime'
            else:
                return 'timestamp'

377 378 379 380 381 382 383 384
The :meth:`~Field.db_type` and :meth:`~Field.rel_db_type` methods are called by
Django when the framework constructs the ``CREATE TABLE`` statements for your
application -- that is, when you first create your tables. The methods are also
called when constructing a ``WHERE`` clause that includes the model field --
that is, when you retrieve data using QuerySet methods like ``get()``,
``filter()``, and ``exclude()`` and have the model field as an argument. They
are not called at any other time, so it can afford to execute slightly complex
code, such as the ``connection.settings_dict`` check in the above example.
385 386 387 388 389 390 391 392 393

Some database column types accept parameters, such as ``CHAR(25)``, where the
parameter ``25`` represents the maximum column length. In cases like these,
it's more flexible if the parameter is specified in the model rather than being
hard-coded in the ``db_type()`` method. For example, it wouldn't make much
sense to have a ``CharMaxlength25Field``, shown here::

    # This is a silly example of hard-coded parameters.
    class CharMaxlength25Field(models.Field):
394
        def db_type(self, connection):
395 396 397 398 399 400 401 402 403
            return 'char(25)'

    # In the model:
    class MyModel(models.Model):
        # ...
        my_field = CharMaxlength25Field()

The better way of doing this would be to make the parameter specifiable at run
time -- i.e., when the class is instantiated. To do that, just implement
404
``Field.__init__()``, like so::
405 406 407 408 409 410 411

    # This is a much more flexible example.
    class BetterCharField(models.Field):
        def __init__(self, max_length, *args, **kwargs):
            self.max_length = max_length
            super(BetterCharField, self).__init__(*args, **kwargs)

412
        def db_type(self, connection):
413 414 415 416 417 418 419 420
            return 'char(%s)' % self.max_length

    # In the model:
    class MyModel(models.Model):
        # ...
        my_field = BetterCharField(25)

Finally, if your column requires truly complex SQL setup, return ``None`` from
421 422 423 424
:meth:`.db_type`. This will cause Django's SQL creation code to skip
over this field. You are then responsible for creating the column in the right
table in some other way, of course, but this gives you a way to tell Django to
get out of the way.
425

426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442
The :meth:`~Field.rel_db_type` method is called by fields such as ``ForeignKey``
and ``OneToOneField`` that point to another field to determine their database
column data types. For example, if you have an ``UnsignedAutoField``, you also
need the foreign keys that point to that field to use the same data type::

    # MySQL unsigned integer (range 0 to 4294967295).
    class UnsignedAutoField(models.AutoField):
        def db_type(self, connection):
            return 'integer UNSIGNED AUTO_INCREMENT'

        def rel_db_type(self, connection):
            return 'integer UNSIGNED'

.. versionadded:: 1.10

    The :meth:`~Field.rel_db_type` method was added.

443
.. _converting-values-to-python-objects:
444

445 446 447
Converting values to Python objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

448
If your custom :class:`~Field` class deals with data structures that are more
449 450 451 452 453 454 455 456 457 458 459 460
complex than strings, dates, integers, or floats, then you may need to override
:meth:`~Field.from_db_value` and :meth:`~Field.to_python`.

If present for the field subclass, ``from_db_value()`` will be called in all
circumstances when the data is loaded from the database, including in
aggregates and :meth:`~django.db.models.query.QuerySet.values` calls.

``to_python()`` is called by deserialization and during the
:meth:`~django.db.models.Model.clean` method used from forms.

As a general rule, ``to_python()`` should deal gracefully with any of the
following arguments:
461

462
* An instance of the correct type (e.g., ``Hand`` in our ongoing example).
463

464
* A string
465

466
* ``None`` (if the field allows ``null=True``)
467 468

In our ``HandField`` class, we're storing the data as a VARCHAR field in the
469 470 471
database, so we need to be able to process strings and ``None`` in the
``from_db_value()``. In ``to_python()``, we need to also handle ``Hand``
instances::
472 473

    import re
474

475 476 477 478 479 480 481 482 483 484 485 486
    from django.core.exceptions import ValidationError
    from django.db import models

    def parse_hand(hand_string):
        """Takes a string of cards and splits into a full hand."""
        p1 = re.compile('.{26}')
        p2 = re.compile('..')
        args = [p2.findall(x) for x in p1.findall(hand_string)]
        if len(args) != 4:
            raise ValidationError("Invalid input for a Hand instance")
        return Hand(*args)

487 488 489
    class HandField(models.Field):
        # ...

490
        def from_db_value(self, value, expression, connection, context):
491 492 493 494
            if value is None:
                return value
            return parse_hand(value)

495 496 497 498
        def to_python(self, value):
            if isinstance(value, Hand):
                return value

499 500
            if value is None:
                return value
501

502
            return parse_hand(value)
503

504 505
Notice that we always return a ``Hand`` instance from these methods. That's the
Python object type we want to store in the model's attribute.
506

507 508
For ``to_python()``, if anything goes wrong during value conversion, you should
raise a :exc:`~django.core.exceptions.ValidationError` exception.
509

510 511
.. _converting-python-objects-to-query-values:

512 513 514
Converting Python objects to query values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

515 516 517
Since using a database requires conversion in both ways, if you override
:meth:`~Field.to_python` you also have to override :meth:`~Field.get_prep_value`
to convert Python objects back to query values.
518 519 520 521 522 523

For example::

    class HandField(models.Field):
        # ...

524
        def get_prep_value(self, value):
525 526
            return ''.join([''.join(l) for l in (value.north,
                    value.east, value.south, value.west)])
527

528 529 530 531 532 533 534 535 536 537
.. warning::

    If your custom field uses the ``CHAR``, ``VARCHAR`` or ``TEXT``
    types for MySQL, you must make sure that :meth:`.get_prep_value`
    always returns a string type. MySQL performs flexible and unexpected
    matching when a query is performed on these types and the provided
    value is an integer, which can cause queries to include unexpected
    objects in their results. This problem cannot occur if you always
    return a string type from :meth:`.get_prep_value`.

538
.. _converting-query-values-to-database-values:
539

540 541 542 543 544
Converting query values to database values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some data types (for example, dates) need to be in a specific format
before they can be used by a database backend.
545
:meth:`~Field.get_db_prep_value` is the method where those conversions should
546 547 548 549
be made. The specific connection that will be used for the query is
passed as the ``connection`` parameter. This allows you to use
backend-specific conversion logic if it is required.

550
For example, Django uses the following method for its
551
:class:`BinaryField`::
552 553 554 555 556 557

    def get_db_prep_value(self, value, connection, prepared=False):
        value = super(BinaryField, self).get_db_prep_value(value, connection, prepared)
        if value is not None:
            return connection.Database.Binary(value)
        return value
558

559 560 561
In case your custom field needs a special conversion when being saved that is
not the same as the conversion used for normal query parameters, you can
override :meth:`~Field.get_db_prep_save`.
562

563
.. _preprocessing-values-before-saving:
564

565 566
Preprocessing values before saving
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
567

568 569
If you want to preprocess the value just before saving, you can use
:meth:`~Field.pre_save`. For example, Django's
570
:class:`~django.db.models.DateTimeField` uses this method to set the attribute
571 572
correctly in the case of :attr:`~django.db.models.DateField.auto_now` or
:attr:`~django.db.models.DateField.auto_now_add`.
573 574 575 576 577 578

If you do override this method, you must return the value of the attribute at
the end. You should also update the model's attribute if you make any changes
to the value so that code holding references to the model will always see the
correct value.

579 580
.. _preparing-values-for-use-in-database-lookups:

581 582 583
Preparing values for use in database lookups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

584 585 586
As with value conversions, preparing a value for database lookups is a
two phase process.

587 588
:meth:`.get_prep_lookup` performs the first phase of lookup preparation:
type conversion and data validation.
589 590

Prepares the ``value`` for passing to the database when used in a lookup (a
591 592
``WHERE`` constraint in SQL). The ``lookup_type`` parameter will be one of the
valid Django filter lookups: ``exact``, ``iexact``, ``contains``, ``icontains``,
593 594 595 596
``gt``, ``gte``, ``lt``, ``lte``, ``in``, ``startswith``, ``istartswith``,
``endswith``, ``iendswith``, ``range``, ``year``, ``month``, ``day``,
``isnull``, ``search``, ``regex``, and ``iregex``.

597 598
If you are using :doc:`custom lookups </howto/custom-lookups>`, the
``lookup_type`` can be any ``lookup_name`` used by the project's custom lookups.
599

600 601 602 603 604
Your method must be prepared to handle all of these ``lookup_type`` values and
should raise either a ``ValueError`` if the ``value`` is of the wrong sort (a
list when you were expecting an object, for example) or a ``TypeError`` if
your field does not support that type of lookup. For many fields, you can get
by with handling the lookup types that need special handling for your field
605 606
and pass the rest to the :meth:`~Field.get_db_prep_lookup` method of the parent
class.
607

608 609 610
If you needed to implement :meth:`.get_db_prep_save`, you will usually need to
implement :meth:`.get_prep_lookup`. If you don't, :meth:`.get_prep_value` will
be called by the default implementation, to manage ``exact``, ``gt``, ``gte``,
611
``lt``, ``lte``, ``in`` and ``range`` lookups.
612

613 614 615
You may also want to implement this method to limit the lookup types that could
be used with your custom field type.

616
Note that, for ``"range"`` and ``"in"`` lookups, ``get_prep_lookup`` will receive
617 618
a list of objects (presumably of the right type) and will need to convert them
to a list of things of the right type for passing to the database. Most of the
619
time, you can reuse ``get_prep_value()``, or at least factor out some common
620 621
pieces.

622
For example, the following code implements ``get_prep_lookup`` to limit the
623
accepted lookup types to ``exact`` and ``in``::
624 625 626 627

    class HandField(models.Field):
        # ...

628
        def get_prep_lookup(self, lookup_type, value):
629 630
            # We only handle 'exact' and 'in'. All others are errors.
            if lookup_type == 'exact':
631
                return self.get_prep_value(value)
632
            elif lookup_type == 'in':
633
                return [self.get_prep_value(v) for v in value]
634 635 636
            else:
                raise TypeError('Lookup type %r not supported.' % lookup_type)

637 638
For performing database-specific data conversions required by a lookup,
you can override :meth:`~Field.get_db_prep_lookup`.
639

640
.. _specifying-form-field-for-model-field:
641

642 643
Specifying the form field for a model field
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
644

645 646
To customize the form field used by :class:`~django.forms.ModelForm`, you can
override :meth:`~Field.formfield`.
647 648 649 650 651 652

The form field class can be specified via the ``form_class`` and
``choices_form_class`` arguments; the latter is used if the field has choices
specified, the former otherwise. If these arguments are not provided,
:class:`~django.forms.CharField` or :class:`~django.forms.TypedChoiceField`
will be used.
653 654

All of the ``kwargs`` dictionary is passed directly to the form field's
655
``__init__()`` method. Normally, all you need to do is set up a good default
656 657 658 659
for the ``form_class`` (and maybe ``choices_form_class``) argument and then
delegate further handling to the parent class. This might require you to write
a custom form field (and even a form widget). See the :doc:`forms documentation
</topics/forms/index>` for information about this.
660

661 662
Continuing our ongoing example, we can write the :meth:`~Field.formfield` method
as::
663 664 665 666 667 668

    class HandField(models.Field):
        # ...

        def formfield(self, **kwargs):
            # This is a fairly standard way to set up some defaults
669
            # while letting the caller override them.
670 671 672 673
            defaults = {'form_class': MyFormField}
            defaults.update(kwargs)
            return super(HandField, self).formfield(**defaults)

674
This assumes we've imported a ``MyFormField`` field class (which has its own
675 676
default widget). This document doesn't cover the details of writing custom form
fields.
677

678 679
.. _helper functions: ../forms/#generating-forms-for-models
.. _forms documentation: ../forms/
680

681 682
.. _emulating-built-in-field-types:

683 684 685
Emulating built-in field types
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

686 687
If you have created a :meth:`.db_type` method, you don't need to worry about
:meth:`.get_internal_type` -- it won't be used much. Sometimes, though, your
688 689 690 691 692 693 694 695 696 697 698
database storage is similar in type to some other field, so you can use that
other field's logic to create the right column.

For example::

    class HandField(models.Field):
        # ...

        def get_internal_type(self):
            return 'CharField'

699 700 701
No matter which database backend we are using, this will mean that
:djadmin:`migrate` and other SQL commands create the right column type for
storing a string.
702

703
If :meth:`.get_internal_type` returns a string that is not known to Django for
704
the database backend you are using -- that is, it doesn't appear in
705 706 707 708 709 710
``django.db.backends.<db_name>.base.DatabaseWrapper.data_types`` -- the string
will still be used by the serializer, but the default :meth:`~Field.db_type`
method will return ``None``. See the documentation of :meth:`~Field.db_type`
for reasons why this might be useful. Putting a descriptive string in as the
type of the field for the serializer is a useful idea if you're ever going to
be using the serializer output in some other place, outside of Django.
711 712

.. _converting-model-field-to-serialization:
713 714 715

Converting field data for serialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
716

717
To customize how the values are serialized by a serializer, you can override
718 719 720 721
:meth:`~Field.value_to_string`. Using ``value_from_object()`` is the best way
to get the field's value prior to serialization. For example, since our
``HandField`` uses strings for its data storage anyway, we can reuse some
existing conversion code::
722 723 724 725

    class HandField(models.Field):
        # ...

726
        def value_to_string(self, obj):
727
            value = self.value_from_object(obj)
728
            return self.get_prep_value(value)
729 730 731 732

Some general advice
--------------------

733 734 735 736 737
Writing a custom field can be a tricky process, particularly if you're doing
complex conversions between your Python types and your database and
serialization formats. Here are a couple of tips to make things go more
smoothly:

738 739 740 741
1. Look at the existing Django fields (in
   :file:`django/db/models/fields/__init__.py`) for inspiration. Try to find
   a field that's similar to what you want and extend it a little bit,
   instead of creating an entirely new field from scratch.
742

743
2. Put a ``__str__()`` (``__unicode__()`` on Python 2) method on the class you're
744 745
   wrapping up as a field. There are a lot of places where the default
   behavior of the field code is to call
746
   :func:`~django.utils.encoding.force_text` on the value. (In our
747
   examples in this document, ``value`` would be a ``Hand`` instance, not a
748 749
   ``HandField``). So if your ``__str__()`` method (``__unicode__()`` on
   Python 2) automatically converts to the string form of your Python object,
750
   you can save yourself a lot of work.
751

752
Writing a ``FileField`` subclass
753
================================
754 755 756 757 758 759 760 761

In addition to the above methods, fields that deal with files have a few other
special requirements which must be taken into account. The majority of the
mechanics provided by ``FileField``, such as controlling database storage and
retrieval, can remain unchanged, leaving subclasses to deal with the challenge
of supporting a particular type of file.

Django provides a ``File`` class, which is used as a proxy to the file's
762
contents and operations. This can be subclassed to customize how the file is
763 764
accessed, and what methods are available. It lives at
``django.db.models.fields.files``, and its default behavior is explained in the
765
:doc:`file documentation </ref/files/file>`.
766 767 768 769 770 771 772 773 774 775 776

Once a subclass of ``File`` is created, the new ``FileField`` subclass must be
told to use it. To do so, simply assign the new ``File`` subclass to the special
``attr_class`` attribute of the ``FileField`` subclass.

A few suggestions
------------------

In addition to the above details, there are a few guidelines which can greatly
improve the efficiency and readability of the field's code.

777 778 779 780 781 782 783 784 785 786 787
1. The source for Django's own ``ImageField`` (in
   ``django/db/models/fields/files.py``) is a great example of how to
   subclass ``FileField`` to support a particular type of file, as it
   incorporates all of the techniques described above.

2. Cache file attributes wherever possible. Since files may be stored in
   remote storage systems, retrieving them may cost extra time, or even
   money, that isn't always necessary. Once a file is retrieved to obtain
   some data about its content, cache as much of that data as possible to
   reduce the number of times the file must be retrieved on subsequent
   calls for that information.