Escrevendo Seu Primeiro Aplicativo Com Django Parte 1

Conteúdo Traduzido do site: Django Project

Este documento cobre a versão 0.95 de Django e a versão do desenvolvimento. Docs anteriores: 0.90, 0.91 Vamos aprender usando um exemplo. Através deste tutorial vamos demonstrar os passos necessários para a criação de uma simples aplicação Web de pesquisa. Ela vai consistir de duas partes: • Um site público que irá permitir que usuários votem na pesquisa e vizualizem seus resultados. • Um site administrativo que permitirá você adicionar, alterar e excluir pesquisas Vamos assumir que você já tem o Django instalado. Você pode verificar se o Django está instalado abrindo o interpretador interativo Python digitando "import django". Se este comando for executado com sucesso, sem erro, significa que o Django está instalado. Criando um Projeto Se esta é sua primeira vez usando o Django você precisará realizar algumas tarefas de configuração inicial. Você terá que auto-gerar algumas linhas de código que estabelecem o projeto Django -- uma configuração própria a cada instância do Django, incluindo a configuração da base de dados, as opções específicas ao Django e as configurações específicas às aplicações. Na linha de comando, no diretório onde você gostaria de colocar o seu código, execute o comando "django-admin.py startproject mysite". Isto criará no diretório atual um novo diretório chamado "mysite".

NOTA Você deve evitar de nomear projetos com nomes de componentes internos do Python ou do Django. Em particular, isto significa que você deve evitar de usar nomes como django (que oporá ao próprio Django) ou o nome site (que se opoem a um pacote interno do Python). ("django-admin.py" deve estar em seu path se você instalou o Django usando seu utilitário setup.py. Se ele não está em seu path, você pode encontrá-lo em "site-packages/django/bin"; considere a criação de um link simbólico para ele em algum lugar de seu path, como /usr/local/bin.)

Onde colocamos o código? Se você conhece PHP, provavelmente está habituado a colocar o código dentro de um documento root num servidor web (num endereço como ´´/var/www´´)´. Com Django, não faça isso. Não é uma boa idéia colocar o código python dentro de um documento de servidor web, porque há o risco das pessoas verem o seu código, isto não é bom para a segurança do seu site.

Coloque o seu código fora dos diretórios do servidor, por exemplo "/home/mysite." Vamos dar uma olhada no que o comando "startproject" criou:

mysite/ __init__.py manage.py settings.py urls.py Estes arquivos são: • __init__.py: Um arquivo vazio que diz ao Python que este diretório deve ser considerado como um pacote do Python. (leia mais sobre pacotes na documentação oficial do Python se você é iniciante em Python) • manage.py: Uma ferramenta em linha de comando que permite interagir com este projeto Django de várias maneiras. • settings.py: Ajustes/configurações para este projeto Django.. • urls.py: As declarações de URLs para este projeto Django; trata-se de um “índice” do seu site gerado pelo Django.

Servidor de Desenvolvimento Vamos verificar se tudo está funcionando. Vá para o diretório mysite, se você ainda não estiver lá, e rode o comando python manage.py runserver. Você verá a seguinte saída na linha de comando:

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).

Você ligou o servidor de desenvolvimento do Django, a um servidor web leve inteiramente escrito em Python. Nós o incluímos ao Django para que você possa desenvolver coisas rápidamente, sem ter que se ocupar de configurar um servidor de produção - tal como Apache - até que você esteja pronto para a produção.

Agora é um boa hora para você tomar nota: Não use este servidor em qualquer coisa que assemelha-se a um ambiente de produção. Este servidor é destinado somente a uma utilização durante o desenvolvimento de uma aplicação. (Nós concebemos frameworks web, não servidores web.)

Agora que o servidor está rodando, visite http://127.0.0.1:8000/ no seu navegador Web. Você verá "Welcome to Django" num agradável tom azul-claro pastel. Funciona!

Mudando a porta Por padrão, o comando runserver inicia o servidor de desenvolvimento na porta 8000. Se você quiser mudar a porta do servidor, passe este argumento na linha de comando. Por instância, este comando inicia o servidor na porta 8080: python manage.py runserver 8080 Todos os docs do servidor de desenvolvimento estão na documentação do django-admin.

