Este documento contém todos os detalhes sobre todas as opções dos campos e tipos de campos que o Django oferece.
See also
Se os campos embutidos não atendem a sua necessidade, você pode facilmente escrever seus próprios campos de model.
Note
Tecnicamente, estes models são definidos em django.db.models.fields, mas por conveniência eles são importados dentro do django.db.models; a convenção padrão é usar from django.db import models e referir-se aos campos como models.<Foo>Field.
O seguintes argumentos estão disponíveis para todos os tipos de campos. Todos são opcionais.
Se True, o Django irá gravar valores vazios como NULL no banco de dados. O padrão é False.
Repare que strings vazias sempre serão gravadas como strings vazias, não como NULL. Use o null=True apenas para campos que não sejam texto, como inteiros, booleanos e datas. Para ambos os tipos de campos, você irá precisar configurar o blank=True se você quer permitir valores vazios nos formulários, como o parâmetro null afeta somente o banco de dados (veja blank, abaixo).
Evite o uso de null em campos de texto, como CharField e TextField a menos que você tenha uma ótima razão. Se um campo baseado em texto tem null=True, isso significa que ele tem dois valores possíveis para “sem dados”: NULL, e a string vazia. Na maioria dos casos, é redundante ter dois valores possíveis para “sem dados;” a convenção do Django é usar a string vazia, não NULL.
Note
Ao usar o Oracle como backend, a opção null=True será convertida para campos de texto que podem ser vazios, e o valor NULL será gravado para indicar a string vazia.
Se True, o campo pode ser vazio. o padrão é False.
Note que isso é diferente de null. null é puramente relacionado ao banco de dados, e blank é relacionado com validação. Se um campo tem blank=True, a validação na administração do Django irá permitir a entrada de um valor vazio. Se um campo tem blank=False, o campo será obrigatório.
Um iterável(e.g., uma lista ou tupla) de tupla duplas para usar como escolhas para esse campo.
Se fornecido, a administração do Django irá usar uma caixa de seleção no lugar de um campo de texto padrão e irá limitar as escolhas as opções dadas.
Uma lista de opções parece com isto:
YEAR_IN_SCHOOL_CHOICES = (
('FR', 'Freshman'),
('SO', 'Sophomore'),
('JR', 'Junior'),
('SR', 'Senior'),
('GR', 'Graduate'),
)
O primeiro elemeno de cada tupla é o verdadeiro valor a ser gravado. O segundo elemento é o nome legível por humanos para essa opção.
A lista de escolhas pode ser definida como uma parte de sua classe de modelo:
class Foo(models.Model):
GENDER_CHOICES = (
('M', 'Male'),
('F', 'Female'),
)
gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
ou fora da sua classe de modelo:
GENDER_CHOICES = (
('M', 'Male'),
('F', 'Female'),
)
class Foo(models.Model):
gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
Você pode também coletar suas escolhas disponíveis em grupos nomeados que podem ser usados com o proposito de organização:
MEDIA_CHOICES = (
('Audio', (
('vinyl', 'Vinyl'),
('cd', 'CD'),
)
),
('Video', (
('vhs', 'VHS Tape'),
('dvd', 'DVD'),
)
),
('unknown', 'Unknown'),
)
O primeiro elemento em cada tupla é o nome a ser aplicado no grupo. O segundo elemento é um iterável de tuplas duplas, com cada tupla dupla contendo um valor e um nome, legível para humanos, para uma opção. Opções agrupadas podem ser combinadas com opções não agrupadas em uma única lista (como a opção unknown deste exemplo).
Para cada campo de modelo que tem o choices configurado, o Django adicionará um método para obter o valor legível para o valor atual do campo. Veja get_FOO_display() na documentação da API de banco de dados.
Finalmente, veja que as opções podem ser qualquer objeto iterável -- não necessariamente uma lista ou tupla. Isso permite qu evocê construa suas opções dinamicamente. Mas se você se pegar hackeando o choices para ser dinâmico, você provavelmente deveria estar usando uma tabela do banco de dados com uma ForeignKey. choices deve ser usados para dados que não mudem muito, ou que não mudem nunca.
O nome da coluna do banco de dados a ser usada com esse campo. Se não for informada, o Django irá usar o nome do campo.
Se o nome da sua coluna no banco de dados é uma palavra chave SQL reservada, ou contém caracteres que não são permitidos em nomes de variáveis no Python -- notadamente, o hífen tudo bem. O Django escapa os nomes de colunas e tabelas por trás dos panos.
Se``True``, djadmin:django-admin.py sqlindexes <sqlindexes> irá gerar uma declaração CREATE INDEX para esse campo.
O nome do tablespace no banco de dados a ser usado para esse o índice desse campo, se esse campo é indexado. O padrão é a configuração DEFAULT_INDEX_TABLESPACE do projeto, se configurado, ou o db_tablespace do modelo, se houver. Se o backend não suporta tablespaces, essa opção é ignorada.
O valor padrão para o campo. Pode ser também um objeto chamável. Se for um chamável, será chamado a cada vez que um novo objeto for criado.
Se False, o campo não será editável na administração ou por formulários gerados automaticamente a partir de models. O padrão é True.
"Ajuda" extra a ser exibida subre o campo na administração de formulários do objeto. É útil para documentação, mesmo que seu objeto não tenha um formulário administrativo.
Note que esse valor não é escapado pelo processamento de HTML ao ser exibido na interface administrativa. Isso permite que você inclua HTML no help_text se você desejar. Por exemplo:
help_text="Por favor use o seguinte formato: <em>DD/MM/YYYY</em>."
Como alternativa você pode utilizar texto plano e django.utils.html.escape() para escapar quaisquer caracter especial do HTML.
Se True, esse campo será a chave primária para o modelo.
Se você não especificar primary_key=True para nenhum campo no seu modelo, o Django irá adicionar automaticamente um IntegerField para ser a chave primária, então você não precisa setar primary_key=True sobre algum de seus campos, a menos que você queira sobrescrever o comportamento de chave primária padrão. Para mais, veja Campos de chave primária automáticos.
primary_key=True implica em blank=False, null=False <Field.null>` e unique=True. Somente uma chave primária é permitida por objeto.
Se True, esse campo deve ser único na tabela.
Isso é garantido no banco de dedos e no formulário de administração do Django. Se você tentar salvar um modelo com um valor duplicado em um campo unique, uma exceção django.db.IntegrityError será lançada pelo método save() do modelo.
Esta opção é válida para todos os tipos de campos exceto :class:ManyToManyField` e FileField.
Configure isso para o nome de um campo DateField ou DateTimeField para exigir que esse campo seja único para o valor da data.
Por exemplo, se você tem um campo title que tem unique_for_date="pub_date", o Django não irá permitir a criação de dois registros com o mesmo title e pub_date.
Isso é reforçado no nível do formulário de administração do Django, mas não no banco de dados.
Semelhante ao unique_for_date, mas requer que o campo seja único com respeito ao mês.
Um nome, legível para humanos, para o campo. Se o nome prolíxo não for dado, o Django criará um automaticamente, usando o nome do campo, convertendo os underscores em espaços. Veja Nomes de campos por extenso.
Um IntegerField que incrementa seu valor automaticamente de acordo com os IDs disponíveis. Você normalmente não precisa usá-lo diretamente; um campo de chave primária será automaticamente adicionado ao seu modelo se você não especificar um. Veja Campos de chave primária automáticos.
Um campo Verdadeiro/Falso.
O site administrativo representa-o como uma checkbox.
Um campo string, para campos texto de tamanhos pequeno e médio.
Para grandes quantidades de texto, use django.db.models.TextField.
A administração representa-o como um <input type="text"> (um input de uma única linha).
CharField tem um argumento extra obrigatório:
O tamanho máximo (em caracteres) do campo. O max_length é verificado a nível de banco de dados e na validação do Django.
Note
Se você estiver escrevendo uma aplicação que deve ser portável para vários backends de banco de dados, você deve estar alerta, pois há restrições para o max_length em alguns backends. Leia as notas sobre backend de bancos de dados.
MySQL users
Se você estiver usando este campo com MySQLdb 1.2.2 e a colação utf8_bin (que não é a padrão), há alguns problemas que deve ter em mente. Leia as notas do banco de dados MySQL para detalhes.
Um campo de inteiros separados por vírgulas. Como no :class`CharField`, o argumento max_length é obrigatório e atente para as portabilidades mencionadas.
Uma data, representada por uma instância datetime.date do Python. Tem alguns poucos argumentos extra, opcionais:
Configura o campo automaticamente para a hora em que o objeto é salvo. Útil para campos de hora da "última modificação". Note que sempre é usada a data atual, não é apenas um valor padrão que você pode sobrescrever.
Configura automaticamente o campo para a data em que ele foi primeiramente criado. Útil para a criação de carimbos de data. Note que sempre é usada a data atual, não é apenas um valir padrão que você pode sobrescrever.
A administração representa isso como um <input type="text"> com um calendário JavaScript, e um atalho para "Hoje." O calendário JavaScript sempre irá iniciar a semana no Domingo.
A date and time, represented in Python by a datetime.datetime instance. Um campo de data e hora. Tem as mesmas opções extras de DateField.
A administração representa esse campo como dois campos <input type="text">, com atalhos JavaScript.
Um número decimal de precisão fixa, representado no Python por uma instância de Decimal. Possui dois argumentos obrigatórios:
O número máximo de dígitos permitidos no número.
O número de casas decimais para salvar com o número.
Por exemplo, para gravar números até 999 com uma precisão de 2 casas decimais, você deve usar:
models.DecimalField(..., max_digits=5, decimal_places=2)
E para guardar números de até aproximadamente um bilhão, com uma precisão de 10 casas decimais:
models.DecimalField(..., max_digits=19, decimal_places=10)
A administração representa isso como um <input type="text"> (um input de uma única linha).
Um CharField que verifica se o valor é um e-mail válido.
Um campo para upload de arquivo. Possui um argumento obrigatório
Note
O argumentos primary_key e unique não são suportados, e lançarão um TypeError se usados.
Has one required argument:
Um caminho no seu sistema de arquivos local que será adicionado a sua configuração MEDIA_ROOT para determinar o valor do atributo url.
Esse caminho pode conter formatação strftime, que será substituído pela data/hora do upload do arquivo (para que os arquivos enviados não encham o diretório fornecido).
Este pode também ser um chamável, como uma função, que será chamada para obter o caminho do upload, incluíndo o nome do arquivo. Este chamável deve ser preparado para receber dois argumentos, e retornar um caminho no estilo Unix (com barras) para serem passados ao longo do sistema de armazenamento. Os dois argumentos que serão passados são:
| Argumento | Descrição |
|---|---|
| instance | Uma instância do model onde o FileField é definido. Mais especificamente, esta é a instância particular onde o arquivo atual está atachado. Na maioria dos casos, este objeto não terá sido salvo no banco de dados ainda, então se ele usa o padrão AutoField, ele pode não ter ainda um valor para seu campo de chave primária. |
| filename | O nome que foi originalmente dado para o arquivo. Este pode ou não pode ser levado em conta durante a definição do caminho de destino final. |
Também há um argumento opcional:
Opcional. Um objeto storage, que manipula o armazenamento e recebimento de seus arquivos. Veja Gerenciando arquivos para mais detalhes de como prover este objeto.
A administração representa esse campo como um <input type="file"> (um widget de upload de arquivo).
O uso de um FileField ou um ImageField (veja abaixo) em um modelo requer alguns passos adicionais:
Por exemplo, digamos que o seu MEDIA_ROOT esteja configurado para '/home/media', e o upload_to está configurado para 'photos/%Y/%m/%d'. A parte '%Y/%m/%d' do upload_to é a formatação strftime; '%Y' é o ano com quatro digítos, '%m' é o mês com dois dígitos e '%d' é o dia com dois dígitos. Se você enviar um arquivo em 15 de janeiro de 2007, ele será salvo no diretório /home/media/photos/2007/01/15.
Se você quer obter o nome do arquivo no disco, ou a URL que se refere àquele arquivo, ou o tamanho do arquivo, você pode usar os métodos name, url e size. Veja Gerenciando arquivos.
Observe que independente da forma que você lida com arquivos enviados, você deve prestar muita atennção para onde você os está enviado e para quais tipos eles são, para evitar furos de segurança. Valide todos os arquivos enviados para assegurar-se que eles são o que você pensa que eles são. Por exemplo, se você permite que alguém envie arquivos sem validação, para um diretório que esteja dentro do document root do seu servidor web, então alguém poderia enviar um script CGI ou PHP e executar esse script visitando essa URL em seu site URL. Não permita isso.
Por padrão, instâncias de FileField são criadas como colunas varchar(100) no seu banco de dados. Assim como nos outros campos, você pode mudar o tamanho máximo usando o argumento max_length.
Um campo CharField cujas escolhas são limitadas a nomes de arquivos em um certo diretório no sistema de arquivos. Tem três argumentos especiais, sendo o primeiro obrigatório:
Obrigatório. O caminho absoluto para um diretório no sistema de arquivos a partir de onde o FilePathField deve obter suas opções. Exemplo: "/home/images".
Opcional. Uma expressão regular, como uma string, que o FilePathField usará para filtrar os nomes dos arquivos. Perceba que a regex será aplicada apenas ao nome do aruqivo, não ao caminho completo. Exemplo: "foo.*\.txt$", que irá casar um arquivo chamado foo23.txt mas não bar.txt ou foo23.gif.
Opcional. True ou``False``. O padrão é False. Especifica se todos os subdiretórios do path devem ser incluídos.
E é claro que todos esses argumentos podem ser usados juntos.
A única pegadinha em potencial é que o match aplica-se ao nome básico do arquivo, não ao caminho completo. Assim, esse exemplo:
FilePathField(path="/home/images", match="foo.*", recursive=True)
...irá casar /home/images/foo.gif mas não /home/images/foo/bar.gif porque o argumento match aplicase aos nomes básicos dos arquivos (foo.gif e bar.gif).
Por padrão, instâncias de FilePathField são criadas como colunas varchar(100) no seu banco de dados. Assim como nos outros campos, você pode mudar o tamanho máximo usando o argumento max_length.
Um número de ponto flutuante, representado no Python como uma instância de um float.
A administração representa-o como um <input type="text"> (um input de uma única linha).
Semelhante ao FileField, mas verifica se o objeto enviado é uma imagem válida. Tem dois argumentos extras opcionais:
Nome de um campo de model que será auto-populado com a altura da imagem toda vez que a instância do model for salva.
Nome de um campo de model que será auto-populado com a largura da imagem toda vez que a instância do model for salva.
Além dos métodos especiais que estão disponíveis para FileField, um class:ImageField também tem os atributos File.height e File.width. Veja Gerenciando arquivos.
Requer a Python Imaging Library.
Por padrão, instâncias de ImageField são criadas como colunas varchar(100) no seu banco de dados. Assim como nos outros campos, você pode mudar o tamanho máximo usando o argumento max_length.
Um inteiro. A administração representa-o como um <input type="text"> (um input de uma única linha).
Um endereço IP, em formato texto (ex: "192.0.2.30"). A administração representa-o como um <input type="text"> (um input de uma única linha).
Como um BooleanField, mas permite NULL como uma das opções. Use-o no lugar de um BooleanField com null=True. A administração representa-o como uma caixa <select> com as escolhas "Unknown", "Yes" e "No".
Como um IntegerField, mas deve ser positivo.
Como um PositiveIntegerField, mas somente permite valores até um certo ponto (de acordo com o tipo de banco de dados utilizado).
Slug é um termo jornalístico. Um slug é um apelido curto para algo, contendo somente letras, números, underscores ou hífens. Eles normalmente são usados em URLs.
Semelhantemente ao CharField, você pode especificar o max_length (leia a nota sobre portabilidade de banco de dados e max_length nesta seção também). Se o max_length não for especificado, o Django irá usar um tamanho padrão de 50.
Implica em Field.db_index.
É muitas vezes mais útil para pre-popular automaticamente um campo baseado no no seu valor. Você pode fazer isso automaticamente no admin usando prepopulated_fields.
Como um IntegerField, mas somente permite valores até um certo ponto (dependendo do banco de dados).
Um campo de texto longo. A administração o representa como uma <textarea> (um input de múltiplas linhas).
MySQL users
Se você estiver usando este campo com MySQLdb 1.2.1p2 e a colação utf8_bin (que não é a padrão), há alguns problemas que deve ter em mente. Leia as notas do banco de dados MySQL para detalhes.
Uma hora. Representado em Python por uma instância datetime.time. Aceita as mesmas opções de auto preenchimento dos campos DateField.
A administração o representa como uma <input type="text"> com alguns atalhos JavaScript.
Um CharField para uma URL. Possui um argumento extra opicional:
Se a opção for True (padrão), a existência da URL será verificada (i.e., será verificado se a URL carrega e não retorna uma reposta 404). It should be noted that when using the single-threaded development server, validating a url being serverd by the same server will hang. This should not be a problem for multithreaded servers.
A administração representa-o como um <input type="text"> (um input de uma única linha).
Como toda subclasse de CharField, URLField recebe um argumento opcional, max_length. Se você não especificar o max_length, o padrão de 200 é usado.
Dec 26, 2011