Criando um projeto

Se for a primeira vez que você está usando o Django você terá que preocupar-se com algumas configurações iniciais. A saber, você irá precisar auto-gerar algum código para estabelecer um projeto Django -- uma coleçao de configurações para uma instancia do Django, incluindo configuração do banco de dados, opções específicas do Django e configurações específicas da aplicação.

A partir da linha de comando, cd para o diretório onde você gostaria de armazenar seu código, então execute o comando django-admin.py startproject mysite. Isso irá criar o diretório mysite no seu diretório atual.

(O django-admin.py deverá estar no caminho do seu sistema se você instalou o Django via python setup.py. Se ele não estiver no caminho, você pode encontrá- lo em site-packages/django/bin, onde site-packages é um diretório dentro da sua instalação do Python. Considere a possibilidade de criar um link simbólico para o django-admin.py a partir de algum lugar no seu caminho, como em /usr/ local/bin.)

Vamos olhar o que o startproject criou:

mysite/
    __init__.py
    manage.py
    settings.py
    urls.py

Esses arquivos são:

• __init__.py: Um arquivo vazio que diz ao python que esse diretório deve ser considerado como um pacote Python. (Leia mais sobre pacotes na documentação oficial do Python se você for iniciante em Python.)
• manage.py: Um utilitário de linha de comando que permite a você interagir com esse projeto Django de várias maneiras.
• settings.py: Definições/configuração para esse projeto Django.
• urls.py: As declarações de URLs para esse projeto Django; uma "tabela de conteúdos" para o seu site movido a Django.

Validating models...
0 errors found.

Django version 0.95, using settings 'mysite.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C (Unix) or CTRL-BREAK (Windows).

python manage.py runserver 8080

python manage.py syncdb

Criando modelos

Agora que seu ambiente -- um "projeto" -- está configurado, você está pronto para começar o trabalho.

Cada aplicação que você escreve no Django consiste de um pacote Python, em algum lugar no seu caminho do Python, que seguirá uma certa convenção. O Django vem com um utilitário que gera automáticamente a estrutura básica de diretório de uma aplicação, então você pode se concentrar apenas em escrever código ao invés de ficar criando diretórios.

Nesse tutorial nós iremos criar nossa aplicação de enquete no diretório mysite, para simplificar. Como Conseqüência, a aplicação irá ser acoplada ao projeto -- assim sendo, o código Python interno da aplicação da enquete irá se referir a mysite.polls. Posteriormente, nesse tutorial, nós iremos discutir como desacoplar suas aplicações para distribuição.

Para criar sua aplicação, certifique-se de que você está no diretório mysite e digite esse comando:

python manage.py startapp polls

Isso irá criar um diretório polls, que irá ser apresentado desta forma:

polls/
    __init__.py
    models.py
    views.py

Essa estrutura de diretório irá abrigar a aplicação de enquete.

O primeiro passo ao escrever uma aplicação Web de banco de dados no Django é definir seus modelos -- essencialmente, o layout do seu banco de dados, com metadados adicionais.

Na nossa aplicação simples de enquete, nós iremos criar dois modelos: polls e choices. Uma enquete (poll) tem uma pergunta e uma data de publicação. Uma escolha (choice) tem dois campos: o texto da escolha e um totalizador de votos. Cada escolha é associada a uma enquete.

Esses conceitos são representados por simples classes Python. Edite o arquivo polls/models.py e ele se parecerá com isso:

from django.db import models

class Poll(models.Model):
    question = models.CharField(max_length=200)
    pub_date = models.DateTimeField('date published')

class Choice(models.Model):
    poll = models.ForeignKey(Poll)
    choice = models.CharField(max_length=200)
    votes = models.IntegerField()

O código é auto-explicativo. Cada modelo é representado por uma classe derivada da classe django.db.models.Model. Cada modelo tem um número de variáveis de classe, as quais por sua vez representam um campo de banco de dados no modelo.

