Eigener Datenbank-Typ¶

db_type(self)¶

Gibt den Spaltentyp für das Field zurück -- abhängig von der derzeit gewählten DATABASE_ENGINE.

Gehen wir einmal davon aus, dass du in PostgreSQL einen Typ mit dem Name mytype erstellt hast. Du kannst diesen Typ nun in deiner Field-Unterklasse verwenden, indem du db_type() wie folgt implementierst:

from django.db import models

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

Sobald du nun dein MytypeField hast, kannst du es in einem Modell nun wie jedes andere Feld verwenden:

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

Wenn deine Applikation nicht nur auf ein Datenbanksystem beschränkt sein soll, musst du unterschiedliche Spaltentypen in Betracht ziehen. So ist zum Beispiel der Spaltentype für Datums- und Zeitangaben in PostgreSQL timestamp, während der Typ in MySQL datetime heißt. Innerhalb von db_type() kann der Typ dann entsprechend der in der Settings-Datei gesetzten DATABASE_ENGINE festgesetzt werden. Das könnte dann zum Beispiel so aussehen:

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() wird nur dann Aufgerufen, wenn Django die CREATE TABLE-Statements für deine Applikation zusammenstellt , also wenn du zum ersten Mal die Tabellen erstellst. Da es nur zu diesem Zeitpunkt ausgeführt, kann es auch durchaus komplexeren Code, wie zum Beispiel die Unterscheidung nach DATABASE_ENGINE wie im oberen Beispiel enthalten.

Einige Spalten Typen erlauben auch Parameter, wie zum Beispiel CHAR(25), wobei 25 die maximale Spaltenbreite festlegt. In einer solchen Situation ist es deutlich flexibler, wenn der Parameter durch das Modell festgelegt wird, anstelle eines fixen Wertes in der db_type()-Methode. So würde ein CharMaxlength25Field nur wenig Sinn machen:

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

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

Eine bessere Lösung wäre hier, wenn der Wert zur Laufzeit festgelegt werden könnte -- also wenn die Klasse instanziiert wird. Um das zu erreichen, implementiere django.db.models.Field.__init__() wie folgt:

# Das ist eine deutlich flexiblere Loesung:
class BetterCharField(models.Field):
    def __init__(self, max_length, *args, **kwargs):
        self.max_length = max_length
        super(BetterCharField, self).__init__(*args, **kwargs)

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

# Im Modell:
class MyModel(models.Model):
    # ...
    my_field = BetterCharField(25)

Wenn deine Spalte ein sehr komplexes SQL-Setup benötigt, schreibe db_type() so, dass es None zurückgibt. Damit überspringt Django diese Spalte während der Erstellung der Tabelle. Du musst dann irgendwie anders diese Spalte anlegen, jedoch erreicht du so, dass Django dir nicht in die Quere kommt.

Datenbankwerte in Python-Objekte umwandeln¶

to_python(self, value)¶

Wandelt einen Wert aus der Datenbank (oder dem Serializer) in ein Python-Objekt um.

In der Regel gibt bereits das Datenbank-Backend den Wert im korrekten Format zurück, folglich gibt die Standardimplementierung einfach value zurück.

Wenn deine Field-Klasse mit Datenstrukturen arbeitet, die komplexer als Strings, Daten und Zahlen sind, dann musst du diese Methode überschreiben. Die Methode sollte hierbei mit folgenden Werten umgehen können:

• Eine Instanz des korrekten Typs (zum Beispiel Hand in unserem Beispiel)
• Ein String (zum Beispiel aus dem Deserializer)
• Was auch immer die Datenbank für Spaltentyp zurückgibt, den du verwendest

In unserer HandField-Klasse speichern wir die Daten in einem VARCHAR-Feld in der Datenbank. Folglich muss die to_python()-Methode sowohl Strings als auch mit Hand-Instanzen verarbeiten können:

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)

Bitte beachte, dass wir immer hier immer eine Hand-Instanz zurückgeben. Das ist der Python-Objekttyp, den wir in unserem Modellattribut speichern möchten.

