Nosso objeto de exemplo¶

Criar campos personalizados requer um pouco de atenção. Para que seja mais fácil de acompanhar, usaremos um exemplo consistente através desta documentação: um objeto Python que represente a coleção de cartas de uma mão de Bridge. Não se preocupe, não é necessário saber como jogar Bridge para entender o exemplo. É necessário saber que 52 cartas são distribuídas igualmente para 4 jogadores, os quais são tradicionalmente chamados north (norte), east (leste), south (sul) and west (oeste). Nossa classe se parece com isso:

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

Isto é uma classe Python ordinária, com nada específico voltado ao Django. Nós gostamos de poder fazer coisas como essa em nossos modelos ( assumimos que o atributo hand no modelo é um instância de Hand):

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

new_hand = Hand(north, east, south, west)
example.hand = new_hand
example.save()

Atribuimos ou lemos o valor do atributo hand no nosso modelo como em qualquer outra classe Python. Este truque é para dizer ao Django como manipular a gravação e a leitura como um objeto.

Para utilizar a classe Hand em nossos modelos, nós não precisamos alterar essa classe em nada. Isso é ideal, porque quer dizer que podemos facilmente escrever modelos de suporte para classes existentes cujo o código fonte não pode ser alterado.

Armazenamento no Banco de Dados.¶

Vamos começar com campos de modelo. Se você decompô-lo, um campo de modelo fornece uma maneira de pegar um objeto Python normal – string, boolean, datetime ou algo mais complexo como Hand – e convertê-lo de e para um formato que é útil quando se lida com o banco de dados. (Esse formato também é útil para serialização, mas como veremos mais adiante, isso é mais fácil quando você tem o lado do banco de dados sob controle).

Campos em um modelo devem ser de alguma maneira convertidos para que se encaixem em um tipo de coluna de banco de dados já existente. Bancos de dados diferentes provêem diferentes tipos de colunas, mas a regra ainda é a mesma: aqueles são os únicos dados que se tem para trabalhar. Qualquer coisa que se queira guardar em um banco de dados deve se encaixar em um daqueles tipos.

Normalmente, você está escrevendo um campo Django para corresponder a um determinado tipo de coluna de banco de dados ou precisará de uma maneira de converter seus dados em, digamos, uma string.

Para nosso exemplo de Mão, poderíamos converter os dados do cartão em uma string de 104 caracteres concatenando todos os cartões juntos em uma ordem predeterminada – digamos, todos os cartões do norte primeiro, depois o leste, * sul* e oeste. Assim, os objetos Mão podem ser salvos em colunas de texto ou caracteres no banco de dados.

O que uma classe campo faz?¶

Todos os campos do Django (e quando dizemos campo neste documento, sempre queremos dizer campos do modelo e não campos de forms) são subclasses de django.db.models.Field. A maioria das informações que o Django registra sobre um campo é comum a todos os campos –name, help text, uniqueness e por diante. Armazenar toda essa informação é papel de Field. Iremos entrar em detalhes precisos do que o Field pode fazer mais tarde; por agora, basta dizer que tudo descende de Field e então customizamos partes chaves do comportamento da classe.

É importante dizer que a classe de campo do Django não é o que é armazenado no seus atributos do modelo. Os atributos dos modelos contém objetos Python normais. As classes de campo que são definidas em um modelo são na verdade armazenadas dentro da classe Meta quando a classe é criada (os detalhes precisos de como isso é feito são importantes aqui). Isso é porque as classes de campos não são necessárias enquanto se está modificando atributos. Na verdade, eles fornecem o maquinário para conversão entre o valor do atributo e o que é armazenado no banco de dados ou enviado para o serializador.

Tenha isso em mente ao criar seus próprios campos. A subclasse Field do Django que você escreve provê o maquinário para conversão entre suas instancias Python e os valores do banco de dados/serializador de várias maneiras (existe uma diferença entre armazenar um valor e usar um valor para lookups por exemplo). Se isso lhe soa um pouco confuso, não se preocupe – se tornará claro no exemplo abaixo. Mas lembre que muitas vezes acabará por criar duas classes quando quiser um campo personalizado:

• A primeira classe é o objeto Python que os usuários irão manipular. Irão assinalar isso a um atributo de model, lerão para mostrar, coisas assim. Esta é a classe Hand em nosso exemplo.
• A segunda classe é a subclasse Field. Essa é a classe que sabe como converter sua classe entre sua forma de armazenamento permanente e a forma do Python e vice-versa.

A descontrução do Campo¶

O contraponto para escrever seu método __init__() é escrever o método deconstruct(). É usado durante model migrations ` para dizer ao Django como pegar uma instância de seu novo campo e reduzi-lo a um formato serializado – em particular, quais argumentos passar para “__init__()` para recriá-lo.

Se não foram adicionadas opções extras ao campo que foi herdado, então não há necessidade de reescrever o método deconstruct(). Por outro lado, se você mudar os argumentos passados no __init__() (como em HandField), será preciso complementar os argumentos sendo passados.

deconstruct() retorna uma tupla de quatro itens: o nome do atributo do campo, o caminho de importação completo da classe do campo, os argumentos posicionais (como uma lista) e os argumentos da palavra-chave (como um dict). Note que isso é diferente do método deconstruct() :ref:`para classes customizadas ` que retorna uma tupla de três coisas.