Cada campo é representado por uma instância de uma classe models.*Field -- ex.: models.CharField para campos do tipo caractere e models.DateTimeField para datetimes. Isso diz ao Django qual tipo de dados cada campo suporta.

O nome de cada instância models.*Field (ex.: question ou pub_date ) é o nome do campo, em formato amigável para a maquina. Você irá usar esse valor no seu código Python, e seu banco de dados irá usá-lo como nome de coluna.

Você pode usar um argumento na primeira posição de um Field para designar um nome legível para humanos. O qual será usado em uma série de partes introspectivas do Django, e ele também servirá como documentação. Se esse campo não for fornecido, o Django irá usar o nome legível para a máquina. Nesse exemplo nós definimo um nome legível para humanos apenas para Poll.pub_date. Para todos os outros campos nesse modelo o nome legível para a maquina servirá como nome legível para humanos.

Algumas classes Field possuem elementos obrigatórios. O CharField, por exemplo, requer que você informe a ele um max_length. Isso é usando não apenas no esquema do banco de dados, mas na validação, como nós veremos em breve.

Finalmente, note a definição de um relacionamento, usando models.ForeignKey. Que diz ao Django que cada Choice (Escolha) está relacionada a uma única Poll (Enquete). O Django suporta todos os relacionamentos de banco de dados comuns: muitos-para-um, muitos-para-muitos e um-para-um.

Ativando os modelos

Aquela pequena parte do modelo fornece ao Django muita informação. Com ela o Django é capaz de:

• Criar um esquema de banco de dados (instruções CREATE TABLE) para essa aplicação.
• Criar uma API de acesso a banco de dados para acessar objetos Poll e Choice.

Mais primeiro nós precisamos dizer o nosso projeto que a aplicação polls está instalada.

Edite o arquivo settings.py novamente, e altere a configuração INSTALLED_APPS para incluir a string 'mysite.polls'. Então ela irá parecer com isso:

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'mysite.polls'
)

Agora o Django sabe que o mysite inclui a aplicação polls. Vamos rodar outro comando:

python manage.py sql polls

Você deverá ver algo similar ao seguinte (as instruções SQL CREATE TABLE para a aplicação pools):

BEGIN;
CREATE TABLE "polls_poll" (
    "id" serial NOT NULL PRIMARY KEY,
    "question" varchar(200) NOT NULL,
    "pub_date" timestamp with time zone NOT NULL
);
CREATE TABLE "polls_choice" (
    "id" serial NOT NULL PRIMARY KEY,
    "poll_id" integer NOT NULL REFERENCES "polls_poll" ("id"),
    "choice" varchar(200) NOT NULL,
    "votes" integer NOT NULL
);
COMMIT;

Note o seguinte:

• A saída exata irá variar dependendo do banco de dados que você está usando.
• Os nomes das tabelas são gerados automáticamente combinando o nome da aplicação (polls) e o nome em minúsculas do modelo -- poll e choice. (Você pode alterar esse comportamento.)
• Chaves primárias (IDs) são adicionadas automáticamente. (Você pode modificar isso, também.)
• Por convenção, o Django adiciona "_id" ao nome do campo chave estrangeira. Sim, você pode alterar isso, como quiser.
• O relacionamento da chave estrangeira é feito explicitamente por um instrução REFERENCES.
• Isso é atrelado ao banco que você está usando, então a utilização de campos específicos do banco de dados como auto_increment (MySQL), serial (PostgreSQL), ou integer primary key (SQLite) é feita para você automáticamente. O mesmo ocorre com as aspas dos nomes de campos -- ex.: usando aspas duplas ou aspas simples. O autor desse tutorial rodava PostgreSQL, então o saída do exemplo está na sintaxe do PostgreSQL.
• O comando sql atualmente não roda o SQL no seu banco de dados - ele apenas mostra-o na tela para que você possa ver o qual SQL o Django acha que seja necessário. Se você quiser, você pode copiar e colar esse SQL no prompt do seu banco de dados. Entretanto, como nós iremos ver em breve, o Django fornece uma maneira mais fácil de submeter o SQL ao banco de dados.

