カスタムのモデルフィールド

db_type(self)

DATABASE_ENGINE 設定に指定されているデータベースで、フィールドのデータ を保存するために使うカラム型を返します。

例えば、 PostgreSQL 固有のカスタム型 mytype を作成したとしましょう。 Django からこの型を使うには、以下のように Field をサブクラス化して、 db_type() メソッドを実装します:

from django.db import models

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

MytypeField を定義したら、他のフィールド型と同じようにモデルで利用でき ます:

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

データベースに依存しないアプリケーションを構築したいなら、データベース毎 のカラム型の違いに注意しておかねばなりません。例えば、 PostgreSQL では日付 や時間に関するカラム型は timestamp 型ですが、 MySQL では datetime 型です。この違いを db_type() メソッドの中で吸収するには、Djangoの settings モジュールを import しておいて、以下のように DATABASE_ENGINE 設定をチェックします:

class MyDateField(models.Field):
    def db_type(self):
        from django.conf import settings
        if settings.DATABASE_ENGINE == 'mysql':
            return 'datetime'
        else:
            return 'timestamp'

db_type() メソッドは、Django がアプリケーションのテーブルを生成するため の CREATE TABLE` 文を構築する瞬間、すなわち最初にテーブルを生成する瞬 間しか呼び出されません。それ以外の場合に呼び出されることはないので、上記の DATABASE_ENGINE をチェックする例のような多少ややこしいコードを書いても さして問題ではありません。

カラムのデータ型にはパラメタを取るものがあります。例えば CHAR(25) は、 25 がカラムの最大長を表しています。こうした場合には、 db_type() メ ソッド内でハードコードしておくよりも、モデル内でパラメタを指定して使えるよ うになっていた方が柔軟性を高められます。例えば、以下に示すような CharMaxlength25Field はあまり便利ではありません:

# パラメタをハードコードしているおバカな例
class CharMaxlength25Field(models.Field):
    def db_type(self):
        return 'char(25)'

# モデル内での使い方
class MyModel(models.Model):
    # ...
    my_field = CharMaxlength25Field()

実行時、すなわちフィールドクラスをインスタンス化する時にパラメタを指定でき た方がよいでしょう。パラメタを指定できるようにするには、以下のように __init__() を実装します:

# より柔軟性のある例
class BetterCharField(models.Field):
    def __init__(self, maxlength, *args, **kwargs):
        self.max_length = max_length
        super(BetterCharField, self).__init__(*args, **kwargs)

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

# モデル内での使い方
class MyModel(models.Model):
    # ...
    my_field = BetterCharField(25)

最後に、カラムの操作に非常に複雑な SQL が必要な場合には、 db_type() に None を返させましょう。そうすれば、 Django の SQL 生成コードはこのフィー ルドの処理をスキップします。もちろん、その場合には、何らかの方法で正しいテー ブルに正しいカラムを生成する必要があります。

to_python(self, value)

データベース (またはシリアライザ) の返す値を Python オブジェクトに変換しま す。

デフォルトの実装では、単に value を返します。通常は、データベースバック エンドは正しい形式 (Python 文字列型など) でデータを返すからです。

カスタムのフィールドクラスで、文字列や日時、整数や浮動小数点型といったデー タ型よりも複雑なデータ構造を扱いたい場合、このメソッドをオーバライドする必 要があります。一般的な規則として、このメソッドは以下の引数をきちんと扱えね ばなりません:

• 正しい型のインスタンス (このドキュメントの例では Hand オブジェク ト)
• 文字列 (デシリアライザなどが返す値)
• このフィールドのカラムタイプに対して、データベースバックエンドが返す 値

HandField クラスでは、データを VARCHAR フィールドで保存しているので、 to_python() は文字列と Hand インスタンスの両方を扱えねばなりません:

import re

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

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

        # The string case.
        p1 = re.compile('.{26}')
        p2 = re.compile('..')
        args = [p2.findall(x) for x in p1.findall(value)]
        return Hand(*args)

このメソッドは常に Hand インスタンスを返していることに注意してください。 to_python() は、モデルの属性値として保存したい Python オブジェクト型を 返します。

忘れないで！: カスタムフィールドに対して to_python() が呼び出される ようにしたければ、上で述べた SubfieldBase メタクラス を使わねばなりませ ん。メタクラスを使わないと、 to_python() は自動的に呼び出されません。

get_db_prep_save(self, value)

to_python() の逆のメソッドで、データベースバックエンドを扱うときに呼び出 されます。 value パラメタは、モデルの現在の属性値です (このような設計に なっているのは、個々のフィールドが、自身を組み込んでいるモデルに対する参照 を持っていないため、フィールドが自分でモデルインスタンスから値を取り出せな いからです)。 このメソッドは、データベースバックエンドのクエリパラメタとし て使えるようにデータをフォーマットして返さねばなりません。

例を示します:

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

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

pre_save(self, model_instance, add)

このメソッドは、 get_db_prep_save() の直前に呼び出され、 このフィールドの model_instance での適切な値を生成して返さねばなりませ ん。属性の名前は self.attrname で参照できます (この値はフィールドのイ ンスタンス化時に設定されます)。モデルインスタンスをデータベースに初めて保存 しようとしている場合、 add パラメタの値は True です。それ以外の値は False です。

このメソッドをオーバライドする必要があるのは、フィールドの値を、保存の直前 に前処理したい場合だけです。例えば、 Django の DateTimeField は、 auto_now や auto_now_add で生成された場合、このメソッドを使って 正しい値をセットします。

このメソッドをオーバライドする場合、最後に属性の値を返さねばなりません。 また、フィールドの値を変更した場合、モデル上の対応する値も更新して、モデル インスタンスを参照しているコードが正しい値を読み出せるようにせねばなりませ ん。

get_db_prep_lookup(self, lookup_type, value)

データベース上で照合を行う時 (WHERE 制約付きで SQL を発行する時) に データベースに渡す値を前処理しまうｓ。 lookup_type は、 Django のフィル タ照合条件である exact, iexact, contains, icontains, gt, gte, lt, lte, in, startswith, istartswith, endswith, iendswith, range, year, month, day, isnull, search, regex, iregex のいずれかの値を取ります。

このメソッドをオーバライドする場合、 lookup_type に指定される全ての照合 条件に対応せねばなりません。また、 value が正しい値でない場合 (単一の オブジェクトが指定されるべきところにリストが指定された場合など) には ValueError を、フィールドが指定した照合に対応していない場合には TypeError を送出せねばなりません。たいていのフィールドでは、特別な扱い の必要な照合タイプだけを処理して、残りは親クラスの get_db_prep_lookup() メソッドに委ねればよいでしょう。

get_db_prep_save() を定義するようなケースでは、おそらく get_db_prep_lookup() も定義する必要があります。また、このメソッドを 定義するたいていの理由は range や in による検索の実現です。 こうした場合には、引数としてオブジェクトのリストを受け取り、データベースに 渡せる何らかの適切な型のオブジェクトからなるリストに変換せねばなりません。 get_db_prep_save() を使い回したり、別のメソッドに共通の処理を括り出し ておくと便利です。

例を示します:

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

    def get_db_prep_lookup(self, lookup_type, value):
        # 'exact' および 'in' だけを扱います。それ以外はエラーにします。
        if lookup_type == 'exact':
            return self.get_db_prep_save(value)
        elif lookup_type == 'in':
            return [self.get_db_prep_save(v) for v in value]
        else:
            raise TypeError('Lookup type %r not supported.' % lookup_type)

formfield(self, form_class=forms.CharField, **kwargs)

このフィールドをモデルに組み込んで、フォームで表示したときに使うデフォルト のフォームフィールドを返します。このメソッドは、 form_for_model() や form_for_instance() といった ヘルパ関数 から呼び出されます。

kwargs 辞書の内容は、全てフォームフィールドの __init__() メソッドに 渡されます。通常、このメソッドの定義では、適切な form_class 引数のデフォ ルト値を設定して、それ以降の処理を親クラスに移譲しているだけです。フォーム フィールドを定義する場合、カスタムのフォームフィールド (や、フォームウィジェッ ト) を書く必要があるかもしれません。カスタムのフォームフィールドについては forms のドキュメント を参照してください。また、カスタムウィジェットは django.contrib.localflavor のコードを参照するとよいでしょう。

これまでの例に合わせて書くと、 formfield() メソッドは以下のように書けま す:

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

    def formfield(self, **kwargs):
        # メソッドの呼び出し側がデフォルトをオーバライド
        # できるようにするための標準的な書き方
        defaults = {'form_class': MyFormField}
        defaults.update(kwargs)
        return super(HandField, self).formfield(**defaults)

上の例では、 MyFormField フィールドクラスを import しているのが前提です (そして、 MyFormField でデフォルトのウィジェットを定義しています)。カス タムのフォームフィールドの定義方法は、このドキュメントでは扱いません。

get_internal_type(self)

データベースレベルでエミュレーションしているフィールド型の名前を返すメソッ ドです。このメソッドは、簡単な方法でフィールド型を定義する際に、データベー スのカラム型を決定するために使われます。

db_type() メソッドを定義していれば、 get_internal_type() を気にする 必要はありません。このメソッドは、ほとんど使われません。ただし、フィールド 型のデータベースストレージが、他のフィールドと同じような型である場合、この メソッドを定義しておくと、他のフィールドのロジックを使ってカラムを生成させ られます。

例を示します:

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

    def get_internal_type(self):
        return 'CharField'

どのデータベースバックエンドを使っているかに関わらず、上のように定義してお くと、 syncdb などの SQL 関係のコマンドを実行した時に、文字列を保存す るための正しいカラム型を生成します。

get_internal_type() が、 Django 上でもデータベースバックエンドでも対応 しない型を示す文字列を返した場合、すなわち、 django.db.backends.<db_name>.creation.DATA_TYPES に存在しない文字列を返 した場合、シリアライザはこの文字列を使いますが、デフォルトの db_type() 実装は None を返します。なぜこのような挙動が有用なのかは、 前述の db_type() のドキュメントを読んでください。シリアライザに、フィールドの 型名として文字列を指定しておくと、 Django の外の何らかの場面でシリアライザ の出力を扱うときに便利だからです。

flatten_data(self, follow, obj=None)

フィールドの属性名をデータに対応付ける辞書を返します。データはフラット化さ れた文字列で表現されています。このメソッドは、ここではあまり重要でない、内 部で使うためのものです (ほとんどはマニピュレータ関係です)。 さしあたって、属性名を文字列に対応付けている 1 要素の辞書を返すだけで十分で す。

このメソッドは、シリアライザがフィールドの値を出力する際に文字列に変換する ために使います。シライアライズ処理時は、 Field._get_val_from_obj(obj) を呼び出して値を取り出すのがよいのですが、パラメタは無視してもかまいません。

例えば、 HandField はデータストレージに文字列を使っているので、既存の変 換コードを再利用できます:

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

    def flatten_data(self, follow, obj=None):
        value = self._get_val_from_obj(obj)
        return {self.attname: self.get_db_prep_save(value)}