Como autor do campo customizado, não é necessário se preocupar sobre os dois primeiros valores; a classe Field básica tem todo o código para o atributo “name” e “import path” funcionar. Entretanto, devemos nos preocupar com o argumentos posicionais e os nomeados, já que estes são as alterações que fizemos

Por exemplo, na nossa classe “HandField” sempre somos forçados a definir max_length em ” __init __ () “. O método “deconstruct()” da classe base “Field” ierá tentar retornar os argumentos da palavra-chave; assim, podemos lançar a partir dos argumentos palavras-chaves para facilitar a leitura

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

Se você adicionar um novo argumento chave, você vai precisar escrever código em deconstruct() que põe o valor dentro de kwargs você mesmo. Você deveria também omitir o valor de kwargs quando ele não é necessário para reconstruir o estado do campo, como quando se usa o valor padrão:

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

Exemplos mais complexos estão além do escopo deste documento, mas lembre – para qualquer configuração da sua instância de Field, o deconstruct() tem que retornar argumentos que se possa passar para o __init__ para reconstruir aquele estado.

Preste atenção extra se foram definidos novos valores padrão para argumentos na superclasse do Field, tem que ter certeza de que estes são sempre incluídos, ao invés de desaparecer se recebem o valor antigo.

Além disso, evite retornar valores como argumentos posicionais; sempre que possível, retorne valores como argumentos de palavra-chave para máxima compatibilidade futura. Se você alterar os nomes das coisas com mais frequência do que sua posição na lista de argumentos do construtor, talvez prefira posicional, mas tenha em mente que as pessoas estarão reconstruindo seu campo a partir da versão serializada por um bom tempo (possivelmente anos), dependendo de quanto tempo suas migrações vivem.

Você pode ver os resultados da desconstrução observando as migrações que incluem o campo e pode testar a desconstrução em testes de unidade desconstruindo e reconstruindo o campo:

name, path, args, kwargs = my_field_instance.deconstruct()
new_instance = MyField(*args, **kwargs)
self.assertEqual(my_field_instance.some_attribute, new_instance.some_attribute)

Atributos de campo que não afetam a definição da coluna do banco de dados¶

Você pode substituir Field.non_db_attrs para personalizar os atributos de um campo que não afetam a definição de uma coluna. É usado durante as migrações do modelo para detectar operações AlterField no-op.

Por exemplo:

class CommaSepField(models.Field):
    @property
    def non_db_attrs(self):
        return super().non_db_attrs + ("separator",)

Alterando a classe básica de um campo personalizado¶

Você não pode alterar a classe base de um campo personalizado porque o Django não irá detectar a mudança, e não irá fazer uma migração para ele. Por exemplo, se você começar com:

class CustomCharField(models.CharField):
    ...

e decidir que quer usar um TextFeld no lugar, você não pode mudar a classe base como estea aqui:

class CustomCharField(models.TextField):
    ...

Ao invés, você deve criar uma nova classe de campo personalizado e atualizar seu modelo para referenciá-la.

class CustomCharField(models.CharField):
    ...


class CustomTextField(models.TextField):
    ...

Como discutido em removendo campos, você deve manter a classe CustomCharField original enquanto tiver migrações que façam referência a ela.

Documentando o seu campo customizado¶

Como sempre, você deve documentar seu tipo de campo, para que os usuários saibam o que é. Além de fornecer uma docstring para ele, que é útil para desenvolvedores, você também pode permitir que os usuários do aplicativo admin vejam uma breve descrição do tipo de campo por meio do aplicativo django.contrib.admindocs `. Para fazer isso, forneça um texto descritivo em um atributo de classe :attr:`~Field.description de seu campo personalizado. No exemplo acima, a descrição exibida pelo aplicativo admindocs para um HandField será ‘Uma mão de cartas (estilo bridge)’.

No display do django.contrib.admindocs, a descrição do campo é interpolada com field.__dict__ o qual habilita a descrição incorporar argumentos do campo. Por exemplo, a descrição para CharField é:

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

Métodos úteis¶

Uma vez criada a subclasse de Field, você deve considerar sobrescrever um poucos métodos, dependendo do comportamento do seu campo. A lista de métodos abaixo está mais ou menos em uma ordem decrescente de importância, então comece do topo.

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.vendor == "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)

Alguns avisos gerais¶

Escrever um um campo personalizado pode ser um um pouco complicado, particularmente se estiver fazendo conversões complexas entre tipos Python e o banco de dados e formatos de serialização. Aqui algumas dicas par fazer as coisas mais tranquilas.

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. Coloque o método __str__() na classe que você está utilizando para envelopar o campo. Em vários lugares o comportamento padrão do código do campo é chamar str(). (Em nossos exemplos neste documento, value seria uma instância de Hand e não de HandField). Então se o método __str__() da sua classe converter o objeto para o formato de texto, você poderá poupar bastante trabalho.

Algumas sugestões¶

Além dos detalhes acima, tem algumas orientações as quais podem melhorar muito a eficiência e a legibilidade do código do campo.

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. Faça o cache dos atributos do arquivo sempre que possível. Uma vez que é possível que arquivos sejam armazenados em sistemas de armazenamento remotos, recuperá-los talvez requeira tempo extra, ou mesmo dinheiro, que não é sempre necessário. Uma vez que o arquivo é recuperado para obter alguns dados sobre seu conteúdo, faça o cache de dados o quanto possível para reduzir o número de vezes que o arquivo deve ser recuperado em chamadas subsequentes para aquela informação.