Se você tiver interesse, também rode os seguintes comandos:

• python manage.py validate -- Verifica por quaisquer erros na construção dos seus modelos.
• python manage.py sqlcustom polls -- Mostra quaisquer instruções SQL personalizadas (como modificações em tabelas ou limitadores) que tenham sido definidas para a aplicação.
• python manage.py sqlclear polls -- Mostra as instruções DROP TABLE necessárias para essa aplicação, de acordo com as tabelas que já existem no seu banco de dados (se houver alguma).
• python manage.py sqlindexes polls -- Mostra as instruções CREATE INDEX necessárias para essa aplicação.
• python manage.py sqlall polls -- Uma combinação de todo o SQL dos comandos 'sql', 'sqlcustom', e 'sqlindexes'.

Olhar para a saída desses comandos irá ajudar a entender o que está acontecendo por baixo do pano.

Agora, rode o syncdb novamente para criar essas tabelas de modelos no seu banco de dados:

python manage.py syncdb

O comando syncdb roda o sql do 'sqlall' em seu banco de dados para todas as aplicações presentes no INSTALLED_APPS que ainda não existam em seu banco de dados. Isso criará todas as tabelas, dados iniciais e índices para quaisquer aplicações que você tenha adicionado ao seu projeto desde a última vez que você rodou o syncdb. O syncdb pode ser chamado sempre que você quiser, e ele irá apenas criar as tabelas que não existirem.

Leia a documentação do django-admin.py para informações completas sobre o que o utilitário manage.py pode fazer.

Brincando com a API

Agora, vamos dar uma passada no shell interativo do Python e brincar um pouco com a API grátis que o Django dá a você. Para invocar o shell do Python, use esse comando:

python manage.py shell

Nós usaremos isso ao invés de simplesmente digitar "python", porque o manage.py configura o ambiente de projeto para você. "A configuração do ambiente" envolve duas coisas:

• Colocar o mysite no sys.path. Buscando flexibilidade, várias partes do Django referem-se aos projetos usando a notação pontuada do Python (ex.: 'mysite.polls.models'). Para que isso funcione, o pacote mysite precisa estar no sys.path.

  Nós já vimos um exemplo disso: a configuração INSTALLED_APPS é uma lista de pacotes na notação pontuada de caminho.

• Configurar a variável de ambiente DJANGO_SETTINGS_MODULE, que fornece ao Django o caminho para o seu arquivo settings.py.

Assim que você estiver no shell, explore a API de banco de dados:

# Importe as classes modelo que acabamos de criar.
>>> from mysite.polls.models import Poll, Choice

# Não há nenhuma enquete no sistema ainda.
>>> Poll.objects.all()
[]

# Crie uma nova Poll (enquete).
>>> import datetime
>>> p = Poll(question="What's up?", pub_date=datetime.datetime.now())

# Salve o objeto na base de dados. Você tem que chamar o save() explicitamente.
>>> p.save()

# Agora ela tem uma ID. Note que ele irá mostrar "1L" ao invés de "1",
# dependendo de qual banco de dados você está usando. Não é nada demais; isso
# apenas significa que o backend do seu banco de dados prefere retornar
# inteiros como objetos inteiros longos do Python.
>>> p.id
1

# Acesse colunas do banco de dados via atributos do Python.
>>> p.question
"What's up?"
>>> p.pub_date
datetime.datetime(2007, 7, 15, 12, 00, 53)

# Modifique valores alterando os atributos e depois chamando o save().
>>> p.pub_date = datetime.datetime(2007, 4, 1, 0, 0)
>>> p.save()

# objects.all() mostra todas as enquetes do banco de dados.
>>> Poll.objects.all()
[<Poll: Poll object>]