Configuração da base de dados Agora, edite o arquivo settings.py. É um módulo normal do Python com as variáveis do módulo que representam as opções de configuração do Django. Mude estes ajustes para combinar parâmetros da conexão da sua base de dados: DATABASE_ENGINE — Escolha um dentre eles "postgresql", "mysql" ou "sqlite3". Outros backends estão também disponíveis. DATABASE_NAME — O nome do seu Banco de Dados, ou o caminho completo(absoluto) do arquivo do Banco de Dados, caso esteja utilizando o SQLite. DATABASE_USER — O nome do usuário do Banco de Dados (não utilizado para SQLite). DATABASE_PASSWORD — A senha do Banco de Dados (não utilizado para SQLite). DATABASE_HOST — O nome do host onde ficará o Banco de Dados. Deixe este como uma string vazia se o servidor de banco de dados estiver na mesma máquina física(não usado para SQLite). Nota: Se você estiver usando PostgreSQL ou MySQL, tenha certeza de ter craido um Banco de Dados neste ponto. Digite "CREATE DATABASE database_name;" no prompt interativo do seu Banco de Dados. Quando você editar settings.py, note a presença do INSTALLED_APPS no final do arquivo. Essa variável contem os nomes de todas as aplicações de Django que são ativadas neste exemplo de Django. Os Apps podem ser usados em múltiplos projetos, e você pode empacotá-los e distribuí-los para que outros os utilizem em seus projetos. Por padrão, INSTALLED_APPS contem os seguintes aplicativos, todos são fornecidos pelo Django: • django.contrib.auth — Um sistema de autenticação.. • django.contrib.contenttypes — Um framework para os tipos de conteúdo. • django.contrib.sessions — Um framework que gerencia sessões. • django.contrib.sites — Um framework para gerenciar múltiplos sites com uma única instalação de Django. Estas aplicações são incluídas, por padrão, porque elas são convenientes na maioria dos casos. Cada uma destas aplicações emprega pelo menos uma tabela na base de dados, embora, assim que nós temos necessidade de criar estas tabelas na base de dados antes que nós possamos as utilizar. Para fazer isso, execute o seguinte comando:

python manage.py syncdb

O comando syncdb ajusta o INSTALLED_APPS e cria todas as tabelas necessárias na base de dados de acordo com os ajustes da base de dados em seu arquivo settings.py. Você verá uma mensagem para cada tabela criada na base de dados, e você verá um prompt que pergunta se você gostaria de criar uma conta de superusuário no sistema de autenticação. Vá adiante e faça isso. Se você estiver interessado, execute na linha de comando do cliente interativo de sua Base de Dados \dt (PostgreSQL), SHOW TABLES; (MySQL), ou .schema (SQLite) para verificar as tabelas que o Django criou.

Para os minimalistas Como nós dissemos acima, as aplicações, por padrão, são incluídas para o caso comum, mas nem todos necessários. Se você não necessitar de algum ou de todos os módulos, sinta-se livre para comentar ou deletar as devidas linhas do INSTALLED_APPS antes de executar o syncdb . O comando do syncdb criará somente tabelas para apps em INSTALLED_APPS.

Criando Modelos Agora que seu ambiente - "projeto" - está inicializado, você pode começar a fazer o seu projeto. Cada aplicação que você escreve em Django consiste em um pacote do Python, em algum lugar no caminho do Python, que segue uma determinada convenção. Django vem com uma funcionalidade que gera automaticamente a estrutura básica do diretório de um app, assim você pode focalizar melhor na escrita do código que na criação dos diretórios.

Projetos vs. Apps Qual é a diferença entre um projeto e um app? Um app é uma aplicação Web que faz algo - por exemplo, um sistema de weblog, uma base de dados de registros públicos ou um simples aplicativo de votação. Um projeto é uma coleção de configurações e de apps para um Web site particular. Um projeto pode conter múltiplos apps. Um app pode estar em múltiplos projetos.

