Um modelo é um único e definitiva fonte de dados sobre os seus dados, Ele contém os campos e comportamentos essenciais dos dados que você está armazenando. Em geral, cada modelo mapeia para uam única tabela no seu banco de dados.
\nO básico
\nCada modelo é uma classe Python que herda django.db.models.Model.
Cada atributo de um modelo representa um campo no banco de dados.
Com tudo isso, Django lhe dá uma API de acesso ao banco de dados gerada automaticamente; veja Fazendo consultas.
Neste exemplo o modelo define um Person, o qual tem um first_name``e ``last_name:
from django.db import models\n\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=30)\n last_name = models.CharField(max_length=30)\nfirst_name e last_name são “fields” do modelo. Cada campo é especificado como um atributo de classe, e cada atributo mapeia uma coluna do banco de dados.
O modelo Person criaria uma tabela de banco de dados como esta:
CREATE TABLE myapp_person (\n "id" bigint NOT NULL PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,\n "first_name" varchar(30) NOT NULL,\n "last_name" varchar(30) NOT NULL\n);\nAlgumas notas técnicas:
\nO nome da tabela, myapp_person, é automaticamente derivado de alguns metadados do modelo mas pode ser sibrescrito. Veja Table names para mais detalhes.
Um campo id é adicionado automaticamente, mas este comportamento pode ser sobrescrito. Veja Campos chave-primária automáticos..
O SQL CREATE TABLE neste exemplo está formatado usando a syntax do PostgreSQL, mas vale a pena notar que o Django usa SQL de acordo com o “backend” do banco de dados especificado no seu arquivo de definições.
Uma vez que tenha definido seus modelos, você precisa dizer ao Django que irá usar aqueles modelos. Faça isso editando seu arquivo de definições e alterando a definição do INSTALLED_APPS para adicionar o nome do módulo que contém seu models.py.
Por exemplo, se o modelo para sua aplicação está em um módulo myapp.models (a estrutura de pacote que foi criada para uma aplicação pelo script manage.py startapp), INSTALLED_APPS deve ser lido, em parte:
INSTALLED_APPS = [\n # ...\n "myapp",\n # ...\n]\nQuando adicionar novas aplicações ao INSTALLED_APPS, tenha certeza de rodar manage.py migrate, opcionalmente antes fazendo migrações para eles antes com manage.py makemigrations.
A parte mais importante de um modelo – e a única parte requerida de um modelo – é a lista de campos de banco de dados que ele define. Campos são especificados através de atributos de classe. Cuidado para não escolher nomes de campos que conflitem com a API dos modelos like clean, save, ou delete.
Exemplo
\nfrom django.db import models\n\n\nclass Musician(models.Model):\n first_name = models.CharField(max_length=50)\n last_name = models.CharField(max_length=50)\n instrument = models.CharField(max_length=100)\n\n\nclass Album(models.Model):\n artist = models.ForeignKey(Musician, on_delete=models.CASCADE)\n name = models.CharField(max_length=100)\n release_date = models.DateField()\n num_stars = models.IntegerField()\nCada campo no seu modelo deve ser instanciado da classe Field apropriada. O Django usa o tipo de classe do campo para determinar algumas coisas:
O tipo da coluna, o qual diz ao banco de dados que tipo de dado irá armazenar (e.g. INTEGER, VARCHAR, TEXT).
O widget HTML padrão para usar quando renderizar o campo de um form (ex. <input type="text">, <select>).
The minimal validation requirements, used in Django’s admin and in\nautomatically-generated forms.
Django vem com dúzias de tipos de campos; você pode achar uma lista nas refrências de campos de modelo. Você pode facilmente escrever seus próprios campos se os que vêm definidos no Django não resolverem; veja Como criar campos de modelo customizado.
\nCada campo recebe um certo conjunto de argumentos específicos (documentados na referência de campos de modelo). Por exemplo, a CharField (e suas subclasses) requerem um argumento max_length o qual especifica o comprimento usado para armazenar dados do campo VARCHAR do banco de dados.
Também há um conjunto de argumentos comuns disponíveis para todos os tipos de campos. Todos opcionais. Estes argumentos são explicados na referência, mas aqui um sumário dos argumentos mais usados:
\nnullSe True, o Django irá usar valores “vazios” como NULL no banco de dados. Padrão is False.
blankSe True, é permitido o campo estar em “branco”. O padrão é False.
Note que isso é diferente de null. null é puramente relacionado ao banco de dados, enquanto que o blank é relacionado a validação. Se um campo tiver blank=True, a validação do “form” permitirá entrada de ym valor vazio. Se o campo tiver blank=False, o campo será requerido.
choicesA sequence of 2-value tuples, a mapping, an\nenumeration type, or a callable (that\nexpects no arguments and returns any of the previous formats), to use as\nchoices for this field. If this is given, the default form widget will be a\nselect box instead of the standard text field and will limit choices to the\nchoices given.
\nUma lista de opções se parece com isso:
\nYEAR_IN_SCHOOL_CHOICES = [\n ("FR", "Freshman"),\n ("SO", "Sophomore"),\n ("JR", "Junior"),\n ("SR", "Senior"),\n ("GR", "Graduate"),\n]\nThe first element in each tuple is the value that will be stored in the\ndatabase. The second element is displayed by the field’s form widget.
\nGiven a model instance, the display value for a field with choices can\nbe accessed using the get_FOO_display()\nmethod. For example:
from django.db import models\n\n\nclass Person(models.Model):\n SHIRT_SIZES = {\n "S": "Small",\n "M": "Medium",\n "L": "Large",\n }\n name = models.CharField(max_length=60)\n shirt_size = models.CharField(max_length=1, choices=SHIRT_SIZES)\n>>> p = Person(name="Fred Flintstone", shirt_size="L")\n>>> p.save()\n>>> p.shirt_size\n'L'\n>>> p.get_shirt_size_display()\n'Large'\nYou can also use enumeration classes to define choices in a concise\nway:
from django.db import models\n\n\nclass Runner(models.Model):\n MedalType = models.TextChoices("MedalType", "GOLD SILVER BRONZE")\n name = models.CharField(max_length=60)\n medal = models.CharField(blank=True, choices=MedalType, max_length=10)\nFurther examples are available in the model field reference.
\ndefaultO valor padrão para o campo. Este pode ser um valor ou um objeto “callable”. Se “callable” ele será chamado cada vez que um novo objeto for criado.
\ndb_defaultThe database-computed default value for the field. This can be a literal\nvalue or a database function.
\nIf both db_default and Field.default are set, default will\ntake precedence when creating instances in Python code. db_default will\nstill be set at the database level and will be used when inserting rows\noutside of the ORM or when adding a new field in a migration.
help_textTexto extra de ajuda para ser mostrado com o “widget” do formulário. É útil para documentar mesmo que seu campo não seja usado em um formulário.
\nprimary_keySe True, este campo será a chave-primária do seu modelo.
If you don’t specify primary_key=True for\nany fields in your model, Django will automatically add a field to hold\nthe primary key, so you don’t need to set\nprimary_key=True on any of your fields\nunless you want to override the default primary-key behavior. For more,\nsee Campos chave-primária automáticos..
O campo chave-primária é somente para leitura. Se você alterar o valor de uma chave-primária em um objeto existente e salvá-lo, um novo objeto será criado além do antigo. Por exemplo:
\nfrom django.db import models\n\n\nclass Fruit(models.Model):\n name = models.CharField(max_length=100, primary_key=True)\n>>> fruit = Fruit.objects.create(name="Apple")\n>>> fruit.name = "Pear"\n>>> fruit.save()\n>>> Fruit.objects.values_list("name", flat=True)\n<QuerySet ['Apple', 'Pear']>\nuniqueSe True, este campo deve ser único dentro da tabela
Novamente, estas são apenas descrições curtas das opções mais comuns dos campos. Detalhes completos podem ser encontrados na ref:referência de opções de campos de modelos comuns <common-model-field-options>.
\nBy default, Django gives each model an auto-incrementing primary key with the\ntype specified per app in AppConfig.default_auto_field or globally in the\nDEFAULT_AUTO_FIELD setting. For example:
id = models.BigAutoField(primary_key=True)\nIf you’d like to specify a custom primary key, specify primary_key=True on one of your fields. If Django sees you’ve explicitly\nset Field.primary_key, it won’t add the automatic id column.
Cada modelo requere exatamente um campo que tenha primary_key=True (declarado explicitamente ou adicionado automaticamente).
Cada tipo de campo, exceto para ForeignKey, ManyToManyField e OneToOneField, recebe um argumento opcional como primeiro argumento – um nome detalhado. Se o nome detalhado não for informado, o Django irá automaticamente criar ele usando o atributo nome do campos, convertendo “underscores” para espaços.
Neste exemplo, o nome detalhada é "person's first name":
first_name = models.CharField("person's first name", max_length=30)\nNeste exemplo, o nome detalhado é "first name":
first_name = models.CharField(max_length=30)\nForeignKey, ManyToManyField and OneToOneField requerem que o primeiro argumento seja uma classe de modelo, então use o argumento nomeado verbose_name:
poll = models.ForeignKey(\n Poll,\n on_delete=models.CASCADE,\n verbose_name="the related poll",\n)\nsites = models.ManyToManyField(Site, verbose_name="list of sites")\nplace = models.OneToOneField(\n Place,\n on_delete=models.CASCADE,\n verbose_name="related place",\n)\nA convenção é não usar caixa-alta na primeira letra do verbose_name. O Django irá automaticamente captalizar a primeira letra quando for necessário.
Claramente, o poder dos bancos de dados relacionais está em relacionar as tabelas entre elas. O Django oferece maneiras de definir os três tipos de relacionamentos mais comuns: muitos-para-muitos, muitos-para-um e um-para-um.
\nPara definir um relacionamento de muitos-para-um, use django.db.models.ForeignKey. Você o usar como qualquer outro tipo de Field: incluindo-o como um atributo do seu modelo.
A ForeignKey requer um argumento posicional: a classe com a qual o modelo está relacionado.
Por exemplo, se um modelo Car tem um fabricante Manufacturer – quer dizer, um Manufacturer faz múltiplos carros mas cada Car somente tem um Manufacturer – use as seguintes definições:
from django.db import models\n\n\nclass Manufacturer(models.Model):\n # ...\n pass\n\n\nclass Car(models.Model):\n manufacturer = models.ForeignKey(Manufacturer, on_delete=models.CASCADE)\n # ...\nVocê também pode criar relacionamentos recursivos (um objeto com relacionamento muitos-para-um comsigo mesmo) e relacionamentos para modelos que ainda não foram definidos; veja a referência para campos de modelo para detalhes.
\nIt’s suggested, but not required, that the name of a\nForeignKey field (manufacturer in the example\nabove) be the name of the model, lowercase. You can call the field whatever you\nwant. For example:
class Car(models.Model):\n company_that_makes_it = models.ForeignKey(\n Manufacturer,\n on_delete=models.CASCADE,\n )\n # ...\nPara definir relacionamentos muitos-para-muitos, use ManyToManyField. Você o usa tal como qualquer outro tipo de Field: incluindo-o como um atributo de classe no seu modelo
O ManyToManyField requer um argumento posicional: a classe com a qual o modelo está relacionado.
Por exemplo, se a Pizza tem muitos objetos Topping – quer dizer, um Topping pode ter em multiplas pizzas e cada Pizza tem muitos recheios – aqui está como você deveria representá-los:
from django.db import models\n\n\nclass Topping(models.Model):\n # ...\n pass\n\n\nclass Pizza(models.Model):\n # ...\n toppings = models.ManyToManyField(Topping)\nTal como ForeignKey, você também pode criar relacionamentos recursivos (um objeto com relacionamento muitos-para-muitos com ele mesmo) e relacionamentos com modelos ainda não definidos.
É sugerido, mas não requerido que o nome de um ManyToManyField (toppings no nosso exemplo acima) seja um plural descrevendo o conjunto dos objetos relacionados do modelo.
Não importa quais dos modelos tem a ManyToManyField, mas você deve colocá-la somente em um dos modelos – não em ambos.
Geralmente, instancias de ManyToManyField devem ir no objeto que serão editados em um formulário. No exemplo acima, toppings está na Pizza (ao invés de Topping ter pizzas como ManyToManyField ) porque é mais natural pensar sobre pizza tendo recheio do que recheios estando em múltiplas pizzas. A maneira com está definido acima, o formulário de Pizza deveria deixar usuários selecionar os recheios.
ManyToManyField os campos também aceitam vários argumentos extras como explicado na referência de campos de modelo. Estas opções ajudam a definir como o relacionamento deve funcionar; todos são opcionais.
When you’re only dealing with many-to-many relationships such as mixing and\nmatching pizzas and toppings, a standard\nManyToManyField is all you need. However, sometimes\nyou may need to associate data with the relationship between two models.
Por exemplo, considere o caso de uma aplicação que rastreia grupos musicais aos quais pertencem músicos. Existe um relacionamento muitos-para-muitos entre pessoas e grupos aos quais eles são membros, então você poderia usar uma ManyToManyField para representar este relacionamento. Porém, existem váriios detalhes sobre este relacionamento que você talvez queria coletar, tal como a data na qual a pessoa se juntou ao grupo.
Para estas situações, o Django permite que você especifique o modelo que será usado para “governar” o relacionamento muitos-para-muitos. Você pode então colocar campos extras no modelo intermediário. O modelo intermediário está associado a ManyToManyField usando o argumento through para apontar para o modelo que atuará como um intermediário. Para nosso exemplo de músicos, o código poderia parecer como algo como:
from django.db import models\n\n\nclass Person(models.Model):\n name = models.CharField(max_length=128)\n\n def __str__(self):\n return self.name\n\n\nclass Group(models.Model):\n name = models.CharField(max_length=128)\n members = models.ManyToManyField(Person, through="Membership")\n\n def __str__(self):\n return self.name\n\n\nclass Membership(models.Model):\n person = models.ForeignKey(Person, on_delete=models.CASCADE)\n group = models.ForeignKey(Group, on_delete=models.CASCADE)\n date_joined = models.DateField()\n invite_reason = models.CharField(max_length=64)\n\n class Meta:\n constraints = [\n models.UniqueConstraint(\n fields=["person", "group"], name="unique_person_group"\n )\n ]\nQuando você define um modelo intermediário, você especifica explicitamente chaves-estrangeiras para os modelos que estão envolvidos no relacionamento muitos-para-muitos. Esta declaração explícita define como os dois modelos estão relacionados.
\nIf you don’t want multiple associations between the same instances, add a\nUniqueConstraint including the from and to\nfields. Django’s automatically generated many-to-many tables include such a\nconstraint.
Existem algumas poucas restrições sobre os modelos intermediários.
\nSeu modelo intermediário deve ter uma - e * somente* uma - chave estrangeira para o modelo fonte (no nosso exemplo, este deve ser o Group), ou você deverá especificar explicitamente as chaves-estrangeiras que o Django deve usar para o relacionamento usando o ManyToManyField.through_fields. Se você tiver mais de uma chave-estrangeira e through_fields não estiver especificado, um erro de validação será emitido. Uma restrição similar se aplica para a chave-estrangeira para o modelo alvo (no nosso exemplo, este deve ser o Person).
For a model which has a many-to-many relationship to itself through an\nintermediary model, two foreign keys to the same model are permitted, but\nthey will be treated as the two (different) sides of the many-to-many\nrelationship. If through_fields is not specified,\nthe first foreign key will be taken to represent the source side of the\nManyToManyField, while the second will be taken to represent the target\nside. If there are more than two foreign keys though, you must specify\nthrough_fields to explicitly indicate which foreign\nkeys to use, otherwise a validation error will be raised.
Now that you have set up your ManyToManyField to use\nyour intermediary model (Membership, in this case), you’re ready to start\ncreating some many-to-many relationships. You do this by creating instances of\nthe intermediate model:
>>> ringo = Person.objects.create(name="Ringo Starr")\n>>> paul = Person.objects.create(name="Paul McCartney")\n>>> beatles = Group.objects.create(name="The Beatles")\n>>> m1 = Membership(\n... person=ringo,\n... group=beatles,\n... date_joined=date(1962, 8, 16),\n... invite_reason="Needed a new drummer.",\n... )\n>>> m1.save()\n>>> beatles.members.all()\n<QuerySet [<Person: Ringo Starr>]>\n>>> ringo.group_set.all()\n<QuerySet [<Group: The Beatles>]>\n>>> m2 = Membership.objects.create(\n... person=paul,\n... group=beatles,\n... date_joined=date(1960, 8, 1),\n... invite_reason="Wanted to form a band.",\n... )\n>>> beatles.members.all()\n<QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>]>\nYou can also use add(),\ncreate(), or\nset() to create\nrelationships, as long as you specify through_defaults for any required\nfields:
>>> beatles.members.add(john, through_defaults={"date_joined": date(1960, 8, 1)})\n>>> beatles.members.create(\n... name="George Harrison", through_defaults={"date_joined": date(1960, 8, 1)}\n... )\n>>> beatles.members.set(\n... [john, paul, ringo, george], through_defaults={"date_joined": date(1960, 8, 1)}\n... )\nYou may prefer to create instances of the intermediate model directly.
\nIf the custom through table defined by the intermediate model does not enforce\nuniqueness on the (model1, model2) pair, allowing multiple values, the\nremove() call will\nremove all intermediate model instances:
>>> Membership.objects.create(\n... person=ringo,\n... group=beatles,\n... date_joined=date(1968, 9, 4),\n... invite_reason="You've been gone for a month and we miss you.",\n... )\n>>> beatles.members.all()\n<QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>, <Person: Ringo Starr>]>\n>>> # This deletes both of the intermediate model instances for Ringo Starr\n>>> beatles.members.remove(ringo)\n>>> beatles.members.all()\n<QuerySet [<Person: Paul McCartney>]>\nThe clear()\nmethod can be used to remove all many-to-many relationships for an instance:
>>> # Beatles have broken up\n>>> beatles.members.clear()\n>>> # Note that this deletes the intermediate model instances\n>>> Membership.objects.all()\n<QuerySet []>\nOnce you have established the many-to-many relationships, you can issue\nqueries. Just as with normal many-to-many relationships, you can query using\nthe attributes of the many-to-many-related model:
\n# Find all the groups with a member whose name starts with 'Paul'\n>>> Group.objects.filter(members__name__startswith="Paul")\n<QuerySet [<Group: The Beatles>]>\nAs you are using an intermediate model, you can also query on its attributes:
\n# Find all the members of the Beatles that joined after 1 Jan 1961\n>>> Person.objects.filter(\n... group__name="The Beatles", membership__date_joined__gt=date(1961, 1, 1)\n... )\n<QuerySet [<Person: Ringo Starr]>\nIf you need to access a membership’s information you may do so by directly\nquerying the Membership model:
>>> ringos_membership = Membership.objects.get(group=beatles, person=ringo)\n>>> ringos_membership.date_joined\ndatetime.date(1962, 8, 16)\n>>> ringos_membership.invite_reason\n'Needed a new drummer.'\nAnother way to access the same information is by querying the\nmany-to-many reverse relationship from a\nPerson object:
>>> ringos_membership = ringo.membership_set.get(group=beatles)\n>>> ringos_membership.date_joined\ndatetime.date(1962, 8, 16)\n>>> ringos_membership.invite_reason\n'Needed a new drummer.'\nPara definir um relacionamento um-para-um, use a OneToOneField. Você pode usar como qualquer outro tipo Field: incluindo-o como um atributo de classe do seu modelo.
Isso é mais útil na chave-primária de um objeto quando este objeto “estende” um outro objeto de alguma maneira.
\nA OneToOneField requer um argumento posicional: a classe com a qual o modelo é relacionado.
Por exemplo, se você estiver construindo um banco de dados de “places”, você pode construir coisas bem padrão tal como endereços, número de telefone, etc. no banco de dados. Então se quiser construir um banco de dados de restaurantes baseado nos lugares, ao invés de repetir a si mesmo e replicar aqueles campos no modelo Restaurant, você pode fazer Restaurant ter um OneToOneField para Place ( porque um restaurante “é um” lugar; de fato, para lidar com isso você poderia tipicamente usar herança, a qual envolve uma relação um-para-um implícita).
Assim como a ForeignKey, um relacionamento recursivo pode ser definido e referencia a modelos ainda não definidos pode ser feita.
Os campos OneToOneField também aceitam um argumento opcional parent_link.
Classes OneToOneField usados para automaticamente se tornar a chave-primária de um modelo. Isso não e mais verdade (embora você possa passar manualmente no argumento attr:~django.db.models.Field.primary_key se quiser). Então, agora é possível ter múltiplos campos de tipos OneToOneField em um único modelo.
It’s perfectly OK to relate a model to one from another app. To do this, import\nthe related model at the top of the file where your model is defined. Then,\nrefer to the other model class wherever needed. For example:
\nfrom django.db import models\nfrom geography.models import ZipCode\n\n\nclass Restaurant(models.Model):\n # ...\n zip_code = models.ForeignKey(\n ZipCode,\n on_delete=models.SET_NULL,\n blank=True,\n null=True,\n )\nAlternatively, you can use a lazy reference to the related model, specified as\na string in the format "app_label.ModelName". This does not require the\nrelated model to be imported. For example:
from django.db import models\n\n\nclass Restaurant(models.Model):\n # ...\n zip_code = models.ForeignKey(\n "geography.ZipCode",\n on_delete=models.SET_NULL,\n blank=True,\n null=True,\n )\nSee lazy relationships for more details.
\nDjango places some restrictions on model field names:
\nA field name cannot be a Python reserved word, because that would result\nin a Python syntax error. For example:
\nclass Example(models.Model):\n pass = models.IntegerField() # 'pass' is a reserved word!\nUm nome de campo não pode conter mais de um “underscore” em uma linha, devido a maneira como a sintaxe dos filtros de pesquisa do Django funcionam.
\nclass Example(models.Model):\n foo__bar = models.IntegerField() # 'foo__bar' has two underscores!\nA field name cannot end with an underscore, for similar reasons.
A field name cannot be check, as this would override the check\nframework’s Model.check() method.
Essas limitações podem ser contornadas, embora, porque seu nome de campo não tem que combinar necessariamente com os nomes de colunas dos banco de dados. Veja a opção db_column.
Palavras-reservadas SQL, tal como join, where ou select, são permitidas como um nome de campos de modelo, porque o Django escapa todos os nomes de colunas e tabelas do banco de dados em cada consulta SQL. Ele usa a sintaxe citada do “engine” do seu banco de dados em particular.
Se um dos campos de modelo existentes não pode ser usado para atender seus propósitos, ou se você deseja tirar vantagem de algum tipo de coluna de banco de dados menos comum, você pode criar sua própria classe de campo. Uma cobertura completa de criar seus próprios campos é fornecido em Como criar campos de modelo customizado.
\nMetaLink para este cabeçalho#Dê ao seu modelo meta-dados usando uma class Meta interna, como segue:
from django.db import models\n\n\nclass Ox(models.Model):\n horn_length = models.IntegerField()\n\n class Meta:\n ordering = ["horn_length"]\n verbose_name_plural = "oxen"\nMeta-dado de modelo é “qualquer coisa que não é um campo”, assim como opções de ordenamento (ordering), nome da tabela do banco de dados (db_table), ou nomes legíveis plural e singular (verbose_name and verbose_name_plural). Nenhum é requierido, e adicionar class Meta ao seu modelo é completamente opcional.
Uma lista completa de todos as opções Meta possíveis pode ser encontrada na referência de opções de modelo.
objetosO atributo mais importante de uma classe de modelo é o Manager. Ele é a interface através da qual o operações de consultas no banco de dados são fornecidas aos modelos do Django e usadas para retornar instâncias de modelos do banco de dados. Se nenhum Manager personalizado é definido, o nome padrão é objects. Os “managers” somente são acessíveis através de classes de modelos, não por instâncias de de modelos.
Defina métodos personalizados em um modelo para adicionar funcionalidade de “nível de linha” personalizado a seus objetos. Enquanto que os métodos Manager são para coisas para “toda a tabela”, métodos de modelos devem agir sobre uma intância de modelo em particular.
Esta é uma técnica valiosa para manter a lógica de negócios em um único lugar – o modelo.
\nPor exemplo, este modelo tem alguns poucos métodos personalizados:
\nfrom django.db import models\n\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n last_name = models.CharField(max_length=50)\n birth_date = models.DateField()\n\n def baby_boomer_status(self):\n "Returns the person's baby-boomer status."\n import datetime\n\n if self.birth_date < datetime.date(1945, 8, 1):\n return "Pre-boomer"\n elif self.birth_date < datetime.date(1965, 1, 1):\n return "Baby boomer"\n else:\n return "Post-boomer"\n\n @property\n def full_name(self):\n "Returns the person's full name."\n return f"{self.first_name} {self.last_name}"\nO último métodos neste exemplo é uma propriedade.
\nA refrência de instância de modelo tem um lista completa de métodos automaticamente dados a cada modelos. Você pode sobrescrever a maioria deles – veja sobrescrevendo métodos pré-definidos de modelo, abaixo – mas existem alguns que você irá quase sempre querer definir:
\n__str__()A Python “magic method” that returns a string representation of any\nobject. This is what Python and Django will use whenever a model\ninstance needs to be coerced and displayed as a plain string. Most\nnotably, this happens when you display an object in an interactive\nconsole or in the admin.
\nVocê sempre irá querer definir este método; o padrão em geral não ajuda muito.
\nget_absolute_url()Este dia ao Django como calcular a URL de um objeto. O Django usa isso na sua interface do “admin” e a qualquer momento que ele precisa descobrir a URL de um objeto.
\nQualquer objeto que tem um URL que o identifica unicamente deve definir este método.
\nExiste um outro conjunto de métodos de modelos que encapsulam vários comportamentos ligados ao banco de dados que você irá querer personalizar. EM particu;ar você irá querer muitas vezes alterar a maneira que o save() e delete() funcionam.
Você é livre para sobrescrever estes métodos (e qualquer outro método de modelo) para alterar o comportamento.
\nUm caso de uso clássico para sobrescrever métodos embutidos é se você quiser que algo aconteça quando salvar um objeto. Por exemplo (veja save() para a documentaçao dos parâmetros que ele aceita):
from django.db import models\n\n\nclass Blog(models.Model):\n name = models.CharField(max_length=100)\n tagline = models.TextField()\n\n def save(self, **kwargs):\n do_something()\n super().save(**kwargs) # Call the "real" save() method.\n do_something_else()\nVocê pode também evitar salvar:
\nfrom django.db import models\n\n\nclass Blog(models.Model):\n name = models.CharField(max_length=100)\n tagline = models.TextField()\n\n def save(self, **kwargs):\n if self.name == "Yoko Ono's blog":\n return # Yoko shall never have her own blog!\n else:\n super().save(**kwargs) # Call the "real" save() method.\nIt’s important to remember to call the superclass method – that’s\nthat super().save(**kwargs) business – to ensure that the object still\ngets saved into the database. If you forget to call the superclass method, the\ndefault behavior won’t happen and the database won’t get touched.
It’s also important that you pass through the arguments that can be\npassed to the model method – that’s what the **kwargs bit does. Django\nwill, from time to time, extend the capabilities of built-in model methods,\nadding new keyword arguments. If you use **kwargs in your method\ndefinitions, you are guaranteed that your code will automatically support those\narguments when they are added.
If you wish to update a field value in the save() method, you may\nalso want to have this field added to the update_fields keyword argument.\nThis will ensure the field is saved when update_fields is specified. For\nexample:
from django.db import models\nfrom django.utils.text import slugify\n\n\nclass Blog(models.Model):\n name = models.CharField(max_length=100)\n slug = models.TextField()\n\n def save(self, **kwargs):\n self.slug = slugify(self.name)\n if (\n update_fields := kwargs.get("update_fields")\n ) is not None and "name" in update_fields:\n kwargs["update_fields"] = {"slug"}.union(update_fields)\n super().save(**kwargs)\nSee Specifying which fields to save for more details.
\n\nUm outro padrão comum é escrever comandos SQL personalizados em métodos de modelos e métodos no nível do módulo. Para mais detalhes sobre usar SQL puro, veja a documentação no usando SQL puro.
\nA herança de modelo no Django funciona quase idêntico a maneira que herança de classes normais no Python, mas o básico do início da página ainda deve ser seguido. Isso significa que c classe base deve ser uma subclasse de django.db.models.Model.
A única decisão que você tem tomar é se você quer que os modelos pais sejam modelos por eles mesmos (com suas próprias tabelas de banco de dados), ou se os modelos parentes são somente para manter informações comuns que somente serão vistas através de seus modelos filhos.
\nExistem três estilos de herança que possíveis em Django.
\nMuitas vezes, você quer somente usar uma classe pai para manter informação que você não quer ter que escrever para cada modelo filho. Essa classe nunca será usada isoladamente, então o que você quer é uma Classes abstratas base
Se você estiver herdando um modelo existente (talvez algo de uma outra aplicação inteira) e quer que cada modelo tenha sua própria tabela de banco de dados, o Herança de múltiplas tabelas é o caminho.
Finalmente, se você quer modificar o comportamento no nível do Python de um modelo, sem mudar os campos do modelo de nenhuma maneira, você pode usar os Modelos Proxy.
Abstract base classes are useful when you want to put some common\ninformation into a number of other models. You write your base class\nand put abstract=True in the Meta\nclass. This model will then not be used to create any database\ntable. Instead, when it is used as a base class for other models, its\nfields will be added to those of the child class.
Um exemplo:
\nfrom django.db import models\n\n\nclass CommonInfo(models.Model):\n name = models.CharField(max_length=100)\n age = models.PositiveIntegerField()\n\n class Meta:\n abstract = True\n\n\nclass Student(CommonInfo):\n home_group = models.CharField(max_length=5)\nO modelo Student terá três campos: name, age e home_group. O modelo CommonInfo não pode ser usado como um modelo normal do Django, já que é uma classe abstrata base. Ele não gera uma tabela de banco de dados nem tem um “manager”, e não pode ser instânciado ou salvo diretamente.
Fields inherited from abstract base classes can be overridden with another\nfield or value, or be removed with None.
Em muitos casos, este tipo de herança de modelo será exatamente o que quer. Isso lhe fornece uma maneira de fatorar informações comuns ao nível do Python, enquanto cainda cria somente uma tabela de banco de dados para cada modelo filho no nível banco de dados.
\nMetaLink para este cabeçalho#QUando um modelo abstrato básico é criado, o Django com que qualquer classe Meta interna que você declare na classe base fique disponível como um atributo. Se a classe filha não declare sua própria classe Meta , ela irá herdar as Meta da pai. Se a filho quer estender a classe Meta da pai, ele pode herdá-la. Por exemplo:
\nfrom django.db import models\n\n\nclass CommonInfo(models.Model):\n # ...\n class Meta:\n abstract = True\n ordering = ["name"]\n\n\nclass Student(CommonInfo):\n # ...\n class Meta(CommonInfo.Meta):\n db_table = "student_info"\nDjango does make one adjustment to the Meta class of an\nabstract base class: before installing the Meta\nattribute, it sets abstract=False. This means that children of abstract\nbase classes don’t automatically become abstract classes themselves. To make\nan abstract base class that inherits from another abstract base class, you need\nto explicitly set abstract=True on the child.
Alguns atributos não farão sentido incluir na classe Meta de uma classe abstrata base. Por exemplo, incluir db_table poderia siginificar que todas as classes filhos (aquelas que não especificarem seus próprios Meta) poderiam usar a mesma tabela, o que é quase certo que não é o que você quer.
Due to the way Python inheritance works, if a child class inherits from\nmultiple abstract base classes, only the Meta options\nfrom the first listed class will be inherited by default. To inherit Meta options from multiple abstract base classes, you must\nexplicitly declare the Meta inheritance. For example:
\nfrom django.db import models\n\n\nclass CommonInfo(models.Model):\n name = models.CharField(max_length=100)\n age = models.PositiveIntegerField()\n\n class Meta:\n abstract = True\n ordering = ["name"]\n\n\nclass Unmanaged(models.Model):\n class Meta:\n abstract = True\n managed = False\n\n\nclass Student(CommonInfo, Unmanaged):\n home_group = models.CharField(max_length=5)\n\n class Meta(CommonInfo.Meta, Unmanaged.Meta):\n pass\nO segundo tipo de heraná de modelo que o Django suporta é quando cada modelo na hierarquia é um modelo completo. Cada modelo corresponder a sua própria tabele de banco de dados e pode ser consultado e criado individualmente. A herança de relacionamento introduz conexões entre a classe filho e cada um de seus parentes (através de um OneToOneField criado automaticamente). Por exemplo:
from django.db import models\n\n\nclass Place(models.Model):\n name = models.CharField(max_length=50)\n address = models.CharField(max_length=80)\n\n\nclass Restaurant(Place):\n serves_hot_dogs = models.BooleanField(default=False)\n serves_pizza = models.BooleanField(default=False)\nAll of the fields of Place will also be available in Restaurant,\nalthough the data will reside in a different database table. So these are both\npossible:
>>> Place.objects.filter(name="Bob's Cafe")\n>>> Restaurant.objects.filter(name="Bob's Cafe")\nIf you have a Place that is also a Restaurant, you can get from the\nPlace object to the Restaurant object by using the lowercase version of\nthe model name:
>>> p = Place.objects.get(id=12)\n# If p is a Restaurant object, this will give the child class:\n>>> p.restaurant\n<Restaurant: ...>\nTodavia, se p no exemplo acima não é um Restaurant (ele foi criado diretamente como um objeto Place ou era um pai de uma alguma outra classe), referenciar p.restaurant poderia emitir uma exceção Restaurante.DoeNotExist.
The automatically-created OneToOneField on\nRestaurant that links it to Place looks like this:
place_ptr = models.OneToOneField(\n Place,\n on_delete=models.CASCADE,\n parent_link=True,\n primary_key=True,\n)\nYou can override that field by declaring your own\nOneToOneField with parent_link=True on Restaurant.
Meta e herança de tabelas múltiplasLink para este cabeçalho#Na situação de herança de multi-tabelas , faz sentido para uma classe filho herdar de seu pai a classe Meta. Todas as opções Meta já foram aplicadas a classe pai aplicar novamente poderia normalmente levar a um comprtamento contraditório (isso em contrate com o caso da classe abstrata base, onde a classe base não existe por sí só).
\nEntão um modelo filho não tem acesso a classe Meta do seu pai. Porém, existem alguns poucos casos onde o filho herda comportamento do pai: se o filho não especifica um atributo ordering ou um atributo get_latest_by, ele herdará isso dos seu pai.
Se o pai tem um ordenação e você não quer que o filho tenha qualquer ordem natural, você pode explicitamente desabilitar isso:
\nclass ChildModel(ParentModel):\n # ...\n class Meta:\n # Remove parent's ordering effect\n ordering = []\nBecause multi-table inheritance uses an implicit\nOneToOneField to link the child and\nthe parent, it’s possible to move from the parent down to the child,\nas in the above example. However, this uses up the name that is the\ndefault related_name value for\nForeignKey and\nManyToManyField relations. If you\nare putting those types of relations on a subclass of the parent model, you\nmust specify the related_name\nattribute on each such field. If you forget, Django will raise a validation\nerror.
Por exemplo, usando novamente a classe Place acima, vamos criar outra subclasse com um ManyToManyField:
class Supplier(Place):\n customers = models.ManyToManyField(Place)\nThis results in the error:
\nReverse query name for 'Supplier.customers' clashes with reverse query\nname for 'Supplier.place_ptr'.\n\nHINT: Add or change a related_name argument to the definition for\n'Supplier.customers' or 'Supplier.place_ptr'.\nAdicionando related_name ao campo customers como segue poderia resolver o erro: models.ManyToManyField(Place, related_name='provider').
Como mencionado, o Django criará automaicamente uma relação OneToOneField para sua classe filho devolta para quaisquer modelos não abstratos. Se quiser controlar o nome do atributo de relacionamento devolta para o pai, você pode criar seu próprio OneToOneField e definir parent_link=True para indicar que seu campo é a conexão de reotorno com a classe pai.
Quando se usa herança de tabelas multiplas, uma nova tabela de banco de dados é criada para cada subclasse do modelo. Este é o comportamento desejável, já que a subclasse precisa de um lugar para armazenar qualquer campo de dado adicional que não esteja presente na classe base. As vezes, entretanto, você quer somente mudar o comportamento Python do modelo – talvez para alterar o “manager” padrão do modelo, ou adicionar um método novo.
\nÉ para isso que serve o modelo “proxy”: criar um proxy para o modelo original. Você pode criar, deletar e editar instâncias do modelo “proxy” e todas os dados serão salvos como se você estivesse usando o modelo original (não “proxy”). A diferença, é que você pode alterar coisas como a ordenação padrão do modelo ou o “manager” padrão no “proxy”, sem ter que alterar o original.
\nModelos “Proxy” são declarados como os modelos normais. Você diz ao Django que este é um modelo “proxy” definindo o atributo proxy na classe Meta como True.
Por exemplo, suponha que queira adicionar um método ao modelo Person. Você pode fazê-lo assim:
from django.db import models\n\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=30)\n last_name = models.CharField(max_length=30)\n\n\nclass MyPerson(Person):\n class Meta:\n proxy = True\n\n def do_something(self):\n # ...\n pass\nThe MyPerson class operates on the same database table as its parent\nPerson class. In particular, any new instances of Person will also be\naccessible through MyPerson, and vice-versa:
>>> p = Person.objects.create(first_name="foobar")\n>>> MyPerson.objects.get(first_name="foobar")\n<MyPerson: foobar>\nYou could also use a proxy model to define a different default ordering on\na model. You might not always want to order the Person model, but regularly\norder by the last_name attribute when you use the proxy:
class OrderedPerson(Person):\n class Meta:\n ordering = ["last_name"]\n proxy = True\nAgora consultas normais ao Person serão não ordenadas e consultas ao OrderedPerson serão ordenadas pelo last_name.
Proxy models inherit Meta attributes in the same way as regular\nmodels.
QuerySets ainda retornam o modelo que foi requisitadoLink para este cabeçalho#Não te uma maneira do Django retornar, vamos dizer, um objeto MyPerson quando consultar por objetos Person. Uma consulta em objetos Person irá retornar aquele tipo de objetos. O ponto de objetos “proxy” é que o código que está no Person original irá usar este código e seu próprio código pode usar as estensões que foram incluídas (que nenhum outro código depende de nenhuma forma). Esta não é uma maneira de substituir o modelo Person (ou nenhum outro) em nenhum lugar com alguma coisa criada por você mesmo.
Um modelo “proxy” deve herdar de exatamente uma classe de modelo não abstrato. Você não pode herdar de múltiplos modelos não abstratos já que o modelo “proxy” não ofrnece qualquer conexão entre as linhas nas diferentes tabelas do banco de dados. Um modelo proxy pode herdar de qualquer número de modelo de classe abstrata, desde que não definam campos de modelo. Um modelo proxy também pode herdar qualquer número de modelos proxy que compartilhem uma classe pai não abstrata em comum.
\nSe você não especificar um “manager” do modelo no modelo “proxy”, ele herda o “manager” de seu modelo pai. Se você definir um “manager” no modelo “proxy”, este será o padrão, embora qualquer “manager” definido nas classes pai ainda estarão disponíveis.
\nContinuando nosso exemplo acima, você pode mudar o “manager” padrão usado quando você fizer uma consulta ao modelo Person assim:
from django.db import models\n\n\nclass NewManager(models.Manager):\n # ...\n pass\n\n\nclass MyPerson(Person):\n objects = NewManager()\n\n class Meta:\n proxy = True\nSe você quiser adicionar um novo “manager” ao “Proxy”, sem substituir o padrão existente, você pode usar as técnicas descritas na documentação “manager” personalizado : crie uma classe base contendo os novos “managers” e herde esta depois da classe base primária:
\n# Create an abstract class for the new manager.\nclass ExtraManagers(models.Model):\n secondary = NewManager()\n\n class Meta:\n abstract = True\n\n\nclass MyPerson(Person, ExtraManagers):\n class Meta:\n proxy = True\nVocê provavelmente não precisa fazer isso muitas vezes, mas, quando precisar, é possível.
\nProxy model inheritance might look fairly similar to creating an unmanaged\nmodel, using the managed attribute on a\nmodel’s Meta class.
With careful setting of Meta.db_table you could create an unmanaged model that\nshadows an existing model and adds Python methods to it. However, that would be\nvery repetitive and fragile as you need to keep both copies synchronized if you\nmake any changes.
On the other hand, proxy models are intended to behave exactly like the model\nthey are proxying for. They are always in sync with the parent model since they\ndirectly inherit its fields and managers.
\nThe general rules are:
\nSe você esta espelhando um modelo existente ou uma tabela de banco de dados e nao quer todas as colunas originarias do banco de dados, use Meta.managed=False. Esta opção é normalmente útil para modelos “views” e tabelas de bancos de dados que não estão sob o controle do Django.
Se voc^está querendo alterar o modelo somente quanto seu comportamento Python, más manter todos os mesmos campos como no original, use Meta.proxy=True. Estas defini as coisas tal que o modelo “proxy” é uma cópia exata da estrutura de armazenamento do modelo original quando o dado são salvos.
Tal como é fazer uma subclasse em Python, é possível para um modelo Django herdar múltiplos modelos pai. Tenha em mente que as regras de resolução de nomes Python se aplicam. A primeira classe base que um nome em particular (e.x. Meta) aparece será a classe usada; por exemplo, isso significa que se múltiplos pais contém uma classe Meta, somente a primeira é que será usada, e todas as outras ignoradas.
\nGeralmente, você não vai precisar herdar de múltiplos pais. O principal caso onde isso é útil é para classes “mix-in”: adicionar um campo extra em particular ou método para ada classe que herda o “mix-in”. Tente manter sua hierarquia de herança tão simples e direta quanto possível, assim você não tem que lutar para descobrir de onde está vindo uma parte particuar da informação.
\nPerceba que herdar de múltiplos modelos que tem em comum um campo id como chave-primária irá emitir um erro. Para usar herança múltipla de maneira correta, você pode usar explicitamente a AutoField no modelo base:
class Article(models.Model):\n article_id = models.AutoField(primary_key=True)\n ...\n\n\nclass Book(models.Model):\n book_id = models.AutoField(primary_key=True)\n ...\n\n\nclass BookReview(Book, Article):\n pass\nOr use a common ancestor to hold the AutoField. This\nrequires using an explicit OneToOneField from each\nparent model to the common ancestor to avoid a clash between the fields that\nare automatically generated and inherited by the child:
class Piece(models.Model):\n pass\n\n\nclass Article(Piece):\n article_piece = models.OneToOneField(\n Piece, on_delete=models.CASCADE, parent_link=True\n )\n ...\n\n\nclass Book(Piece):\n book_piece = models.OneToOneField(Piece, on_delete=models.CASCADE, parent_link=True)\n ...\n\n\nclass BookReview(Book, Article):\n pass\nIn normal Python class inheritance, it is permissible for a child class to\noverride any attribute from the parent class. In Django, this isn’t usually\npermitted for model fields. If a non-abstract model base class has a field\ncalled author, you can’t create another model field or define\nan attribute called author in any class that inherits from that base class.
This restriction doesn’t apply to model fields inherited from an abstract\nmodel. Such fields may be overridden with another field or value, or be removed\nby setting field_name = None.
Sobrescrever campos em um modelo pai leva a dificuldades em áreas como a inicialização de novas instâncias (especificar qual campo está sendo inicializado no Model.__init__) e serialização. Estas são características que classes Python normais não tem que lidar do mesmo modo, isso quer dizer que a diferença entre herança de modelos Django e herança de classes Python não são arbitrárias.
A restrição somente se aplica a atributos os quais são instâncias de Field. Atributos normais de Python podem ser sobrescritos se quiser. Isos também só se aplica para os nomes de atributos com o Python os vê. Se você está manualmente especificando o nome da coluna do banco de dados, você pode ter o mesmo nome de coluna aparecendo em ambos, um filho e em um modelo ancestral para heraná de múltiplas tabelas (elas são solunas em duas diferentes tabelas de banco de dados).
O Django irá emitir uma FieldError se você sobrescrever qualquer campo de modelo de qualquer modelo ancestral.
Note that because of the way fields are resolved during class definition, model\nfields inherited from multiple abstract parent models are resolved in a strict\ndepth-first order. This contrasts with standard Python MRO, which is resolved\nbreadth-first in cases of diamond shaped inheritance. This difference only\naffects complex model hierarchies, which (as per the advice above) you should\ntry to avoid.
\nThe manage.py startapp command creates an application\nstructure that includes a models.py file. If you have many models,\norganizing them in separate files may be useful.
To do so, create a models package. Remove models.py and create a\nmyapp/models/ directory with an __init__.py file and the files to\nstore your models. You must import the models in the __init__.py file.
For example, if you had organic.py and synthetic.py in the models\ndirectory:
myapp/models/__init__.pyfrom .organic import Person\nfrom .synthetic import Robot\nExplicitly importing each model rather than using from .models import *\nhas the advantages of not cluttering the namespace, making code more readable,\nand keeping code analysis tools useful.