A documentação referência de modelo explica como usar as classes de campo padrão do Django –CharField, DateField, etc. Para muitos propósitos, essas classes são tudo o que você irá precisar. Às vezes, porém, a versão do Django não irá atender às suas necessidades específicas, ou você irá querer usar um campo que é totalmente diferente daqueles fornecidos com Django.
Os tipos de campos embutidos no Django não cobrem todas os possíveis tipos de colunas do banco de dados – somente os tipos comuns, tais como VARCHAR``e ``INTEGER. Para tipos de colunas mais obscuros, tal como polígonos geográficos ou ainda tipos criados pelo usuário como `PostgreSQL custom Types`__, é possível definir sua própria subclasse de Field do Django.
Por outro lado, pode haver um tipo complexo de objeto no Python que pode de alguma maneira ser serializado para que se encaixe em um tipo de coluna padrão no banco de dados. Este é um outro caso onde uma subclasse de Field pode ajudar a utilizar o objeto com o “models”.
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:
\nclass Hand:\n """A hand of cards (bridge style)"""\n\n def __init__(self, north, east, south, west):\n # Input parameters are lists of cards ('Ah', '9s', etc.)\n self.north = north\n self.east = east\n self.south = south\n self.west = west\n\n # ... (other possibly useful methods omitted) ...\nIsto é 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)\nprint(example.hand.north)\n\nnew_hand = Hand(north, east, south, west)\nexample.hand = new_hand\nexample.save()\nAtribuimos 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.
Let’s start with model fields. If you break it down, a model field provides a\nway to take a normal Python object – string, boolean, datetime, or\nsomething more complex like Hand – and convert it to and from a format\nthat is useful when dealing with the database. (Such a format is also useful\nfor serialization, but as we’ll see later, that is easier once you have the\ndatabase side under control).
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.
\nNormally, you’re either writing a Django field to match a particular database\ncolumn type, or you will need a way to convert your data to, say, a string.
\nFor our Hand example, we could convert the card data to a string of 104\ncharacters by concatenating all the cards together in a predetermined order –\nsay, all the north cards first, then the east, south and west cards. So\nHand objects can be saved to text or character columns in the database.
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.
Quando estiver panejando sua subclasse de Field, primeiro de uma com qual classe já existente Field seu campo se parece mais. É possível fazer uma subclasse de campo Django já existente e economizar algum trabalho ? Caso não, você deve construir uma subclasse de Field, da qual tudo descende.
Iniciar seu novo campo é uma questão de separar quaisquer argumentos que são específicos para seu caso dos argumentos comuns e passar este último para o método __init__() da Field (ou sua classe pai).
No nosso exemplo, iremos chamar nosso campo de HandField. (é uma boa idéia chamar sua subclasse Field <AgumaCoisa>Field, então ela fica facilmente identificável como uma subclasse de Field) . Nosso campo não se comporta como nenhum outro campo existente, então iremos herdar diretamente de Field:
from django.db import models\n\nclass HandField(models.Field):\n\n description = "A hand of cards (bridge style)"\n\n def __init__(self, *args, **kwargs):\n kwargs['max_length'] = 104\n super().__init__(*args, **kwargs)\nNosso HandField aceita a maioria das opções dos campos padrão (veja a lista abaixo), mas asseguramos que ele tenha um comprimento fixo, já que só precisa de 52 valores de carta mais seus naipes; 104 caracteres no total.
O método Field.__init__() recebe os seguintes parâmetros:
name
rel: Usado para campos relacionados (como ForeignKey). Somente para uso avançado.
serialize: se False, o campo não será “serializado” quando o modelo for passado para os serializadores. Padrão é True.
db_tablespace: Somente para a criação de índice, se o “backend” suportar tablespaces. Normalmente é possível ignorar essa opção.
auto_created: True se o campo foi criado automaticamente, como para o OneToOneField usado pela herança de modelo. Somente para uso avançado.
Todas as opções sem uma explicação na lista acima tem o mesmo significado que os campos normais do Django. veja a field documentation para exemplos e detalhes.
\nThe counterpoint to writing your __init__() method is writing the\ndeconstruct() method. It’s used during model migrations to tell Django how to take an instance of your new field\nand reduce it to a serialized form - in particular, what arguments to pass to\n__init__() to recreate it.
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() returns a tuple of four items: the field’s attribute name,\nthe full import path of the field class, the positional arguments (as a list),\nand the keyword arguments (as a dict). Note this is different from the\ndeconstruct() method for custom classes\nwhich returns a tuple of three things.
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
\nfrom django.db import models\n\nclass HandField(models.Field):\n\n def __init__(self, *args, **kwargs):\n kwargs['max_length'] = 104\n super().__init__(*args, **kwargs)\n\n def deconstruct(self):\n name, path, args, kwargs = super().deconstruct()\n del kwargs["max_length"]\n return name, path, args, kwargs\nSe 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\n\nclass CommaSepField(models.Field):\n "Implements comma-separated storage of lists"\n\n def __init__(self, separator=",", *args, **kwargs):\n self.separator = separator\n super().__init__(*args, **kwargs)\n\n def deconstruct(self):\n name, path, args, kwargs = super().deconstruct()\n # Only include kwarg if it's not the default\n if self.separator != ",":\n kwargs['separator'] = self.separator\n return name, path, args, kwargs\nExemplos 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.
In addition, try to avoid returning values as positional arguments; where\npossible, return values as keyword arguments for maximum future compatibility.\nIf you change the names of things more often than their position in the\nconstructor’s argument list, you might prefer positional, but bear in mind that\npeople will be reconstructing your field from the serialized version for quite\na while (possibly years), depending how long your migrations live for.
\nYou can see the results of deconstruction by looking in migrations that include\nthe field, and you can test deconstruction in unit tests by deconstructing and\nreconstructing the field:
\nname, path, args, kwargs = my_field_instance.deconstruct()\nnew_instance = MyField(*args, **kwargs)\nself.assertEqual(my_field_instance.some_attribute, new_instance.some_attribute)\nYou can override Field.non_db_attrs to customize attributes of a field that\ndon’t affect a column definition. It’s used during model migrations to detect\nno-op AlterField operations.
Por exemplo:
\nclass CommaSepField(models.Field):\n\n @property\n def non_db_attrs(self):\n return super().non_db_attrs + ("separator",)\nVocê 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:
\nclass CustomCharField(models.CharField):\n ...\ne decidir que quer usar um TextFeld no lugar, você não pode mudar a classe base como estea aqui:
class CustomCharField(models.TextField):\n ...\nAo invés, você deve criar uma nova classe de campo personalizado e atualizar seu modelo para referenciá-la.
\nclass CustomCharField(models.CharField):\n ...\n\nclass CustomTextField(models.TextField):\n ...\nComo discutido em removendo campos, você deve manter a classe CustomCharField original enquanto tiver migrações que façam referência a ela.
As always, you should document your field type, so users will know what it is.\nIn addition to providing a docstring for it, which is useful for developers,\nyou can also allow users of the admin app to see a short description of the\nfield type via the django.contrib.admindocs application. To do this provide descriptive\ntext in a description class attribute of your custom field. In\nthe above example, the description displayed by the admindocs application\nfor a HandField will be ‘A hand of cards (bridge style)’.
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)")\nUma 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.
Vamos dizer que você tenha criado um tipo personalizado para o PostgreSQL chamado mytype. Você pode herdar de Field e implementar o método db_type(), como a:
from django.db import models\n\nclass MytypeField(models.Field):\n def db_type(self, connection):\n return 'mytype'\nUma vez que tenha MyTypeField, pode usá-lo em qualquer modelo, tal como qualquer outro tipo Field:
class Person(models.Model):\n name = models.CharField(max_length=80)\n something_else = MytypeField()\nIf you aim to build a database-agnostic application, you should account for\ndifferences in database column types. For example, the date/time column type\nin PostgreSQL is called timestamp, while the same column in MySQL is called\ndatetime. You can handle this in a db_type() method by\nchecking the connection.vendor attribute. Current built-in vendor names\nare: sqlite, postgresql, mysql, and oracle.
Por exemplo:
\nclass MyDateField(models.Field):\n def db_type(self, connection):\n if connection.vendor == 'mysql':\n return 'datetime'\n else:\n return 'timestamp'\nOs métodos db_type() e rel_db_type() são chamados pelo Django quando o framework constrói comandos CREATE TABLE para a sua aplicação – isto é, quando você cria as tabelas pela primeira vez. Os métodos também são chamados quando constróem cláusulas WHERE que incluem um campo de modelo – isto é, quando você retorna dados usando métodos QuerySet como get(), filter(), e exclude() e tem um campo de modelo como argumento. Eles não são chamados em nenhum outro momento, portanto podem executar códigos complexos, como a verificação connection.settings_dict no exemplo acima.
Alguns tipos de coluna do banco de dados aceitam parâmetros, como CHAR(25), onde o parâmetro 25 representa o tamanho máximo da coluna. Em casos como este, é mais flexível se o parâmetro for especificado no modelo ao invés de ser hard-coded no método db_type(). Por exemplo, não faria muito sentido ter CharMaxlength25Field, mostrado aqui:
# This is a silly example of hard-coded parameters.\nclass CharMaxlength25Field(models.Field):\n def db_type(self, connection):\n return 'char(25)'\n\n# In the model:\nclass MyModel(models.Model):\n # ...\n my_field = CharMaxlength25Field()\nThe better way of doing this would be to make the parameter specifiable at run\ntime – i.e., when the class is instantiated. To do that, implement\nField.__init__(), like so:
# This is a much more flexible example.\nclass BetterCharField(models.Field):\n def __init__(self, max_length, *args, **kwargs):\n self.max_length = max_length\n super().__init__(*args, **kwargs)\n\n def db_type(self, connection):\n return 'char(%s)' % self.max_length\n\n# In the model:\nclass MyModel(models.Model):\n # ...\n my_field = BetterCharField(25)\nFinally, if your column requires truly complex SQL setup, return None from\ndb_type(). This will cause Django’s SQL creation code to skip\nover this field. You are then responsible for creating the column in the right\ntable in some other way, but this gives you a way to tell Django to get out of\nthe way.
O método rel_db_type() é chamado por campos como o ForeignKey e o OneToOneField que apontam para outros campos para determinar o tipo da sua coluna de banco de dados. Por exemplo, se tiver um UnsignedAutoField, você também precisa de chaves estrangeiras que apontam para aquele campo para usar o mesmo tipo de dado:
# MySQL unsigned integer (range 0 to 4294967295).\nclass UnsignedAutoField(models.AutoField):\n def db_type(self, connection):\n return 'integer UNSIGNED AUTO_INCREMENT'\n\n def rel_db_type(self, connection):\n return 'integer UNSIGNED'\nSe sua classe customizada de Field lida com estruturas de dados mais complexas que strings, datas, inteiros, or floats, então talvez precise sobrescrever o from_db_value() e to_python().
Se presente para a subclasse do campo, from_db_value() será chamado em todas as circunstâncias quando dados são lidos do banco de dados, incluindo em agregacões e chamadas do values() .
o to_python() é chamado pela deserialização e durante o método clean() usado nos forms.
Como regra geral, ``to_python()``deve lidar tranquilamente com qualquer dos seguintes argumentos:
\nUma instância do tipo correto (ex., ``Hand``no nosso exemplo corrente).
Uma string
None``(se o campo permitir ``null=True)
In our HandField class, we’re storing the data as a VARCHAR field in\nthe database, so we need to be able to process strings and None in the\nfrom_db_value(). In to_python(), we need to also handle Hand\ninstances:
import re\n\nfrom django.core.exceptions import ValidationError\nfrom django.db import models\nfrom django.utils.translation import gettext_lazy as _\n\ndef parse_hand(hand_string):\n """Takes a string of cards and splits into a full hand."""\n p1 = re.compile('.{26}')\n p2 = re.compile('..')\n args = [p2.findall(x) for x in p1.findall(hand_string)]\n if len(args) != 4:\n raise ValidationError(_("Invalid input for a Hand instance"))\n return Hand(*args)\n\nclass HandField(models.Field):\n # ...\n\n def from_db_value(self, value, expression, connection):\n if value is None:\n return value\n return parse_hand(value)\n\n def to_python(self, value):\n if isinstance(value, Hand):\n return value\n\n if value is None:\n return value\n\n return parse_hand(value)\nPerceba que sempre retornamos uma instância destes métodos. Este é o tipo do objeto Python que queremos armazenar no atributo do modelo.
\nPara to_python(), se qualquer coisa der errado durante a conversão do valor, deve-se gerar a exceção ValidationError.
Since using a database requires conversion in both ways, if you override\nfrom_db_value() you also have to override\nget_prep_value() to convert Python objects back to query values.
Por exemplo:
\nclass HandField(models.Field):\n # ...\n\n def get_prep_value(self, value):\n return ''.join([''.join(l) for l in (value.north,\n value.east, value.south, value.west)])\nAlguns tipos de dados (por exemplo datas) precisam estar em um formato específico antes deles poderem ser usados por um “backend” de banco de dados. O get_db_prep_value() é um método onde estas conversões devem ser feitas. A conexão específica que será usada para a query é passada pelo parâmetro connection. Isso lhe possibilita usar a lógica de conversão espeçifica para um backend se isso for necessário.
Por exemplo, o Django usa o seguinte método para isso BinaryField:
def get_db_prep_value(self, value, connection, prepared=False):\n value = super().get_db_prep_value(value, connection, prepared)\n if value is not None:\n return connection.Database.Binary(value)\n return value\nNo caso do seu campo personalizado precisar de uma conversão especial quando for salvo e isso não é o mesmo que a conversão usada para parâmetros de query, você pode sobrescrever get_db_prep_save().
Caso queira processar o valor logo antes de salvar, pode-se usar pre_save(). Por exemplo, o DateTimeField do Django usa este método para definir o atributo corretamente no caso de auto_now ou auto_now_add.
Caso sobrescreva este método, é necessário retornar o valor do atributo no fim. Deve-se também atualizar o atributo do modelo caso tenham sido feito mudanças no valor, de modo que que o código que mantém as referências ao modelo sempre veja o valor correto.
\nPara personalizar o campo de formulário usado pelo ModelForm, você pode sobrescrever formfield().
A classe do campo de formulário pode ser especificada via o form_class e os argumentos de choices_form_class; o último é especificado se o campo tiver opções (choices) especificadas, do contrário o primeiro. Se estes argumentos não são fornecidos, será usada a CharField ou TypedChoiceField.
Todos os dicionários kwargs é passado diretamente para o método __init__()` do campo do formulário. Normalmente, tudo o que você precisa fazer é definir um bom padrão para o argumento do form_class (e talvez choices_form_class) e delegar futuras manipulações para a classe pai. Isso talvez requeira que seja escrito um campo de form personalizado (e mesmo o widget de formulário). Veja o forms documentation para informações sobre isso.
Continuando nosso exemplo em andamento, podemos escrever o método formfield() como:
class HandField(models.Field):\n # ...\n\n def formfield(self, **kwargs):\n # This is a fairly standard way to set up some defaults\n # while letting the caller override them.\n defaults = {'form_class': MyFormField}\n defaults.update(kwargs)\n return super().formfield(**defaults)\nIsso assume que importamos uma classe de campo MyModelField (o qual tem seu próprio widget padrão). Este documento não cobre os detalhes de escrever um campo de formulário personalizado.
Se você criou um método db_type(), não precisa se preocupar sobre get_internal_type() – isso não será usado muito. As vezes, porém, seu armazenamento no banco de dados é similar em tipo a outro campo, então você pode usar a lógica deste outro campo para criar a coluna correta.
Por exemplo:
\nclass HandField(models.Field):\n # ...\n\n def get_internal_type(self):\n return 'CharField'\nNão importa qual backend de banco de dados que esteja sendo usado, isso quer dizer que o migrate e outros comandos SQL criam o tipo de coluna correto para armazenar uma string.
Se o get_internal_type() retorna uma string que não é conhecida para o Django para o backend de banco de dados que está sendo usado – que é, ele não aparece no django.db.backends.<db_name>.base.DatabaseWrapper.data_types – a string ainda será usada pelo serializador, mas o método padrão db_type() retornará None. Veja a documentação do db_type() pelas razões pelas quais este talvez seja útil.
Para personalizar como os valores são serializados por um serializador, você pode sobrescrever :meth:’~Field.value_to_string’. Utilizando :meth:’~Field.value_from_object’ é a melhor forma para obter o valor dos campos antes da serialização. Por exemplo, visto que “HandField” utiliza strings para armazenar dados, nós podemos reutilizar algum código de conversão existente:
\nclass HandField(models.Field):\n # ...\n\n def value_to_string(self, obj):\n value = self.value_from_object(obj)\n return self.get_prep_value(value)\nEscrever 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.
\nOlhe para os campos existentes no Django (em django/db/models/fields/__init__.py) para inspação. Tente encontrar um campo que seja similar ao o que você quer extender um pouco, ao invés de criar um inteiramente novo desde o início.
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.
FileFieldLink para este cabeçalho#Além dos métodos acima, campos que lidam com arquivos tem alguns outros requerimentos especiais que devem ser levados em conta. A maioria dos mecanismos fornecidos pelo ``FileField`, como controlar o armazenamento e leitura na base de dados, podem permanecer inalterados, deixando as subclasses lidarem com o desafio de dar suporte a um tipo de arquivo particular.
\nO Django fornece uma classe File, a qual é usada como um proxy para conteúdos e operações de arquivos . Isso pode ser herdado para customizar como o arquivo é acessado, e quais métodos estão disponíveis. Isso está em django.db.models.fields.files, e seu comportamento padrão é explicado no arquivo documentação.
Once a subclass of File is created, the new FileField subclass must be\ntold to use it. To do so, assign the new File subclass to the special\nattr_class attribute of the FileField subclass.
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.
\nO código fonte para o ImageField do Django (em django/db/models/fields/files.py) é um bom exemplo de como herdar FileField para dar suporte ao um tipo de arquivo em particular, já que ele incorpora todas as técnicas descritas acima.
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.