Neste tutorial, nós criaremos um simples aplicativo de votação no diretório do mysite. Consequentemente, o app será acoplado ao projeto que é o código Python dentro do aplicativo votação que consultará o mysite.polls. Mais tarde neste tutorial, nós discutiremos o desacoplamento de suas aplicações para uma distribuição independente. Para criar seu app, certifique-se que você está no diretório mysite e digite este comando:

python manage.py startapp polls Isto criará um diretório polls, que é descrito a seguir: polls/ __init__.py models.py views.py

Esta estrutura do diretório abrigará a aplicação de votação. A primeira etapa em escrever um aplicativo Web na base de dados em Django é definir seus modelos - essencialmente, sua disposição na base de dados, com metadados adicionais.

Filosofia Um modelo é a única e definitiva fonte de dados sobre os seus dados. Contem os campos e os comportamentos essenciais dos dados que você está armazenando. Django segue o princípio DRY. O objetivo é definir seu modelo de dados em um lugar e derivar automaticamente as coisas a partir dele.

Em nosso simples aplicativo de votação, nós criaremos dois modelos: votações(polls) e escolhas(choices). Uma votação tem uma pergunta e uma data de publicação. Uma escolha tem dois campos: o texto da escolha e um registro de voto. Cada escolha é associada com uma votação. Estes conceitos são representados por classes simples do Python. Edite o arquivo polls/models.py para que fique como o exemplo abaixo:

from django.db import models class Poll(models.Model): question = models.CharField(maxlength=200) pub_date = models.DateTimeField('date published') class Choice(models.Model): poll = models.ForeignKey(Poll) choice = models.CharField(maxlength=200) votes = models.IntegerField()

O código é claro e conciso. Cada Modelo é representado por uma classe compreendida em django.db.models.Modelo. Cada Modelo tem um certo número de atributos da classe, cada qual representa um campo da base de dados no Modelo. Cada campo é representado por um exemplo de uma classe de models.*Field class - por exemplo, models.CharField para campos de tipo caracter e models.DateTimeField para campos do tipo data. Isto diz ao Django que tipo de dados está contido em cada campo. O nome de cada instância de models.*Field (por exemplo: question ou o pub_date) é o nome de campo. Você usará este valor em seu código do Python, e sua base de dados usá-lo-á como o nome da coluna. Você pode definir um primeiro argumento opcional Field um nome informal, mais fácil de ser compreendido por um leitor humano. Isso é usado em partes introspectivas do Django, e isto distribue também a documentação do código. Se este campo não for fornecido, Django usará o nome editado pela máquina. Neste exemplo, nós definimos somente um nome editado por pessoas para Poll.pub_date. Para todos campos restantes neste modelo, o nome editado pela máquina do campo bastará como seu nome editado por pessoas. Algumas classes do campo requereram elementos. CharField, por exemplo, requer que você lhe dê um maxlength. Isso é usado não somente no schema da base de dados, mas na validação, o que nós veremos logo. Finalmente, note que um relacionamento é definido, usando models.ForeignKey. Isso diz ao Django que cada escolha é relacionada a uma única votação. Django suporta todos os relacionamentos comuns da base de dados: um-para-muitos, muitos-para-muitos e um-para-um. Ativando Modelos Estes poucos bits de código do model dão ao Django muitas informações. Com ele, Django pode: • Criar um schema no Banco de Dados (as instruções CREATE TABLE) para este app. • Criar uma API Python para acesso ao Banco de Dados para acessar os objetos Poll(Votação) e Choice(Escolha). Mas primeiramente nós necessitamos dizer a nosso projeto que as polls(votações) app estão instaladas.

Filosofia Os apps de Django são "plugáveis": Você pode usar um app em projetos múltiplos, e você pode distribuir apps, porque eles não têm que ser amarrados a uma dada instalação de Django.

Edite o arquivo settings.py outra vez, e mude o INSTALLED_APPS para incluir a string "mysite.polls". Logo ficará como abaixo:

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

Agora o Django sabe que o mysite possui o app votações(polls). Vamos executar um outro comando:

python manage.py sql polls

Você deve ver algo similar ao seguinte (as instruções CREATE TABLE SQL para o app votações):

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;