Nicht vergessen: Wenn dein Feld davon abhängt, dass to_python() aufgerufen wird, wenn es erstellt wird, dann solltest du die Die SubfieldBase-Metaklasse verwenden, die weiter oben beschrieben wurde. Ansonsten wird to_python() nicht automatisch aufgerufen.

Python-Objekte in Datenbankwerte umwandeln¶

get_db_prep_value(self, value)¶

Die Methode hat genau die gegenteilige Aufgabe von to_python(), wenn man mit Datenbank-Backends anstelle von reiner Serialisierung arbeitet. Der value-Parameter ist der aktuelle Wert des Attributs im Modell (ein Feld hat keinerlei Verbindung zum Modell, das es enthält, weshalb es den Wert nicht selbst vom Modell beziehen kann) und die Methode soll die Daten nun in einem Format zurückgeben, das für die Verwendung in Queries an das Datenbank-Backend geeignet ist.

Zum Beispiel:

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

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

get_db_prep_save(self, value)¶

... erfüllt die gleiche Aufgabe, wird jedoch dann aufgerufen, wenn der Feldwert in die Datenbank gespeichert werden soll. Da die Standardimplementierung lediglich get_db_pre_value aufruft, solltest du in der Regel diese Methode nicht implementieren müssen, ausser wenn dein Feld in einer besonderen Art und Weise konvertiert werden muss, bevor es gespeichert werden kann und dann nicht mehr dem Wert entspricht, der als normaler Query-Parameter verwendet werden kann (was der Implementierung von get_db_prep_value entspricht).

Werte vor dem Speichern bearbeiten¶

pre_save(self, model_instance, add)¶

Diese Methode wird kurz vor get_db_prep_save() aufgerufen und sollte den des entsprechenden Attributs von model_instance für dieses Feld zurückgeben. Der Name des Attributes ist (dank Field) in self.attname gespeichert. Wenn das Modell zum ersten Mal in die Datenbank gespeichert wird, ist der add-Parameter True, ansonsten False.

Du musst diese Methode nur dann überschreiben, wenn du den Wert irgendwie modifizieren willst, bevor er gespeichert wird. So verwendet zum Beispiel Djangos DateTimeField diese Methode, um den Wert des Attributs entsprechend anzupassen, wenn die Parameter auto_now oder auto_now_add gesetzt sind.

Wenn du nun diese Methode überschreibst, musst du den Wert des Attributes zurückgeben. Du solltest ausserdem das Attribut im Modell aktualisieren, wenn du den Wert änderst, damit Referenzen auf dieses Modell immer den korrekten Wert sehen.

Werte für Datenbankabfragen vorbereiten¶

get_db_prep_lookup(self, lookup_type, value)¶

Bereitet den value für seine Rolle als Abfrage-Parameter auf die Datenbank vor (eine WHERE-Klausel in SQL). Der lookup_type ist einer der folgenden Abfrage-Filter in Django: exact, iexact, contains, icontains, gt, gte, lt, lte, in, startswith, istartswith, endswith, iendswith, range, year, month, day, isnull, search, regex, und iregex.

Deine Methode muss mit all diesen lookup_type-Werten umgehen können und sollte entweder einen ValueError werfen, wenn der value zum Beispiel eine Liste ist, wenn du ein normales Objekt erwartet hast, oder einen TypeError, wenn dein Feld einen bestimmten Abfragetyp nicht unterstützt. Meistens kannst du auch einfach nur die Methode für eine kleine Anzahl an Abfragetypen implementieren, die irgendwie eine besondere Behandlung benötigen, und alle anderen von get_db_prep_lookup() der Elternklasse verarbeiten lassen.

Wenn du get_db_prep_save() hast implementieren müssen, dann brauchst du wahrscheinlich auch get_db_prep_lookup(). Wenn du diese Methode nicht implementierst, wird get_db_prep_value von der Standardimplementierung aufgerufen, um exact-, gt-, gte-, lt-, lte-, in- und range-Abfragen zu verarbeiten.

Du kannst mit dieser Methode auch die Anzahl der verschiedenen Abfragetypen einschränken, die mit deinem Feldtyp verwendet werden können.

