{{{
#!rst



THIS TRANSLATION IS IN PROGRESS:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------------------------------------------------------------------------------+
|    This is an **in progress** translation document, that means there is somebody working on it. |
|    For more information on translating documents please look at `TranslateDocumentation Wiki`_. |
|    Please **do not** edit this page.                                                            |
|                                                                                                 |
| .. _TranslateDocumentation Wiki : http://code.djangoproject.com/wiki/TranslateDocumentation     |
+-------------------------------------------------------------------------------------------------+   

..
  ===============
  Model reference
  ===============

.. sidebar:: Referência dos models
  :subtitle: tradução para o português.

  Documento original: `Django Model Reference`_
  
  Tradução: gabriel `<gabriel.sales at gmail.com>`
  
  Referente a revisão: 3953

.. _Django Model Reference: http://www.djangoproject.com/documentation/model_api/

.. contents:: **Conteúdos do capítulo**

Este documento cobre a versão 0.95 de Django e a versão do desenvolvimento. Docs anteriores: `0.90`_, `0.91`_



.. _0.90: http://www.djangoproject.com/documentation/0_90/ 


.. _0.91: http://www.djangoproject.com/documentation/0_91/ 

=====================
Referência dos Models
=====================

Um model é a fonte única e definitiva dos seus dados, nele estão contidos os
campos essenciais e relacionamentos dos dados que você está arquivando.
Genericamente, cada model referencia a uma tabela no banco de dados.

O básico:

    * Cada model é uma classe Python que é uma subclasse de
      ``django.db.models.Model``.
    * Cada atributo do model representa um campo na base de dados.
    * Metadados do model (informações descritivas dos dados) vão para uma
      classe interior nomeada ``Meta``.
    * Metadados usados para o site de administração do Django vão para a
      classe interior nomeada ``Admin``.
    * A partir disso o Django oferece uma API de acesso ao banco de dados
      gerada automaticamente, que é melhor explicada no
      `Referência da API de Banco de Dados`_.

Associado a esse documento existe o `repositório oficial de exemplos de
models`_.(No código fonte do Django, estes exemplos se encontram no
diretório ``tests/modeltests``.)

.. _Referência da API de Banco de Dados: http://www.djangoproject.com/documentation/db_api/
.. _repositório oficial de exemplos de models: http://www.djangoproject.com/documentation/models/

Exemplo rápido
==============

Este model exemplo define uma ``Person``, que possui um ``first_name`` e
``last_name``::

    from django.db import models

    class Person(models.Model):
        first_name = models.CharField(maxlength=30)
        last_name = models.CharField(maxlength=30)

``first_name`` e ``last_name`` são *campos* do model. Cada campo é
especificado como um atributo da classe, e cada atributo referencia a uma
coluna do banco de dados.

O model ``Person`` acima criaria uma tabela no banco de dados como essa::

    CREATE TABLE myapp_person (
        "id" serial NOT NULL PRIMARY KEY,
        "first_name" varchar(30) NOT NULL,
        "last_name" varchar(30) NOT NULL
    );

Algumas notas técnicas:

    * O nome da tabela, ``myapp_person``, é automaticamente atribuído de
      algum metadado do model podendo ser sobrescrito. Olhe _`Nome de
      Tabelas` abaixo.
    * Um campo ``id`` é adicionado automaticamente, mas essa ação pode ser
      configurada. Olhe `Campos de chave primária automáticos`_ a seguir.
    * O código SQL ``CREATE TABLE`` utilizado no exemplo está formatado
      na syntax do PostgreSQL, porém é valido notar que o Django utiliza
      a syntax de acordo com o tipo de banco de dados especificado no seu
      `arquivo de configurações`_.

.. _arquivo de configurações: http://www.djangoproject.com/documentation/settings/

Campos
======

A parte mais importante de um model -- e a única obrigatória -- é a
definição da lista de campos da base de dados. Esses campos são
especificados por atributos de classe.

Exemplos:

    class Musician(models.Model):
        first_name = models.CharField(maxlength=50)
        last_name = models.CharField(maxlength=50)
        instrument = models.CharField(maxlength=100)

Restrições de nomes de campos
-----------------------------

O Django impõe apenas dois tipos de restrição à nomes de campos:

    1. O campo não pode ser nomeado com uma palavra reservada do Python,
       porque seu uso ocasionaria em um erro de sintaxe. Por exemplo::

           class Example(models.Model):
           pass = models.IntegerField() # 'pass' é uma palavre reservada!

    2. Um nome de campo não pode possuir mais do que uma sobrelinha por
       linha, por causa da sintaxe do Django para buscas no banco. Por
       exemplo::

           class Example(models.Model):
               foo__bar = models.IntegerField() 'foo__bar' possui duas
               sobrelinhas!

Essas limitações podem ser contornadas, porque o nome do campo não precisa
necessariamente conter o nome da coluna do banco de dados. Veja a seção
`db_column`_ abaixo.




}}}