Observe o seguinte: • A saída exata variará dependendo da base de dados que você está utilizando. • Os nomes da tabela são gerados automaticamente combinando o nome do aplicativo (polls) e o plural do nome do objeto – polls e choices. (Você pode alterar este comportamento.) • As Chaves Primárias (IDs) são adicionadas automáticamente. (Você pode alterar este comportamento também.) • Por convenção, Django adiciona o "_id" ao nome de campo chave estrangeira. Sim, você pode alterar isto, também. • O relacionamento de chave estrangeira (foreign key) é feito explicitamente pela cláusula "REFERENCES". • O código é redigido por um Banco de Dados que você está usando, assim os tipos de campo específicos de cada Banco de Dados tais como o auto_increment (MySQL), o serial (PostgreSQL), ou o integer primary key (SQLite) são gerados para você automaticamente. A mesma coisa acontece com as quotes de nomes de campo - por exemplo, usando quotes dobro ou simples quotes. O autor deste tutorial utiliza PostgreSQL, por isso que o exemplo está na sintaxe de PostgreSQL. • O comando sql não roda realmente o SQL na sua base de dados - ele mostra na tela os comandos SQL de modo que você possa ver que o SQL do Django pensa ser requerido. Se você quiser, você pode copiar e colar este código SQL em seu prompt da base de dados. Entretanto, como nós veremos adiante, Django fornece uma maneira mais fácil de comitar o SQL na base de dados. Se você estiver interessado, execute também os seguintes comandos: • python manage.py validate polls —Verifica qualquer erro na construção do seu models. • python manage.py sqlcustom polls —Mostra as inserções de dados iniciais requeridos pelo framework de administração do Django. • python manage.py sqlclear polls — Mostra as cláusulas "DROP TABLE" necessárias para este aplicativo, de acordo com as tabelas já existentes em sua base de dados (se existentes).  python manage.py sqlindexes polls —Mostra as cláusulas "CREATE INDEX" para este aplicativo.  python manage.py sqlall polls — Uma combinação dos comandos SQL de "sql", "sqlcustom", e "sqlindexes" Olhando a saída destes comandos pode ajudá-lo a entender o que realmente ocorre por baixo dos panos. Agora, execute syncdb novamente para criar as tabelas do model na base de dados:

python manage.py syncdb

O comando do syncdb executa o sql do "sqlall" na sua base de dados para todos os apps em INSTALLED_APPS que ainda não existem na sua base de dados. Isto cria todas as tabelas, dados iniciais e índices para todos os apps que você adicionar a seu projeto desde a última vez você executou o syncdb. O syncdb pode ser chamado sempre que você quiser criar tabelas que não existem. Leia a documentação de django-admin.py para informação completa sobre a utilização do manage.py. Manipulando a API Agora abra o shell interativo do Python interactive shell, e iremos manipular a API Python que Django lhe fornece: Chame o Shell Python, usando este comando:

python manage.py shell

Nós estamos usando este comando em vez do comando "python" simplesmente, porque manage.py define o ambiente do projeto para você. "Definir o ambiente" significa duas coisas: • Inserir o mysite sobre sys.path. Para a flexibilidade, diversas partes de Django consultam os projetos na notação Python de caminhos separados por pontos (por exemplo. "mysite.polls.models"). Para que isto para funcione, o pacote do mysite tem que estar em sys.path. Nós já vimos um exemplo deste tipo: a opção de INSTALLED_APPS é uma lista dos pacotes na notação do caminho separado por pontos. • Definição da variável de ambiente de DJANGO_SETTINGS_MODULE, que dá ao Django o trajeto do seu arquivo settings.py.

Contornando manage.py Se você não quiser utilizar o manage.py não há problema. Certifique-se que o diretório mysite está no diretório raiz sobre arquivos do Python (ou seja, quando você dijitar import mysite funciona) e defina uma variável de ambiente DJANGO_SETTINGS_MODULE a mysite.settings. Para mais informações, leia a documentação do django-admin.py.

