Debian Codegraph @

docs/howto/custom-model-fields.txt

raw
1 =================================
2 How to create custom model fields
3 =================================
4
5 .. currentmodule:: django.db.models
6
7 Introduction
8 ============
9
10 The :doc:`model reference </topics/db/models>` documentation explains how to use
11 Django's standard field classes -- :class:`~django.db.models.CharField`,
12 :class:`~django.db.models.DateField`, etc. For many purposes, those classes are
13 all you'll need. Sometimes, though, the Django version won't meet your precise
14 requirements, or you'll want to use a field that is entirely different from
15 those shipped with Django.
16
17 Django's built-in field types don't cover every possible database column type --
18 only the common types, such as ``VARCHAR`` and ``INTEGER``. For more obscure
19 column types, such as geographic polygons or even user-created types such as
20 `PostgreSQL custom types`_, you can define your own Django ``Field`` subclasses.
21
22 .. _PostgreSQL custom types: https://www.postgresql.org/docs/current/sql-createtype.html
23
24 Alternatively, you may have a complex Python object that can somehow be
25 serialized to fit into a standard database column type. This is another case
26 where a ``Field`` subclass will help you use your object with your models.
27
28 Our example object
29 ------------------
30
31 Creating custom fields requires a bit of attention to detail. To make things
32 easier to follow, we'll use a consistent example throughout this document:
33 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 You only need to know that 52 cards are dealt out equally to four players, who
36 are traditionally called *north*, *east*, *south* and *west*. Our class looks
37 something like this::
38
39 class Hand:
40 """A hand of cards (bridge style)"""
41
42 def __init__(self, north, east, south, west):
43 # Input parameters are lists of cards ('Ah', '9s', etc.)
44 self.north = north
45 self.east = east
46 self.south = south
47 self.west = west
48
49 # ... (other possibly useful methods omitted) ...
50
51 .. _Bridge: https://en.wikipedia.org/wiki/Contract_bridge
52
53 This is an ordinary Python class, with nothing Django-specific about it.
54 We'd like to be able to do things like this in our models (we assume the
55 ``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 new_hand = Hand(north, east, south, west)
61 example.hand = new_hand
62 example.save()
63
64 We assign to and retrieve from the ``hand`` attribute in our model just like
65 any other Python class. The trick is to tell Django how to handle saving and
66 loading such an object.
67
68 In order to use the ``Hand`` class in our models, we **do not** have to change
69 this class at all. This is ideal, because it means you can easily write
70 model support for existing classes where you cannot change the source code.
71
72 .. note::
73 You might only be wanting to take advantage of custom database column
74 types and deal with the data as standard Python types in your models;
75 strings, or floats, for example. This case is similar to our ``Hand``
76 example and we'll note any differences as we go along.
77
78 Background theory
79 =================
80
81 Database storage
82 ----------------
83
84 Let's start with model fields. If you break it down, a model field provides a
85 way to take a normal Python object -- string, boolean, ``datetime``, or
86 something more complex like ``Hand`` -- and convert it to and from a format
87 that is useful when dealing with the database. (Such a format is also useful
88 for serialization, but as we'll see later, that is easier once you have the
89 database side under control).
90
91 Fields in a model must somehow be converted to fit into an existing database
92 column type. Different databases provide different sets of valid column types,
93 but the rule is still the same: those are the only types you have to work
94 with. Anything you want to store in the database must fit into one of
95 those types.
96
97 Normally, you're either writing a Django field to match a particular database
98 column type, or you will need a way to convert your data to, say, a string.
99
100 For our ``Hand`` example, we could convert the card data to a string of 104
101 characters by concatenating all the cards together in a predetermined order --
102 say, all the *north* cards first, then the *east*, *south* and *west* cards. So
103 ``Hand`` objects can be saved to text or character columns in the database.
104
105 What does a field class do?
106 ---------------------------
107
108 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 about a field is common to all fields -- name, help text, uniqueness and so
112 forth. Storing all that information is handled by ``Field``. We'll get into the
113 precise details of what ``Field`` can do later on; for now, suffice it to say
114 that everything descends from ``Field`` and then customizes key pieces of the
115 class behavior.
116
117 It's important to realize that a Django field class is not what is stored in
118 your model attributes. The model attributes contain normal Python objects. The
119 field classes you define in a model are actually stored in the ``Meta`` class
120 when the model class is created (the precise details of how this is done are
121 unimportant here). This is because the field classes aren't necessary when
122 you're just creating and modifying attributes. Instead, they provide the
123 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 Keep this in mind when creating your own custom fields. The Django ``Field``
127 subclass you write provides the machinery for converting between your Python
128 instances and the database/serializer values in various ways (there are
129 differences between storing a value and using a value for lookups, for
130 example). If this sounds a bit tricky, don't worry -- it will become clearer in
131 the examples below. Just remember that you will often end up creating two
132 classes when you want a custom field:
133
134 * The first class is the Python object that your users will manipulate.
135 They will assign it to the model attribute, they will read from it for
136 displaying purposes, things like that. This is the ``Hand`` class in our
137 example.
138
139 * The second class is the ``Field`` subclass. This is the class that knows
140 how to convert your first class back and forth between its permanent
141 storage form and the Python form.
142
143 Writing a field subclass
144 ========================
145
146 When planning your :class:`~django.db.models.Field` subclass, first give some
147 thought to which existing :class:`~django.db.models.Field` class your new field
148 is most similar to. Can you subclass an existing Django field and save yourself
149 some work? If not, you should subclass the :class:`~django.db.models.Field`
150 class, from which everything is descended.
151
152 Initializing your new field is a matter of separating out any arguments that are
153 specific to your case from the common arguments and passing the latter to the
154 ``__init__()`` method of :class:`~django.db.models.Field` (or your parent
155 class).
156
157 In our example, we'll call our field ``HandField``. (It's a good idea to call
158 your :class:`~django.db.models.Field` subclass ``<Something>Field``, so it's
159 easily identifiable as a :class:`~django.db.models.Field` subclass.) It doesn't
160 behave like any existing field, so we'll subclass directly from
161 :class:`~django.db.models.Field`::
162
163 from django.db import models
164
165
166 class HandField(models.Field):
167 description = "A hand of cards (bridge style)"
168
169 def __init__(self, *args, **kwargs):
170 kwargs["max_length"] = 104
171 super().__init__(*args, **kwargs)
172
173 Our ``HandField`` accepts most of the standard field options (see the list
174 below), but we ensure it has a fixed length, since it only needs to hold 52
175 card values plus their suits; 104 characters in total.
176
177 .. note::
178
179 Many of Django's model fields accept options that they don't do anything
180 with. For example, you can pass both
181 :attr:`~django.db.models.Field.editable` and
182 :attr:`~django.db.models.DateField.auto_now` to a
183 :class:`django.db.models.DateField` and it will ignore the
184 :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 pass all the options to
190 the parent class and then don't use them later on. It's up to you whether
191 you want your fields to be more strict about the options they select, or to
192 use the 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 * :attr:`~django.db.models.Field.unique`
201 * :attr:`~django.db.models.Field.blank`
202 * :attr:`~django.db.models.Field.null`
203 * :attr:`~django.db.models.Field.db_index`
204 * ``rel``: Used for related fields (like :class:`ForeignKey`). For advanced
205 use only.
206 * :attr:`~django.db.models.Field.default`
207 * :attr:`~django.db.models.Field.editable`
208 * ``serialize``: If ``False``, the field will not be serialized when the model
209 is passed to Django's :doc:`serializers </topics/serialization>`. Defaults to
210 ``True``.
211 * :attr:`~django.db.models.Field.unique_for_date`
212 * :attr:`~django.db.models.Field.unique_for_month`
213 * :attr:`~django.db.models.Field.unique_for_year`
214 * :attr:`~django.db.models.Field.choices`
215 * :attr:`~django.db.models.Field.help_text`
216 * :attr:`~django.db.models.Field.db_column`
217 * :attr:`~django.db.models.Field.db_tablespace`: Only for index creation, if the
218 backend supports :doc:`tablespaces </topics/db/tablespaces>`. You can usually
219 ignore this option.
220 * :attr:`~django.db.models.Field.auto_created`: ``True`` if the field was
221 automatically created, as for the :class:`~django.db.models.OneToOneField`
222 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 meaning they do for normal Django fields. See the :doc:`field documentation
226 </ref/models/fields>` for examples and details.
227
228 .. _custom-field-deconstruct-method:
229
230 Field deconstruction
231 --------------------
232
233 The counterpoint to writing your ``__init__()`` method is writing the
234 :meth:`~.Field.deconstruct` method. It's used during :doc:`model migrations
235 </topics/migrations>` to tell Django how to take an instance of your new field
236 and reduce it to a serialized form - in particular, what arguments to pass to
237 ``__init__()`` to recreate it.
238
239 If you haven't added any extra options on top of the field you inherited from,
240 then there's no need to write a new ``deconstruct()`` method. If, however,
241 you're changing the arguments passed in ``__init__()`` (like we are in
242 ``HandField``), you'll need to supplement the values being passed.
243
244 ``deconstruct()`` returns a tuple of four items: the field's attribute name,
245 the full import path of the field class, the positional arguments (as a list),
246 and the keyword arguments (as a dict). Note this is different from the
247 ``deconstruct()`` method :ref:`for custom classes <custom-deconstruct-method>`
248 which returns a tuple of three things.
249
250 As a custom field author, you don't need to care about the first two values;
251 the base ``Field`` class has all the code to work out the field's attribute
252 name and import path. You do, however, have to care about the positional
253 and keyword arguments, as these are likely the things you are changing.
254
255 For example, in our ``HandField`` class we're always forcibly setting
256 max_length in ``__init__()``. The ``deconstruct()`` method on the base ``Field``
257 class will see this and try to return it in the keyword arguments; thus,
258 we can drop it from the keyword arguments for readability::
259
260 from django.db import models
261
262
263 class HandField(models.Field):
264 def __init__(self, *args, **kwargs):
265 kwargs["max_length"] = 104
266 super().__init__(*args, **kwargs)
267
268 def deconstruct(self):
269 name, path, args, kwargs = super().deconstruct()
270 del kwargs["max_length"]
271 return name, path, args, kwargs
272
273 If you add a new keyword argument, you need to write code in ``deconstruct()``
274 that puts its value into ``kwargs`` yourself. You should also omit the value
275 from ``kwargs`` when it isn't necessary to reconstruct the state of the field,
276 such as when the default value is being used::
277
278 from django.db import models
279
280
281 class CommaSepField(models.Field):
282 "Implements comma-separated storage of lists"
283
284 def __init__(self, separator=",", *args, **kwargs):
285 self.separator = separator
286 super().__init__(*args, **kwargs)
287
288 def deconstruct(self):
289 name, path, args, kwargs = super().deconstruct()
290 # Only include kwarg if it's not the default
291 if self.separator != ",":
292 kwargs["separator"] = self.separator
293 return name, path, args, kwargs
294
295 More complex examples are beyond the scope of this document, but remember -
296 for any configuration of your Field instance, ``deconstruct()`` must return
297 arguments that you can pass to ``__init__`` to reconstruct that state.
298
299 Pay extra attention if you set new default values for arguments in the
300 ``Field`` superclass; you want to make sure they're always included, rather
301 than disappearing if they take on the old default value.
302
303 In addition, try to avoid returning values as positional arguments; where
304 possible, return values as keyword arguments for maximum future compatibility.
305 If you change the names of things more often than their position in the
306 constructor's argument list, you might prefer positional, but bear in mind that
307 people will be reconstructing your field from the serialized version for quite
308 a while (possibly years), depending how long your migrations live for.
309
310 You can see the results of deconstruction by looking in migrations that include
311 the field, and you can test deconstruction in unit tests by deconstructing and
312 reconstructing the field::
313
314 name, path, args, kwargs = my_field_instance.deconstruct()
315 new_instance = MyField(*args, **kwargs)
316 self.assertEqual(my_field_instance.some_attribute, new_instance.some_attribute)
317
318 .. _custom-field-non_db_attrs:
319
320 Field attributes not affecting database column definition
321 ---------------------------------------------------------
322
323 You can override ``Field.non_db_attrs`` to customize attributes of a field that
324 don't affect a column definition. It's used during model migrations to detect
325 no-op ``AlterField`` operations.
326
327 For example::
328
329 class CommaSepField(models.Field):
330 @property
331 def non_db_attrs(self):
332 return super().non_db_attrs + ("separator",)
333
334
335 Changing a custom field's base class
336 ------------------------------------
337
338 You can't change the base class of a custom field because Django won't detect
339 the change and make a migration for it. For example, if you start with::
340
341 class CustomCharField(models.CharField): ...
342
343 and then decide that you want to use ``TextField`` instead, you can't change
344 the subclass like this::
345
346 class CustomCharField(models.TextField): ...
347
348 Instead, you must create a new custom field class and update your models to
349 reference it::
350
351 class CustomCharField(models.CharField): ...
352
353
354 class CustomTextField(models.TextField): ...
355
356 As discussed in :ref:`removing fields <migrations-removing-model-fields>`, you
357 must retain the original ``CustomCharField`` class as long as you have
358 migrations that reference it.
359
360 Documenting your custom field
361 -----------------------------
362
363 As always, you should document your field type, so users will know what it is.
364 In addition to providing a docstring for it, which is useful for developers,
365 you can also allow users of the admin app to see a short description of the
366 field type via the :doc:`django.contrib.admindocs
367 </ref/contrib/admin/admindocs>` application. To do this provide descriptive
368 text in a :attr:`~Field.description` class attribute of your custom field. In
369 the above example, the description displayed by the ``admindocs`` application
370 for a ``HandField`` will be 'A hand of cards (bridge style)'.
371
372 In the :mod:`django.contrib.admindocs` display, the field description is
373 interpolated with ``field.__dict__`` which allows the description to
374 incorporate arguments of the field. For example, the description for
375 :class:`~django.db.models.CharField` is::
376
377 description = _("String (up to %(max_length)s)")
378
379 Useful methods
380 --------------
381
382 Once you've created your :class:`~django.db.models.Field` subclass, you might
383 consider overriding a few standard methods, depending on your field's behavior.
384 The list of methods below is in approximately decreasing order of importance,
385 so start from the top.
386
387 .. _custom-database-types:
388
389 Custom database types
390 ~~~~~~~~~~~~~~~~~~~~~
391
392 Say you've created a PostgreSQL custom type called ``mytype``. You can
393 subclass ``Field`` and implement the :meth:`~Field.db_type` method, like so::
394
395 from django.db import models
396
397
398 class MytypeField(models.Field):
399 def db_type(self, connection):
400 return "mytype"
401
402 Once you have ``MytypeField``, you can use it in any model, just like any other
403 ``Field`` type::
404
405 class Person(models.Model):
406 name = models.CharField(max_length=80)
407 something_else = MytypeField()
408
409 If you aim to build a database-agnostic application, you should account for
410 differences in database column types. For example, the date/time column type
411 in PostgreSQL is called ``timestamp``, while the same column in MySQL is called
412 ``datetime``. You can handle this in a :meth:`~Field.db_type` method by
413 checking the ``connection.vendor`` attribute. Current built-in vendor names
414 are: ``sqlite``, ``postgresql``, ``mysql``, and ``oracle``.
415
416 For example::
417
418 class MyDateField(models.Field):
419 def db_type(self, connection):
420 if connection.vendor == "mysql":
421 return "datetime"
422 else:
423 return "timestamp"
424
425 The :meth:`~Field.db_type` and :meth:`~Field.rel_db_type` methods are called by
426 Django when the framework constructs the ``CREATE TABLE`` statements for your
427 application -- that is, when you first create your tables. The methods are also
428 called when constructing a ``WHERE`` clause that includes the model field --
429 that is, when you retrieve data using QuerySet methods like ``get()``,
430 ``filter()``, and ``exclude()`` and have the model field as an argument.
431
432 Some database column types accept parameters, such as ``CHAR(25)``, where the
433 parameter ``25`` represents the maximum column length. In cases like these,
434 it's more flexible if the parameter is specified in the model rather than being
435 hard-coded in the ``db_type()`` method. For example, it wouldn't make much
436 sense to have a ``CharMaxlength25Field``, shown here::
437
438 # This is a silly example of hard-coded parameters.
439 class CharMaxlength25Field(models.Field):
440 def db_type(self, connection):
441 return "char(25)"
442
443
444 # In the model:
445 class MyModel(models.Model):
446 # ...
447 my_field = CharMaxlength25Field()
448
449 The better way of doing this would be to make the parameter specifiable at run
450 time -- i.e., when the class is instantiated. To do that, implement
451 ``Field.__init__()``, like so::
452
453 # This is a much more flexible example.
454 class BetterCharField(models.Field):
455 def __init__(self, max_length, *args, **kwargs):
456 self.max_length = max_length
457 super().__init__(*args, **kwargs)
458
459 def db_type(self, connection):
460 return "char(%s)" % self.max_length
461
462
463 # In the model:
464 class MyModel(models.Model):
465 # ...
466 my_field = BetterCharField(25)
467
468 Finally, if your column requires truly complex SQL setup, return ``None`` from
469 :meth:`.db_type`. This will cause Django's SQL creation code to skip
470 over this field. You are then responsible for creating the column in the right
471 table in some other way, but this gives you a way to tell Django to get out of
472 the way.
473
474 The :meth:`~Field.rel_db_type` method is called by fields such as ``ForeignKey``
475 and ``OneToOneField`` that point to another field to determine their database
476 column data types. For example, if you have an ``UnsignedAutoField``, you also
477 need the foreign keys that point to that field to use the same data type::
478
479 # MySQL unsigned integer (range 0 to 4294967295).
480 class UnsignedAutoField(models.AutoField):
481 def db_type(self, connection):
482 return "integer UNSIGNED AUTO_INCREMENT"
483
484 def rel_db_type(self, connection):
485 return "integer UNSIGNED"
486
487 .. _converting-values-to-python-objects:
488
489 Converting values to Python objects
490 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
491
492 If your custom :class:`~Field` class deals with data structures that are more
493 complex than strings, dates, integers, or floats, then you may need to override
494 :meth:`~Field.from_db_value` and :meth:`~Field.to_python`.
495
496 If present for the field subclass, ``from_db_value()`` will be called in all
497 circumstances when the data is loaded from the database, including in
498 aggregates and :meth:`~django.db.models.query.QuerySet.values` calls.
499
500 ``to_python()`` is called by deserialization and during the
501 :meth:`~django.db.models.Model.clean` method used from forms.
502
503 As a general rule, ``to_python()`` should deal gracefully with any of the
504 following arguments:
505
506 * An instance of the correct type (e.g., ``Hand`` in our ongoing example).
507
508 * A string
509
510 * ``None`` (if the field allows ``null=True``)
511
512 In our ``HandField`` class, we're storing the data as a ``VARCHAR`` field in
513 the database, so we need to be able to process strings and ``None`` in the
514 ``from_db_value()``. In ``to_python()``, we need to also handle ``Hand``
515 instances::
516
517 import re
518
519 from django.core.exceptions import ValidationError
520 from django.db import models
521 from django.utils.translation import gettext_lazy as _
522
523
524 def parse_hand(hand_string):
525 """Takes a string of cards and splits into a full hand."""
526 p1 = re.compile(".{26}")
527 p2 = re.compile("..")
528 args = [p2.findall(x) for x in p1.findall(hand_string)]
529 if len(args) != 4:
530 raise ValidationError(_("Invalid input for a Hand instance"))
531 return Hand(*args)
532
533
534 class HandField(models.Field):
535 # ...
536
537 def from_db_value(self, value, expression, connection):
538 if value is None:
539 return value
540 return parse_hand(value)
541
542 def to_python(self, value):
543 if isinstance(value, Hand):
544 return value
545
546 if value is None:
547 return value
548
549 return parse_hand(value)
550
551 Notice that we always return a ``Hand`` instance from these methods. That's the
552 Python object type we want to store in the model's attribute.
553
554 For ``to_python()``, if anything goes wrong during value conversion, you should
555 raise a :exc:`~django.core.exceptions.ValidationError` exception.
556
557 .. _converting-python-objects-to-query-values:
558
559 Converting Python objects to query values
560 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
561
562 Since using a database requires conversion in both ways, if you override
563 :meth:`~Field.from_db_value` you also have to override
564 :meth:`~Field.get_prep_value` to convert Python objects back to query values.
565
566 For example::
567
568 class HandField(models.Field):
569 # ...
570
571 def get_prep_value(self, value):
572 return "".join(
573 ["".join(l) for l in (value.north, value.east, value.south, value.west)]
574 )
575
576 .. warning::
577
578 If your custom field uses the ``CHAR``, ``VARCHAR`` or ``TEXT``
579 types for MySQL, you must make sure that :meth:`.get_prep_value`
580 always returns a string type. MySQL performs flexible and unexpected
581 matching when a query is performed on these types and the provided
582 value is an integer, which can cause queries to include unexpected
583 objects in their results. This problem cannot occur if you always
584 return a string type from :meth:`.get_prep_value`.
585
586 .. _converting-query-values-to-database-values:
587
588 Converting query values to database values
589 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
590
591 Some data types (for example, dates) need to be in a specific format
592 before they can be used by a database backend.
593 :meth:`~Field.get_db_prep_value` is the method where those conversions should
594 be made. The specific connection that will be used for the query is
595 passed as the ``connection`` parameter. This allows you to use
596 backend-specific conversion logic if it is required.
597
598 For example, Django uses the following method for its
599 :class:`BinaryField`::
600
601 def get_db_prep_value(self, value, connection, prepared=False):
602 value = super().get_db_prep_value(value, connection, prepared)
603 if value is not None:
604 return connection.Database.Binary(value)
605 return value
606
607 In case your custom field needs a special conversion when being saved that is
608 not the same as the conversion used for normal query parameters, you can
609 override :meth:`~Field.get_db_prep_save`.
610
611 .. _preprocessing-values-before-saving:
612
613 Preprocessing values before saving
614 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
615
616 If you want to preprocess the value just before saving, you can use
617 :meth:`~Field.pre_save`. For example, Django's
618 :class:`~django.db.models.DateTimeField` uses this method to set the attribute
619 correctly in the case of :attr:`~django.db.models.DateField.auto_now` or
620 :attr:`~django.db.models.DateField.auto_now_add`.
621
622 If you do override this method, you must return the value of the attribute at
623 the end. You should also update the model's attribute if you make any changes
624 to the value so that code holding references to the model will always see the
625 correct value.
626
627 .. _specifying-form-field-for-model-field:
628
629 Specifying the form field for a model field
630 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
631
632 To customize the form field used by :class:`~django.forms.ModelForm`, you can
633 override :meth:`~Field.formfield`.
634
635 The form field class can be specified via the ``form_class`` and
636 ``choices_form_class`` arguments; the latter is used if the field has choices
637 specified, the former otherwise. If these arguments are not provided,
638 :class:`~django.forms.CharField` or :class:`~django.forms.TypedChoiceField`
639 will be used.
640
641 All of the ``kwargs`` dictionary is passed directly to the form field's
642 ``__init__()`` method. Normally, all you need to do is set up a good default
643 for the ``form_class`` (and maybe ``choices_form_class``) argument and then
644 delegate further handling to the parent class. This might require you to write
645 a custom form field (and even a form widget). See the :doc:`forms documentation
646 </topics/forms/index>` for information about this.
647
648 If you wish to exclude the field from the :class:`~django.forms.ModelForm`, you
649 can override the :meth:`~Field.formfield` method to return ``None``.
650
651 Continuing our ongoing example, we can write the :meth:`~Field.formfield` method
652 as::
653
654 class HandField(models.Field):
655 # ...
656
657 def formfield(self, **kwargs):
658 # Exclude the field from the ModelForm when some condition is met.
659 some_condition = kwargs.get("some_condition", False)
660 if some_condition:
661 return None
662
663 # Set up some defaults while letting the caller override them.
664 defaults = {"form_class": MyFormField}
665 defaults.update(kwargs)
666 return super().formfield(**defaults)
667
668 This assumes we've imported a ``MyFormField`` field class (which has its own
669 default widget). This document doesn't cover the details of writing custom form
670 fields.
671
672 .. _helper functions: ../forms/#generating-forms-for-models
673 .. _forms documentation: ../forms/
674
675 .. _emulating-built-in-field-types:
676
677 Emulating built-in field types
678 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
679
680 If you have created a :meth:`.db_type` method, you don't need to worry about
681 :meth:`.get_internal_type` -- it won't be used much. Sometimes, though, your
682 database storage is similar in type to some other field, so you can use that
683 other field's logic to create the right column.
684
685 For example::
686
687 class HandField(models.Field):
688 # ...
689
690 def get_internal_type(self):
691 return "CharField"
692
693 No matter which database backend we are using, this will mean that
694 :djadmin:`migrate` and other SQL commands create the right column type for
695 storing a string.
696
697 If :meth:`.get_internal_type` returns a string that is not known to Django for
698 the database backend you are using -- that is, it doesn't appear in
699 ``django.db.backends.<db_name>.base.DatabaseWrapper.data_types`` -- the string
700 will still be used by the serializer, but the default :meth:`~Field.db_type`
701 method will return ``None``. See the documentation of :meth:`~Field.db_type`
702 for reasons why this might be useful. Putting a descriptive string in as the
703 type of the field for the serializer is a useful idea if you're ever going to
704 be using the serializer output in some other place, outside of Django.
705
706 .. _converting-model-field-to-serialization:
707
708 Converting field data for serialization
709 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
710
711 To customize how the values are serialized by a serializer, you can override
712 :meth:`~Field.value_to_string`. Using :meth:`~Field.value_from_object` is the
713 best way to get the field's value prior to serialization. For example, since
714 ``HandField`` uses strings for its data storage anyway, we can reuse some
715 existing conversion code::
716
717 class HandField(models.Field):
718 # ...
719
720 def value_to_string(self, obj):
721 value = self.value_from_object(obj)
722 return self.get_prep_value(value)
723
724 Some general advice
725 -------------------
726
727 Writing a custom field can be a tricky process, particularly if you're doing
728 complex conversions between your Python types and your database and
729 serialization formats. Here are a couple of tips to make things go more
730 smoothly:
731
732 #. Look at the existing Django fields (in
733 :source:`django/db/models/fields/__init__.py`) for inspiration. Try to find
734 a field that's similar to what you want and extend it a little bit,
735 instead of creating an entirely new field from scratch.
736
737 #. Put a ``__str__()`` method on the class you're wrapping up as a field. There
738 are a lot of places where the default behavior of the field code is to call
739 ``str()`` on the value. (In our examples in this document, ``value`` would
740 be a ``Hand`` instance, not a ``HandField``). So if your ``__str__()``
741 method automatically converts to the string form of your Python object, you
742 can save yourself a lot of work.
743
744 Writing a ``FileField`` subclass
745 ================================
746
747 In addition to the above methods, fields that deal with files have a few other
748 special requirements which must be taken into account. The majority of the
749 mechanics provided by ``FileField``, such as controlling database storage and
750 retrieval, can remain unchanged, leaving subclasses to deal with the challenge
751 of supporting a particular type of file.
752
753 Django provides a ``File`` class, which is used as a proxy to the file's
754 contents and operations. This can be subclassed to customize how the file is
755 accessed, and what methods are available. It lives at
756 ``django.db.models.fields.files``, and its default behavior is explained in the
757 :doc:`file documentation </ref/files/file>`.
758
759 Once a subclass of ``File`` is created, the new ``FileField`` subclass must be
760 told to use it. To do so, assign the new ``File`` subclass to the special
761 ``attr_class`` attribute of the ``FileField`` subclass.
762
763 A few suggestions
764 -----------------
765
766 In addition to the above details, there are a few guidelines which can greatly
767 improve the efficiency and readability of the field's code.
768
769 #. The source for Django's own ``ImageField`` (in
770 :source:`django/db/models/fields/files.py`) is a great example of how to
771 subclass ``FileField`` to support a particular type of file, as it
772 incorporates all of the techniques described above.
773
774 #. Cache file attributes wherever possible. Since files may be stored in
775 remote storage systems, retrieving them may cost extra time, or even
776 money, that isn't always necessary. Once a file is retrieved to obtain
777 some data about its content, cache as much of that data as possible to
778 reduce the number of times the file must be retrieved on subsequent
779 calls for that information.