Bei range und in-Anfragen erhält get_db_prep_lookup eine Liste von Objekten (wahrscheinlich mit dem korrekten Typ) und muss diese Liste dann in eine Liste von Werten mit dem richtigen Typ umwandeln, um sie dann der Datenbank zu übergeben. Meistens kannst du hier get_db_prep_value() wieder verwenden, ganz oder in Teilen.

Im folgenden Beispiel wird get_db_prep_lookup implementiert, um nur exact und in zuzulassen:

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

    def get_db_prep_lookup(self, lookup_type, value):
        # We only handle 'exact' and 'in'. All others are errors.
        if lookup_type == 'exact':
            return [self.get_db_prep_value(value)]
        elif lookup_type == 'in':
            return [self.get_db_prep_value(v) for v in value]
        else:
            raise TypeError('Lookup type %r not supported.' % lookup_type)

Formularfeld und Modellfeld verbinden¶

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

Gibt das Formularfeld zurück, das standardmässig für dieses Modellfeld verwendet werden soll, wenn es angezeigt wird. Diese Methode wird von ModelForm aufgerufen.

Das gesamte kwargs-Dictionary wird direkt an die Field__init__()-Methode des Formularfelds übergeben. Somit musst du normalerweise einfach einen guten Standardwert für das form_class setzen und dann alles weitere der Elternklasse überlassen. Das heißt aber auch, dass du vielleicht dein eigenes Formularfeld schreiben wirst müssen (und auch vermutlich ein Formular-Widget). Mehr Information darüber findest du in der Formular-Dokumentation. Für Widget-Beispiele wirf auch einen Blick auf den Code von django.contrib.localflavor.

In unserem Beispiel können wir die formfield()-Methode so schreiben:

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(HandField, self).formfield(**defaults)

Das setzt voraus, dass wir eine MyFormField-Feldklasse importiert haben, welche ihr eigenes Standard-Widget hat. Dieses Dokument behandelt nicht das Schreiben eigener Formularfelder

Eingebaute Feldtypen nachahmen¶

get_internal_type(self)¶

Gibt den Namen derjenigen Field-Subklasse zurück, die wir auf der Datenbankschicht nachahmen wollen. Das wird genutzt, um einfach den Spaltentyp in einfachen Fällen zu ermitteln.

Wenn du bereits eine db_type()-Methode geschrieben hast, brauchst du dich nicht weiter um get_internal_type() zu kümmern, da es nicht weiter verwendet wird. Wenn dein Feld aber auf der Datenbank-Ebene einem anderen bereits existierenden Feld sehr ähnlich ist, kannst du somit einfach die Funktionalität dieses Anderen Feldes für die Erstellung des richtigen Spaltentyps verwenden.

Zum Beispiel:

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

    def get_internal_type(self):
        return 'CharField'

Ganz egal, welches Datenbank-Backend wir nun benutzen, bedeutet das, das syncdb und andere SQL-Befehle den richtigen Spaltentyp für einen String erstellen werden.

Wenn get_internal_type() nun einen String zurückgibt, der Django für das gerade verwendete Datenbank-Backend unbekannt ist -- als der String nicht in django.db.backends.<db_name>.creation.DATA_TYPES aufscheint --, wird der String trotzdem für den Serializer verwendet werden, jedoch gibt db_type() None zurück. Warum das nützlich ist, wird in der Dokumentation zu db_type() erklärt. Es ist hier normalerweise ratsam, einen sprechenden String als Typ des Feldes für den Serializer anzugeben; speziell wenn du die Ausgabe des Serializers auch ausserhalb von Django verwendest.

Felddaten für die Serialisierung konvertieren¶

value_to_string(self, obj)¶

Diese Methode wird von den Serializern verwendet, um das Feld in einen String umzuwandeln, der dann ausgegeben werden kann. Field._get_val_from_obj(obj)() aufzurufen ist hierbei der Beste Weg, um den Wert für die Serialisierung zu bekommen. Da unser HandField zum Beispiel ohnehin bereits Strings als Datenspeicher verwendet, können wird ein bisschen Wiederverwertung betreiben:

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

    def value_to_string(self, obj):
        value = self._get_val_from_obj(obj)
        return self.get_db_prep_value(value)