# Importe as Classes do Modelo que nós iremos trabalhar. >>> from mysite.polls.models import Poll, Choice # Não há nenhuma votação no sistema por enquanto. >>> Poll.objects.all() [] # Crie uma nova votação. >>> from datetime import datetime >>> p = Poll(question="What's up?", pub_date=datetime.now()) # Salve o objeto no banco de dados, Você tem que chamar save() explicitamente. >>> p.save() # Agora você tem uma ID. Note que poderá aparecer "1L" ao invés de "1", # isto depende muito da base de dados que você utiliza. Não é uma falha; # isto significa que o backend de seu banco de dados prefere # rodar os números inteiros como objetos do tipo inteiro longo do Python. >>> p.id 1 # Acesse as colunas da Base de Dados via Atributos do Python. >>> p.question "What's up?" >>> p.pub_date datetime.datetime(2005, 7, 15, 12, 00, 53) # Mude os valores modificando os atributos, chamando a função save(). >>> p.pub_date = datetime(2005, 4, 1, 0, 0) >>> p.save() # objects.all() mostra todas as votações da base de dados. >>> Poll.objects.all() []

Espere um minuto. é uma representação inutil. Vamos corrigir isto editando o modelo de votações(dentro da pasta "polls/models.py") e colocando o método __str__() nas classes Poll e Choice.

class Poll(models.Model): # ... def __str__(self): return self.question class Choice(models.Model): # ... def __str__(self): return self.choice

É importante adicionar o método __str__() aos seus modelos, não somente para o seu próprio bem-estar além de que você pode utilizar o console interativo, mas também porque as representações dos objetos são utilizadas também na interface de administração auto-gerenciada do Django. Observe que estes são métodos Padrões do Python. Vamos adicionar o nosso próprio método. Apenas para uma demonstração.

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

Observe adicão do import datetime que referencia o módulo padrão de Python datetime. Voltemos ao shell interativo do Python e executemos os seguintes comandos: python manage.py shell

>>> from mysite.polls.models import Poll, Choice # Verifique que nosso novo método __str__() funciona. >>> Poll.objects.all() [Poll: What's up?] # Django fornece uma rica API de busca dentro do Banco de Dados que é inteiramente # gerenciado por palavras-chaves. >>> Poll.objects.filter(id=1) [Poll: What's up?] >>> Poll.objects.filter(question__startswith='What') [Poll: What's up?] # Pegue a votação do ano de 2005 ou do ano em curso. >>> Poll.objects.get(pub_date__year=2005) Poll: What's up? >>> Poll.objects.get(id=2) Traceback (most recent call last): ... DoesNotExist: Poll matching query does not exist. # A pesquisa por palavra-chave é o caso mais comum, onde o Django fornece um # atalho para uma pesquisa exata do termo chave. # O seguinte é identico ao Poll.objects.get(id=1). >>> Poll.objects.get(pk=1) Poll: What's up? # Verifique que o nosso método funciona. >>> p = Poll.objects.get(pk=1) >>> p.was_published_today() False # Dê uma lista de escolhas Choice(Escolha) a uma Votação. Crie e construa # um novo objeto Escolha(Choice), faça uma instrução INSERT, adicione a escolha # junto coma s escolhas disponíveis e retorne um novo objeto Escolha(Choice). >>> p = Poll.objects.get(pk=1) >>> p.choice_set.create(choice='Not much', votes=0) >>> p.choice_set.create(choice='The sky', votes=0) >>> c = p.choice_set.create(choice='Just hacking again', votes=0) # Os objetos Escolha(Choice) são uma API de acesso aos objetos Votação(Poll) >>> c.poll Poll: What's up? # E vice-versa: os objetos Votação(Poll) são acessados pelos Objetos Escolhas(Choice). >>> p.choice_set.all() [, , ] >>> p.choice_set.count() 3 # A API segue automaticamente os relacionamentos determinados. # Utilize um duplo underscore para separar relacionamentos. # Isto funciona até o nível de de complexidade que você quiser. # Não há limite. Encontre todas as escolhas para qualquer votação no pub_date de 2005. >>> Choice.objects.filter(poll__pub_date__year=2005) [, , ] # Vamos deletar uma Escolha(choice). Use o método delete() para isto. >>> c = p.choice_set.filter(choice__startswith='Just hacking') >>> c.delete()

Bem pessoal no próximo post estarei colocando o segundo tutorial do Django. Abraço!