Espere um pouco. <Poll: Poll object> é, uma representação totalmente inútil desse objeto. Vamos corrigir isso editando o modelo de enquetes (no arquivo polls/models.py) e adicionando um método __unicode__() a ambos Poll e Choice:

class Poll(models.Model):
    # ...
    def __unicode__(self):
        return self.question

class Choice(models.Model):
    # ...
    def __unicode__(self):
        return self.choice

É importante adicionar métodos __unicode__() aos seus modelos, não apenas para sua própria sanidade quando estiver lidando com o prompt interativo, mas também porque representações de objetos são usadas em toda administração gerada automáticamente pelo Django.

Note que esses são métodos Python normais. Vamos adicionar um método personalizado, apenas por demonstração:

import datetime
# ...
class Poll(models.Model):
    # ...
    def was_published_today(self):
        return self.pub_date.date() == datetime.date.today()

Note a adição de import datetime para referenciar o módulo padrão do Python datetime.

Vamos voltar um pouco ao shell interativo do Python rodando python manage.py shell novamente:

>>> from mysite.polls.models import Poll, Choice

# Certifique-se de que a sua adição do __unicode__() funcionou.
>>> Poll.objects.all()
[<Poll: What's up?>]

# O Django fornece uma rica API de procura em banco de dados inteiramente
# controlada por argumentos formados por palavras-chave.
>>> Poll.objects.filter(id=1)
[<Poll: What's up?>]
>>> Poll.objects.filter(question__startswith='What')
[<Poll: What's up?>]

# Pegue a enquete cujo ano é 2007. Claro que, se você estiver seguindo esse
# tutorial em outro ano, mude como for apropriado.
>>> Poll.objects.get(pub_date__year=2007)
<Poll: What's up?>

>>> Poll.objects.get(id=2)
Traceback (most recent call last):
    ...
DoesNotExist: Poll matching query does not exist.

# Buscar por uma chave primária é o caso mais comum, então o Django fornece um
# atalho para buscas por chaves primárias específicas.
# O que se segue é idêntido a Poll.objects.get(id=1).
>>> Poll.objects.get(pk=1)
<Poll: What's up?>

# Certifique-se de que o método personalizado funcionou.
>>> p = Poll.objects.get(pk=1)
>>> p.was_published_today()
False

# Dê à enquete (``Poll``) algumas opções (``Choices``). A chamada ``create`` constrói um
# novo objeto opção (``choice``), executa a instrução INSERT, adiciona a escolha ao
# conjunto de escolhas disponíveis e retorna o novo objeto opção (``Choice``).
>>> p = Poll.objects.get(pk=1)
>>> p.choice_set.create(choice='Not much', votes=0)
<Choice: Not much>
>>> p.choice_set.create(choice='The sky', votes=0)
<Choice: The sky>
>>> c = p.choice_set.create(choice='Just hacking again', votes=0)

# Objetos ``Choice`` possuem acesso via API aos seus objetos ``Poll`` relacionados.
>>> c.poll
<Poll: What's up?>

# E vice-versa: Objetos ``Poll`` possuem acesso aos objetos ``Choice``.
>>> p.choice_set.all()
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]
>>> p.choice_set.count()
3

# A API segue automáticamente os relacionamentos da forma como você precisa.
# Use ``underscores`` duplos para separar relacionamentos.
# Isso funciona em tantos níveis abaixo quando você quiser; não há limite.
# Encontre todas as opções (``choices``) para uma enquete cuja ``pub_date`` é em 2007.
>>> Choice.objects.filter(poll__pub_date__year=2007)
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]

# Vamos deletar uma das escolhas. Use delete() para isso.
>>> c = p.choice_set.filter(choice__startswith='Just hacking')
>>> c.delete()

Para um detalhamento completo da API de banco de dados, veja nossa referência à API de Banco de Dados.

Quando você se sentir confortável com a API, leia a parte 2 desse tutorial para colocar a administração automática do Django para funcionar.