Django2.0手册:编写自定义 model fields

我们的示例对象¶

Creating custom fields requires a bit of attention to detail. To make things
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.
Don’t worry, you don’t have to know how to play Bridge to follow this example.
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:

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

    def __init__(self, north, east, south, west):
        # Input parameters are lists of cards ('Ah', '9s', etc.)
        self.north = north
        self.east = east
        self.south = south
        self.west = west

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

This is just an ordinary Python class, with nothing Django-specific about it.
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):

example = MyModel.objects.get(pk=1)
print(example.hand.north)

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
loading such an object.

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.

数据库存储¶

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
with. Anything you want to store in the database must fit into one of
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
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.

一个 field 类做了什么?¶

All of Django’s fields (and when we say fields in this document, we always
mean model fields and not form fields) are subclasses
of django.db.models.Field. Most of the information that Django records
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.

It’s important to realize that a Django field class is not what is stored in
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
database or sent to the serializer.

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

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

Field deconstruction¶

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

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

The contract of deconstruct() is simple; it returns a tuple of four items:
the field’s attribute name, the full import path of the field class, the
positional arguments (as a list), and the keyword arguments (as a dict). Note
this is different from the deconstruct() method for custom classes which returns a tuple of three things.

As a custom field author, you don’t need to care about the first two values;
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
max_length in __init__(). The deconstruct() method on the base Field
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().__init__(*args, **kwargs)

    def deconstruct(self):
        name, path, args, kwargs = super().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):
        self.separator = separator
        super().__init__(*args, **kwargs)

    def deconstruct(self):
        name, path, args, kwargs = super().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 –
for any configuration of your Field instance, deconstruct() must return
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
possible, return values as keyword arguments for maximum future compatibility.
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)

Changing a custom field’s base class¶

You can’t change the base class of a custom field because Django won’t detect
the change and make a migration for it. For example, if you start with:

class CustomCharField(models.CharField):
    ...

and then decide that you want to use TextField instead, you can’t change
the subclass like this:

class CustomCharField(models.TextField):
    ...

Instead, you must create a new custom field class and update your models to
reference it:

class CustomCharField(models.CharField):
    ...

class CustomTextField(models.TextField):
    ...

As discussed in removing fields, you
must retain the original CustomCharField class as long as you have
migrations that reference it.

Documenting your custom field¶

As always, you should document your field type, so users will know what it is.
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
field type via the django.contrib.admindocs application. To do this simply provide
descriptive text in a description class attribute of your custom
field. In the above example, the description displayed by the admindocs
application for a HandField will be ‘A hand of cards (bridge style)’.

In the 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
CharField is:

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

Useful methods¶

Once you’ve created your 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.

from django.db import models

class MytypeField(models.Field):
    def db_type(self, connection):
        return 'mytype'

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

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

# This is a silly example of hard-coded parameters.
class CharMaxlength25Field(models.Field):
    def db_type(self, connection):
        return 'char(25)'

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

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

    def db_type(self, connection):
        return 'char(%s)' % self.max_length

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

# 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'

import re

from django.core.exceptions import ValidationError
from django.db import models
from django.utils.translation import gettext_lazy as _

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)

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

    def from_db_value(self, value, expression, connection):
        if value is None:
            return value
        return parse_hand(value)

    def to_python(self, value):
        if isinstance(value, Hand):
            return value

        if value is None:
            return value

        return parse_hand(value)

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

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

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

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

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

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

    def get_internal_type(self):
        return 'CharField'

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

    def value_to_string(self, obj):
        value = self.value_from_object(obj)
        return self.get_prep_value(value)

Some general advice¶

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:

1. Look at the existing Django fields (in
   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.
2. Put a __str__() method on the class you’re wrapping up as a field. There
   are a lot of places where the default behavior of the field code is to call
   str() on the value. (In our examples in this document, value would
   be a Hand instance, not a HandField). So if your __str__()
   method automatically converts to the string form of your Python object, you
   can save yourself a lot of work.

一些建议¶

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

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.