Referência de campos do Model¶
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
.
Opções dos campos¶
O seguintes argumentos estão disponíveis para todos os tipos de campos. Todos são opcionais.
null
¶
-
Field.
null
¶
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.
blank
¶
-
Field.
blank
¶
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.
choices
¶
-
Field.
choices
¶
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.
db_column
¶
-
Field.
db_column
¶
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.
db_index
¶
-
Field.
db_index
¶
Se``True``, djadmin:django-admin.py sqlindexes <sqlindexes> irá gerar uma
declaração CREATE INDEX
para esse campo.
db_tablespace
¶
-
Field.
db_tablespace
¶
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.
default
¶
-
Field.
default
¶
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.
editable
¶
-
Field.
editable
¶
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
.
help_text
¶
-
Field.
help_text
¶
“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.
primary_key
¶
-
Field.
primary_key
¶
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.
unique
¶
-
Field.
unique
¶
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
.
unique_for_date
¶
-
Field.
unique_for_date
¶
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.
unique_for_month
¶
-
Field.
unique_for_month
¶
Semelhante ao unique_for_date
, mas requer que o campo seja único
com respeito ao mês.
verbose_name
¶
-
Field.
verbose_name
¶
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.
Tipos de campos¶
AutoField
¶
-
class
AutoField
(**options)¶
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.
BooleanField
¶
-
class
BooleanField
(**options)¶
Um campo Verdadeiro/Falso.
O site administrativo representa-o como uma checkbox.
MySQL users..
Um campo booleano é armazenado no MySQL como uma coluna TINYINT
com o
valor sendo 0 ou 1 (a maioria dos bancos de dados possuem a propriedade do
tipo BOOLEAN
ao invés). Então, para o MySQL, somente, quando um
BooleanField
é recebido de um banco de dados e armazenado em um atributo
de model, ele terá os valores 1 ou 0, ao invés de True
ou False
.
Normalmente, isto não deveria ser um problema, desde que o Python garanta
que o 1 == True
e 0 == False
sejam ambos veradeiros.
Somente tenha cuidado se você estiver escrevendo algo como obj is True
quando obj
é um valor vindo de um atributo booleano de um model. Se esse
model foi construído usando o backend mysql
, o teste “is
” falhará.
Dê preferencia para um teste de igualdade (usando “==
”) em casos como
este.
CharField
¶
-
class
CharField
(max_length=None[, **options])¶
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:
-
CharField.
max_length
¶ 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.
CommaSeparatedIntegerField
¶
-
class
CommaSeparatedIntegerField
(max_length=None[, **options])¶
Um campo de inteiros separados por vírgulas. Como no :class`CharField`, o
argumento max_length
é obrigatório e atente para as
portabilidades mencionadas.
DateField
¶
-
class
DateField
([auto_now=False, auto_now_add=False, **options])¶
Uma data, representada por uma instância datetime.date
do Python. Tem alguns
poucos argumentos extra, opcionais:
-
DateField.
auto_now
¶ 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.
-
DateField.
auto_now_add
¶ 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.
DateTimeField
¶
-
class
DateTimeField
([auto_now=False, auto_now_add=False, **options])¶
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.
DecimalField
¶
-
class
DecimalField
(max_digits=None, decimal_places=None[, **options])¶
Um número decimal de precisão fixa, representado no Python por uma instância de
Decimal
. Possui dois argumentos obrigatórios:
-
DecimalField.
max_digits
¶ O número máximo de dígitos permitidos no número.
-
DecimalField.
decimal_places
¶ 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).
EmailField
¶
-
class
EmailField
([max_length=75, **options])¶
Um CharField
que verifica se o valor é um e-mail válido.
FileField
¶
-
class
FileField
(upload_to=None[, max_length=100, **options])¶
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:
-
FileField.
upload_to
¶ Um caminho no seu sistema de arquivos local que será adicionado a sua configuração
MEDIA_ROOT
para determinar o valor do atributourl
.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:
-
FileField.
storage
¶ -
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:
- No seu arquivo de configurações, você precisa definir
MEDIA_ROOT
como o caminho completo para o diretório onde você gostaria que o Django guardasse os arquivos enviados. (Por questões de performance, esses arquivos não são guardados no banco de dados). Defina oMEDIA_URL
como a URL pública desse diretório. Assegure-se de que esse diretório tenha permissão de escrita pela conta do usuário que executa o servidor web. - Adiciona o
FileField
ouImageField
ao seu modelo, definindo a opçãoupload_to
para dizer ao Django para qual subdiretório doMEDIA_ROOT
ele deve enviar os arquivos. - Tudo o que será gravado no seu banco de dados é o caminho para o arquivo
(relativo ao
MEDIA_ROOT
). Você muito provavalmente usará a funçãourl
fornecida pelo Django. Por exemplo, se seuImageField
é chamado demug_shot
, você pode obter a URL absoluta para sua imagem em um template com{{ object.get_mug_shot.url }}
.
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.
max_length
foi adicionado nesta versão.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
.
FilePathField
¶
-
class
FilePathField
(path=None[, match=None, recursive=False, max_length=100, **options])¶
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:
-
FilePathField.
path
¶ 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"
.
-
FilePathField.
match
¶ 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 chamadofoo23.txt
mas nãobar.txt
oufoo23.gif
.
-
FilePathField.
recursive
¶ Opcional.
True
ou``False``. O padrão éFalse
. Especifica se todos os subdiretórios dopath
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
).
max_length
foi adicionado nesta versão.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
.
FloatField
¶
-
class
FloatField
([**options])¶
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).
ImageField
¶
-
class
ImageField
(upload_to=None[, height_field=None, width_field=None, max_length=100, **options])¶
Semelhante ao FileField
, mas verifica se o objeto enviado é uma imagem
válida. Tem dois argumentos extras opcionais:
-
ImageField.
height_field
¶ 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.
-
ImageField.
width_field
¶ 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
.
IntegerField
¶
-
class
IntegerField
([**options])¶
Um inteiro. A administração representa-o como um <input type="text">
(um
input de uma única linha).
IPAddressField
¶
-
class
IPAddressField
([**options])¶
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).
NullBooleanField
¶
-
class
NullBooleanField
([**options])¶
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”.
PositiveIntegerField
¶
-
class
PositiveIntegerField
([**options])¶
Como um IntegerField
, mas deve ser positivo.
PositiveSmallIntegerField
¶
-
class
PositiveSmallIntegerField
([**options])¶
Como um PositiveIntegerField
, mas somente permite valores até um certo
ponto (de acordo com o tipo de banco de dados utilizado).
SlugField
¶
-
class
SlugField
([max_length=50, **options])¶
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
.
SmallIntegerField
¶
-
class
SmallIntegerField
([**options])¶
Como um IntegerField
, mas somente permite valores até um certo
ponto (dependendo do banco de dados).
TextField
¶
-
class
TextField
([**options])¶
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.
TimeField
¶
-
class
TimeField
([auto_now=False, auto_now_add=False, **options])¶
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.
URLField
¶
-
class
URLField
([verify_exists=True, max_length=200, **options])¶
Um CharField
para uma URL. Possui um argumento extra opicional:
-
URLField.
verify_exists
¶ 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.