| 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. |