Criando uma aplicação Django reutilizável
Links da documentação oficial:
https://docs.djangoproject.com/pt-br/1.11/intro/reusable-apps/
Para baixar o código como está até agora, acesse o meu github no link abaixo:
https://github.com/toticavalcanti/django_course/tree/make_polls_package
Criando uma aplicação reutilizável
Vamos transformar nossa app web em um pacote Python autônomo que você pode reutilizar em novos projetos e compartilhar com outras pessoas.
REUTILIZAÇÃO IMPORTA
É um grande trabalho projetar, contruir, testar e manter uma aplicação web. Muitos projetos Python e Django compartilham problemas em comum, que tal economizar um pouco de trabalho repetido?
A reutilização é o modo de vida em Python e de projetos de software em geral.
Pra que reinventar a roda?
PACOTE? APLICAÇÃO?
Um pacote Python fornece uma maneira de agrupar códigos Python relacionados para fácil reutilização.
Um pacote contém um ou mais arquivos de códigos Python (também conhecidos como “módulos”).
Um pacote pode ser importado com:
import foo.bar
ou
from foo import bar
Para um diretório como polls formar um pacote, ele deve conter um arquivo especial __init__.py, mesmo se este arquivo estiver vazio.
Uma aplicação Django é apenas um pacote Python que é especificamente destinado para uso em um projeto Django.
Uma aplicação pode usar convenções comuns do Django, tais como ter submódulos models, tests, urls, e views.
Estrutura da App Django
Você criou mysite/templates na parte 7 do Tutorial, e polls/templates na 3.
Talvez agora fique caro porque escolhemos separar o diretório de templates do de projeto e aplicação: tudo que é parte da aplicação “polls” está em polls. Isso torna a aplicação auto contida e facilita adicioná-la em um novo projeto.
O diretório polls pode agora ser copiado em um novo projeto Django e ser reusado, embora não esteja pronta para ser publicada. Para isso, precisamos empacotar a aplicação para tornar fácil para outros instalarem.
INSTALANDO ALGUNS PRÉ-REQUISITOS
Vamos usar o setuptools para construir nosso pacote.
É a ferramenta de empacotamento recomendada!
Vamos usar o pip também, para instalar e desinstalar.
Vamos usar o setuptools para construir nosso pacote.
É a ferramenta de empacotamento recomendada!
Vamos usar o pip também, para instalar e desinstalar.
Empacotando sua aplicação
Empacotamento Python refere-se a preparar sua aplicação num formato específico que possa ser facilmente instalado e usado. O próprio Django é empacotado de uma maneira muito parecida.
Para aplicações pequenas, como a de enquetes, esse processo não é tão difícil.
1. Primeiro crie um diretório pai para polls, fora do seu projeto Django. Nomeie esse diretório de django-polls
Escolhendo um nome para a sua aplicaçãoQuando for escolher um nome para o seu pacote, cheque fontes como PyPI para evitar conflitos de nomes com pacotes existentes.
Ao criar um pacote para distribuir, geralmente é útil prefixar django- ao nome do seu módulo. Isso ajuda outros que estão procurando por aplicação Django identificarem sua aplicação como uma específica do Django.
Label da aplicação (isto é, a parte final do caminho pontilhado para os pacotes da aplicação) deve ser único no INSTALLED_APPS.
Evite usar o mesmo rótulo como os do pacote contrib do Django, por exemplo auth, admin, ou messages.
2. Mova o diretório polls para dentro do diretório django-polls.
3. Crie um arquivo django-polls/README.rst com o seguinte conteúdo:
django-polls/README.rst
=====
Polls
=====
Polls is a simple Django app to conduct Web-based polls. For each
question, visitors can choose between a fixed number of answers.
Detailed documentation is in the "docs" directory.
Quick start
-----------
1. Add "polls" to your INSTALLED_APPS setting like this::
INSTALLED_APPS = [
...
'polls',
]
2. Include the polls URLconf in your project urls.py like this::
url(r'^polls/', include('polls.urls')),
3. Run `python manage.py migrate` to create the polls models.
4. Start the development server and visit http://127.0.0.1:8000/admin/
to create a poll (you'll need the Admin app enabled).
5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
4. Crie um arquivo django-polls/LICENSE. Escolher uma licença está fora do escopo deste tutorial, mas é suficiente dizer que código distribuído publicamente sem uma licença é inútil. Djando e muitas aplicações compatíveis com o Django são distribuídas sob a licença BSD; no entanto, você é livre para escolher sua própria licença. Apenas esteja ciente que a escolha da sua licença afetará quem pode usar seu código.
Você poderá usar esse exemplo abaixo de LICENSE:
The MIT License (MIT)
Copyright (c) Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
5. Como próximo passo iremos criar um arquivo setup.py o qual fornece detalhes sobre como construir e instalar a “app”. Um explicação completa sobre este arquivo está fora do escopo deste tutorial, mas o documento setuptools docs tem uma boa explicação. Crie um arquivo django-polls/setup.py com o seguinte conteúdo:
django-polls/setup.py
import os
from setuptools import find_packages, setup
with open(os.path.join(os.path.dirname(__file__), 'README.rst')) as readme:
README = readme.read()
# allow setup.py to be run from any path
os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir)))
setup(
name='django-polls',
version='0.1',
packages=find_packages(),
include_package_data=True,
license='BSD License', # example license
description='A simple Django app to conduct Web-based polls.',
long_description=README,
url='https://www.example.com/',
author='Your Name',
author_email='yourname@example.com',
classifiers=[
'Environment :: Web Environment',
'Framework :: Django',
'Framework :: Django :: X.Y', # replace "X.Y" as appropriate
'Intended Audience :: Developers',
'License :: OSI Approved :: BSD License', # example license
'Operating System :: OS Independent',
'Programming Language :: Python',
# Replace these appropriately if you are stuck on Python 2.
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.4',
'Programming Language :: Python :: 3.5',
'Topic :: Internet :: WWW/HTTP',
'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
],
)
6. Por padrão, apenas módulos e pacotes Python são incluídos no pacote. Para incluir arquivos adicionais, precisaremos criar um arquivo MANIFEST.in. A documentação do setuptools citada no passo anterior, fala deste arquivo em mais detalhes. Para incluir o templates, o README.rst e nosso arquivo LICENSE, crie um arquivo django-polls/MANIFEST.in com o seguinte conteúdo:
include LICENSE
include README.rst
recursive-include polls/static *
recursive-include polls/templates *
7. É opcional, mas recomendado, incluir uma documentação detalhada com sua aplicação. Crie um diretório django-polls/docs vazio, para futura documentação. Adicione uma linha a mais ao django-polls/MANIFEST.in:
recursive-include docs *
Veja que o diretório docs não será incluído no seu pacote a menos que você adicione alguns arquivos à ele.
Muitas aplicações Django fornecem sua documentação online através de sites como readthedocs.org
8. Dentro da pasta django-polls, crie seu pacote com:
python setup.py sdist
execute dentro do diretório django-polls.
Caso dê erro por não ter o setuptools instalado, rode o comando abaixo para instalá-lo:
sudo apt-get install python setuptools
Esse comando cria um diretório chamado dist e cria seu novo pacote.
Utilizando o seu próprio pacote
Uma vez que movemos o diretório polls para fora do projeto, ele não funciona mais.
Vamos consertar isso agora ao instalar nosso novo pacote django-polls
Instalando uma biblioteca de usuário
Os passos a seguir instalam django-polls como uma biblioteca do usuário.
Instalação por usuário tem uma série de vantagens sobre a instalação do pacote em todo o sistema, tais como ser utilizável em sistemas onde você não tem acesso de administrador, bem como prevenir o pacote de afetar serviços do sistema e outros usuários da máquina.
Note que instalações por usuário pode ainda afetar o comportamento de ferramentas do sistema que são executados com esse usuário, então, o virtualenv pode ser a solução.
Se não tiver o pip instalado, rode o comando abaixo para instalar:
sudo apt-get install python pip
Agora vamos instalar o pacote, para isso, use o pip.
pip install --user /django-polls/dist/django-polls-0.1.tar.gz
Caso esteja usando um ambiente virtual, como é o caso desse tutorial, retire o –user do comando acima ficando assim:
pip install /django-polls/dist/django-polls-0.1.tar.gz
Caso dê erro, utilize o caminho absoluto:
pip install ~/django-polls/dist/django-polls-0.1.tar.gz
Outra opção que pode também ser usada:
pip install home/toticavalcanti/dist/django-polls-0.1.tar.gz
Com sorte, seu projeto Django deverá agora funcionar corretamente de novo.
Inicie o servidor novamente para confirmar.
Para desinstalar o pacote, use o pip:
pip uninstall ~/django-polls
Publicando sua aplicação
Agora que nós empacotamos e testamos django-polls, ele está pronto para ser compartilhado com o mundo! Se isso não foi apenas um exemplo, você pode agora:
Enviar o pacote por email para um amigo.
Enviar o pacote para seu site.
Poste o pacote em um repositório público, como o Python Package Index (PyPI). O packaging.python.org tem um bom tutorial para fazer isso.
Instalando pacotes Python com virtualenv
Anteriormente, nós instalamos nossa app de votação (Polls) como uma biblioteca de usuário. Isso tem algumas desvantagens:
Modificar as bibliotecas de usuário pode afetar outros softwares em Python do seu sistema.
Você não poderá rodar versões diferentes do seu pacote (ou outros pacotes com o mesmo nome).
Em geral, essas situações somente vem a tona quando se mantém vários projetos Django. Neste caso, a melhor solução é usar o virtualenv. Esta ferramenta permite que você mantenha múltiplos ambientes Python isolados, cada um com sua própria cópia de bibliotecas e “namespaces” de pacotes.
