Aplicações¶
Django contém um registro de aplicações instaladas que armazena configuração e fornece introspecção. Ele também mantem uma lista de modelos </topics/db/models disponíveis.
Esse registro é simplesmente chamado apps
e está disponível em django.apps
:
>>> from django.apps import apps
>>> apps.get_app_config('admin').verbose_name
'Admin'
Projetos e aplicações¶
O termo project descreve uma aplicação web Django. O pacote de projeto Python é definido primariamente por um módulo de configuração, que geralmente contêm outras coisas. Por exemplo, quando você executa django-admin startproject mysite
você criará um diretório de projeto mysite
que contêm o pacote Python mysite
com os módulos settings.py
, urls.py
, and wsgi.py
. O pacote do projeto geralmente é extendido para incluir coisas como fixtures, CSS e templates que não estão atrelados a nenhuma aplicação em particular.
O project’s root directory (aquele que contêm manage.py
) é geralmente o container de todas as aplicações do projeto que não estão instaladas separadamente.
O termo application descreve um pacote Python que prove alguns conjunto de recursos. Aplicativos devem ser reutilizados em projetos diferentes.
Aplicações abrigam combinações de modelos, views, templates, templates tags, static files, URLs, middleware, etc. Estas são comumente ligados ao projeto na definição INSTALLED_APPS
e opcionalmente em outros mecanismos como URLconfs, a definição MIDDLEWARE
, ou por herança de templates.
É importante entender que uma aplicação Django é apenas um conjunto de código que interage com várias partes do framework. Não existe um objeto Application
propriamente dito. Entretanto, existem alguns lugares onde o Django precisa interagir com estas aplicações instaladas, geralmente para configuração e introspecção. É por isso que o registro de aplicações mantém os metadados em uma instância AppConfig
para cada aplicação instalada.
Não existe nenhuma restrição que defina que um pacote de projeto não possa ser considerado uma aplicação e tenha seus próprios modelos, etc. (seria necessário adicionar a INSTALLED_APPS
).
Configurandos as aplicações¶
Para configurar uma aplicação, herde AppConfig
e coloque um caminho pontuado a essa subclasse em INSTALLED_APPS
.
Quando um INSTALLED_APPS
contém um caminho pontuado para um módulo de aplicação, o Django procura pela váriavel default_app_config
naquele módulo.
Caso esteja definido, é o caminho em notação de ponto até a AppConfig
subclasse para aquela aplicação.
Se não existir uma variável default_app_config
, o Django usa a classe padrão AppConfig
.
default_app_config
permite que aplicações que antecedem ao Django 1.7 tais como django.contrib.admin
utilizem o recurso AppConfig
sem necessitar que o usuário atualize seus INSTALLED_APPS
.
Novas aplicações devem evitar default_app_config
. Ao invés disso, eles deveriam usar um caminho pontuado para a subclasse de AppConfig
apropriada para ser configurada explicitamente nas INSTALLED_APPS
.
Para autores de aplicações¶
Se você está criando uma app plugável chamada “Rock ‘n’ roll”, aqui está como você poderia prover um nome apropriado para o admin:
# rock_n_roll/apps.py
from django.apps import AppConfig
class RockNRollConfig(AppConfig):
name = 'rock_n_roll'
verbose_name = "Rock ’n’ roll"
Você pode fazer sua aplicação carregar esta subclase AppConfig
por padrão da seguinte maneira:
# rock_n_roll/__init__.py
default_app_config = 'rock_n_roll.apps.RockNRollConfig'
Isso irá fazer com que RockNRollConfig
seja usada quando INSTALED_APPS
contenha apenas 'rock_n_roll'
. Isso lhe permite o uso das funcionalidades da AppConfig
sem obrigar seus usuários a atualizar sua configuração INSTALLED_APPS
. Além desse caso de uso, é melhor evitar usar default_app_config
and ao invés disso especificar a classe de configuração de app na INSTALLED_APPS
como descrito a seguir.
Com certeza você pode orientar seus usuários a colocar 'rock_n_roll.apps.RockNRollConfig'
em sua configuração INSTALLED_APPS
. Você pode até prover algumas subclasses AppConfig
diferentes com diferentes comportamentos e permitir seus usuários escolherem um via sua configuração INSTALLED_APPS
.
A convenção recomendado é colocar a classe de configuração em um submódulo da aplicação chamada “apps”. No entento, isto não é imposto pelo Django.
Você deve incluir name
atributo do Djando para determinar qual aplicação essa configuração se aplica. Você pode defenir qualquer atributo documentado na API referência AppConfig
Nota
Se o seu código importa o registro de aplicações no __init__.py
da aplicação, o nome apps
irá conflitar com o sub-módulo apps
. A melhor prática é mover esse código para um sub-módulo e importá-lo. Uma alternativa é importar o registro com um nome diferente:
from django.apps import apps as django_apps
Para usuários de aplicações¶
Se você está usando “Rock ’n’ roll” em um projeto chamado anthology
, mas quer mostrá-lo como “Jazz Manouche”, você pode fornecer sua própria configuração:
# anthology/apps.py
from rock_n_roll.apps import RockNRollConfig
class JazzManoucheConfig(RockNRollConfig):
verbose_name = "Jazz Manouche"
# anthology/settings.py
INSTALLED_APPS = [
'anthology.apps.JazzManoucheConfig',
# ...
]
Novamente, definir classes de configuração de um projeto específico em um sub-módulo chamado apps
é uma convenção, não é requerido.
Configuração da aplicação¶
-
class
AppConfig
[código fonte]¶ Objetos de configuração de uma aplicação armazenam meta-dados para uma aplicacão. Alguns atributos podem ser configurados nas subclasses
AppConfig
. Outros são definidos pelo Django e são somente para leitura.
Atributos configuráveis¶
-
AppConfig.
name
¶ O caminho completo para do Python para a aplicação, exemplo:
'django.contrib.admin'
.Este atributo define a qual aplicação a configuração se aplica. deve ser definido em todas as subclasses de
AppConfig
.Ele deve ser único dentro de todo o projeto Django.
-
AppConfig.
label
¶ Nome curto para a aplicação, ex.
'admin'
Este atributo permite trocar o rótulo de uma aplicação quando duas aplicações tem rótulos conflitantes. Seu valor padrão é um último componente de
name
. ELe deve ser uma identificador Python válido.Ele deve ser único dentro de todo o projeto Django.
-
AppConfig.
verbose_name
¶ Nome legível para a aplicação, ex. “Administração”.
O atributo padrão para `` label.title()``.
-
AppConfig.
path
¶ Caminho no sistema de arquivo para o diretório da aplicação , ex.: ‘/usr/lib/python3.4/dist-packages/django/contrib/admin’`.
Na maioria dos casos, o Django pode automaticamente detectar e definir isso, mas você pode explicitamente sobrepor como um atributo de classe na sua sublcasse de
AppConfig
. Em alguma situações isso é requerido; por exemplo se o pacote da aplicação é um namespace package com míltiplos caminhos.
Atributos somente leitura¶
-
AppConfig.
module
¶ Módulo raiz para a aplicação, ex.: <module ‘django.contrib.admin’ from ‘django/contrib/admin/__init__.pyc’>`.
-
AppConfig.
models_module
¶ Módulo contendo os módelos, ex.:
<module 'django.contrib.admin.models' from 'django/contrib/admin/models.pyc'>
.Isso pode ser
None
se a aplicação nao contém um módulomodels
. Note que os sinais relacionados com o banco de dados tal comopre_migrate
epost_migrate
somente são emitidos por aplicações que conténham o módulomodels
.
Métodos¶
-
AppConfig.
get_models
()[código fonte]¶ Retornar um iterável de classes
Model
para esta aplicação.Requer que o registro do aplicativo esteja totalmente povoado.
-
AppConfig.
get_model
(model_name, require_ready=True)[código fonte]¶ Retorna a
Model
com o nome dadomodel_name
.model_name
é insensível à capitularização -case-insensitive-.Resultará em :exc:’LookupError’ se esse modelo não existir na aplicação.
Requer o registro da aplicação para ser populado totalmente, a não ser que o argumento
require_ready
esteja definido comoFalse
.require_ready
se comporta exatamente como emapps.get_model()
.New in Django 1.11:O arqgumento
require_ready
foi adicionado.
-
AppConfig.
ready
()[código fonte]¶ Subclasses podem substituir este método para realizar tarefas de inicialização tal como registrar “signals”. Ele é chamado tão logo o registro seja populado.
Entretanto você não pode importar modelos a nível de modulo onde as classes
AppConfig
são definidas, você pode faze-lo inready()`, usando tanto uma instrução de ``import
ouget_model()
.Se estiver registrando
model signals
, você pode referenciar o emissor por um rotulo string ao invés da classe do modeloExemplo
from django.db.models.signals import pre_save def ready(self): # importing model classes from .models import MyModel # or... MyModel = self.get_model('MyModel') # registering signals with the model's string label pre_save.connect(receiver, sender='app_label.MyModel')
Aviso
Embora você possa acessar classes de modelo como descrito acima, evite interagir co o banco de dados dentro da implementação do seu
ready()
. Isso inclui métodos de modelos que executam “queries” (save()
,delete()
, métodos de gerenciamento e etc.), e também “queries” SQL explicitas através dodjango.db.connection
. Seu métodoready()
irá rodar durante o início de cada comando de gerenciamento. Por exemplo, apesar de a configuração do banco de dados de teste ser separado das definições de produção, omanage.py test
ainda poderia executar algumas “queries” no seu banco de dados de produção.Nota
No processo de inicialização normal, o método
ready
somente é chamado uma vez pelo Django. Mas em alguns casos excepcionais, particularmente em testes os quais estão mexendo com aplicações instaladas, oready
talvez seja chamado mais de uma vez. Neste caso, ou escreva métodos indepotentes, ou coloque um indicador nas suas classesAppConfig
para prevenir re-executar código o qual deveria rodar exatamente uma vez.
Pacotes de espaço de nomes como apps (Python 3.3+)¶
As versões de Python 3.3 ou maiores suportam pacotes Python sem um arquivo “__init__.py”. Estes pacotes são cohecidos como “pacotes de espaço de nomes” e podem ser distribuídos em vários diretórios em diferentes locais no sys.path
(see PEP 420).
Aplicações Django requerem um único caminho baseado no sistema de arquivos onde o Django (dependendo da configuração) irá procurar por templates, ativos estáticos, etc. Sendo assim, pacotes de espaço de nomes podem ser aplicações Django somente se uma das seguintes for verdadeiro:
- O pacote de espaço de nome tem na verdade somente um localização (ex.: não está distribuído em mais de um diretório)
- A classe
AppConfig
usada para configurar a aplicação tem um atributo de classepath
, o qual é o caminho absoluto do diretório que o Django irá usar como o único caminho básico para a aplicação.
Se nenhuma destas condições forem atendidas, Django irá emitir um erro ImproperlyConfigured
.
Registro do Aplicativo¶
-
apps
¶ O registro da aplicação fornece a seguinte API pública. Métodos que não estão listados abaixo são considerados privados e talvez mudem sem serem noticiados.
-
apps.
ready
¶ Atributo booleano que é passado para
True
depois que o registro está totalmente populado e todos os métodosAppConfig.ready()
são chamados.
-
apps.
get_app_config
(app_label)¶ Retorna uma
AppConfig
para a aplicação com o dadoapp_label
. Emite um erroLookupError
se tal aplicação não existir.
-
apps.
is_installed
(app_name)¶ Verifique se uma aplicação com o dado nome existe no registro.
app_name
é o nome completo da app, exemplo'django.contrib.admin'
.
-
apps.
get_model
(app_label, model_name, require_ready=True)¶ Retorna a
Model
com o dadoapp_label
e``model_name``. Como um atalho, esse método também aceita um simples argumento na forma deapp_label.model_name
.model_name
é case-insensitive, ou seja, não diferencia maiúsculas e minúsculas.Emite
LookupError
se a tal aplicação ou modelo não existir. EmiteValueError
quando chamado com um argumento único que não contém exatamente um ponto.Requer o registro da aplicação para ser populado totalmente, a não ser que o argumento
require_ready
esteja definido comoFalse
.Definindo o
require_ready
paraFalse
permite procurar por padrões :ref:` enquanto o registro da aplicação esta sendo preenchido <app-loading-process>`, especificamente durante a segunda fase onde ele importa os modelos/padroes. Entãoget_model()
têm o mesmo efeito de importar um modelo. O caso de uso principal é para configurar as classes de modelo com configurações, comoAUTH_USER_MODEL
.When
require_ready
isFalse
,get_model()
returns a model class that may not be fully functional (reverse accessors may be missing, for example) until the app registry is fully populated. For this reason, it’s best to leaverequire_ready
to the default value ofTrue
whenever possible.New in Django 1.11:O arqgumento
require_ready
foi adicionado.
Processo de Inicialização¶
Como as aplicações são carregadss¶
Quando o Django inicia, a django.setup()
é responsável por popular o registro da aplicação.
-
setup
(set_prefix=True)[código fonte]¶ Configura o Django através:
- Carregando configurações
- Configurando o “logging”.
- Se
set_prefix
é igual a True, definindo o prefixo do escript que resolve URL paraFORCE_SCRIPT_NAME
se estiver definido, ou caso contrário para/
. - Inicializando o registro do aplicativo.
Changed in Django 1.10:A capacidade de determinar o prefixo do script tradutor de URL é nova.
Essa função é chamada automáticamente.
- Quando rodar um servidor HTTP via suporte WSGI do Django.
- Quando invocar um comando de gerenciamento.
Ele deve ser chamado explicitamente em outros casos, por exemplo em scripts Python.
O registro da aplicaçào é inicializado em três estágios. Em cada estágio, o Django processa todas as aplicações na ordem que estÃo em INSTALLED_APPS
.
Primeiro Django importa cada item que está no
INSTALLED_APPS
.Se ele é uma class de configuração de aplicação, o Django importa a raiz do pacote da aplicação, definida pelo seu atributo
name
. Se for um pacote Python, o Django cria uma configuração de aplicação padrão.Neste momento, seu código não deveria importar nenhum modelo!
Em outras opalavras, os pacotes da raiz da sua aplicação e os módulos que definem sua classes de configuração da aplicação não deveriam importar nenhum modelo, mesmo que indiretamente.
Falando estritamente, o Django permite importar modelos uma vez que a aplicação de configuração está carregada. No entanto , a fim de evitar limitações desnecessárias na ordem definida em
INSTALLED_APPS
, recomendamos fortemente não importar qualquer modelo neste estágio.Uma vez que este estágio se complete, as APIs que manipulam as configurações da aplicação tal como
get_app_config()
se tornam disponíveis.Então o Django tenta importar o submódulo
models
de cada aplicação, se houver uma.Você deve definir ou importar todos os modelos no seu
models.py
ou nomodels/__init__.py
da sua aplicação. De outtro modo, o registro da aplicação talvez não seja totalmente populado neste ponto, o que pode causar um malfuncionamento do ORM.Uma vez que este estágio esteja completo, as APIs que operam nos modelos tal como
get_model()
se tornam usáveis.Finalmente o Django executa o método
ready()
de cada configuração da aplicação.
Solução de Problemas¶
Aqui estão alguns problemas comuns que você talvez encontre durante a inicialização:
AppRegistryNotReady
: This happens when importing an application configuration or a models module triggers code that depends on the app registry.Por exemplo,
ugettext()
usa o registro da app para procurar por catálogos de tradução em aplicações. Para traduzir durante o tempo de importação, você precisa ao invés deugettext_lazy()
. (Usar ougettext()
pode gerar bug, porque a tradução deveria acontecer no tempo de importação, ao invés de em cada request dependendo da linguagem ativa.)Executar as queries de banco de dados com o ORM em tempo de importação nos módulo de modelos também irá disparar a mesma exceção. O ORM não pode funcionar devidamente até que todos os modelos estejam disponíveis.
Essa exceção também acontece se você chamar
django.setup()
em um script Python autônomo.ImportError: cannot import name ...
Isso acontece se a sequência de importação termina em um loop.Para eliminar tais problemas, você deve minimizar a dependências entre seus módulos de modelos e fazer o menos possível durante o tempo de importação. Para evitar a execução de código em tempo de imporatação você pode move-lo para uma função e cachear seus resultados. O código será executado quando você precisar dos resultados pela primeira vez. Este conceito é conhecido como “avaliação preguiçosa”.
django.contrib.admin
automaticamene realiza a auto-descoberta od módulos doadmin
nas aplicações instaladas. Para impedir isso, altere seuINSTALLED_APPS
para que contenha o'django.contrib.admin.apps.SimpleAdminConfig'
ao invés do'django.contrib.admin'
.