--- title: "Aplicações" version: 1.11 locale: pt-br source: https://docs.djangoproject.com/pt-br/1.11/ref/applications/ canonical: https://djangodocs.dev/pt-br/1.11/ref/applications/ --- # 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 \>> 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](/pt-br/1.11/intro/reusable-apps/) 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`](/pt-br/1.11/ref/settings/#std-setting-INSTALLED_APPS) e opcionalmente em outros mecanismos como URLconfs, a definição [`MIDDLEWARE`](/pt-br/1.11/ref/settings/#std-setting-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`](#django.apps.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`](/pt-br/1.11/ref/settings/#std-setting-INSTALLED_APPS)). ## Configurandos as aplicações Para configurar uma aplicação, herde [`AppConfig`](#django.apps.AppConfig) e coloque um caminho pontuado a essa subclasse em [`INSTALLED_APPS`](/pt-br/1.11/ref/settings/#std-setting-INSTALLED_APPS). Quando um [`INSTALLED_APPS`](/pt-br/1.11/ref/settings/#std-setting-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`](#django.apps.AppConfig) subclasse para aquela aplicação. Se não existir uma variável `default_app_config`, o Django usa a classe padrão [`AppConfig`](#django.apps.AppConfig). `default_app_config` permite que aplicações que antecedem ao Django 1.7 tais como `django.contrib.admin` utilizem o recurso [`AppConfig`](#django.apps.AppConfig) sem necessitar que o usuário atualize seus [`INSTALLED_APPS`](/pt-br/1.11/ref/settings/#std-setting-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`](#django.apps.AppConfig) apropriada para ser configurada explicitamente nas [`INSTALLED_APPS`](/pt-br/1.11/ref/settings/#std-setting-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`](#django.apps.AppConfig) sem obrigar seus usuários a atualizar sua configuração [`INSTALLED_APPS`](/pt-br/1.11/ref/settings/#std-setting-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`](/pt-br/1.11/ref/settings/#std-setting-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`](/pt-br/1.11/ref/settings/#std-setting-INSTALLED_APPS). Você pode até prover algumas subclasses [`AppConfig`](#django.apps.AppConfig) diferentes com diferentes comportamentos e permitir seus usuários escolherem um via sua configuração [`INSTALLED_APPS`](/pt-br/1.11/ref/settings/#std-setting-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`](#django.apps.AppConfig.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`](#django.apps.AppConfig) > **Note** > > 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` Objetos de configuração de uma aplicação armazenam meta-dados para uma aplicacão. Alguns atributos podem ser configurados nas subclasses [`AppConfig`](#django.apps.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`](#django.apps.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`](#django.apps.AppConfig). Em alguma situações isso é requerido; por exemplo se o pacote da aplicação é um [namespace package](#namespace-package) com míltiplos caminhos. ### Atributos somente leitura #### `AppConfig.module` Módulo raiz para a aplicação, ex.: \\`. #### `AppConfig.models_module` Módulo contendo os módelos, ex.: ``. Isso pode ser `None` se a aplicação nao contém um módulo `models`. Note que os sinais relacionados com o banco de dados tal como [`pre_migrate`](/pt-br/1.11/ref/signals/#django.db.models.signals.pre_migrate) e [`post_migrate`](/pt-br/1.11/ref/signals/#django.db.models.signals.post_migrate) somente são emitidos por aplicações que conténham o módulo `models`. ### Métodos #### `AppConfig.get_models()` Retornar um iterável de classes [`Model`](/pt-br/1.11/ref/models/instances/#django.db.models.Model) para esta aplicação. Requer que o registro do aplicativo esteja totalmente povoado. #### `AppConfig.get_model(model_name, require_ready=True)` Retorna a [`Model`](/pt-br/1.11/ref/models/instances/#django.db.models.Model) com o nome dado `model_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 como `False`. `require_ready` se comporta exatamente como em [`apps.get_model()`](#django.apps.apps.get_model). > **New in Django 1.11** > > O arqgumento `require_ready` foi adicionado. #### `AppConfig.ready()` 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`](#django.apps.AppConfig) são definidas, você pode faze-lo in ```ready()`, usando tanto uma instrução de ``import``` ou [`get_model()`](#django.apps.AppConfig.get_model). Se estiver registrando [`model signals`](/pt-br/1.11/ref/signals/#module-django.db.models.signals), você pode referenciar o emissor por um rotulo string ao invés da classe do modelo Exemplo ``` 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') ``` > **Warning** > > Embora você possa acessar classes de modelo como descrito acima, evite interagir co o banco de dados dentro da implementação do seu [`ready()`](#django.apps.AppConfig.ready). Isso inclui métodos de modelos que executam “queries” ([`save()`](/pt-br/1.11/ref/models/instances/#django.db.models.Model.save), [`delete()`](/pt-br/1.11/ref/models/instances/#django.db.models.Model.delete), métodos de gerenciamento e etc.), e também “queries” SQL explicitas através do `django.db.connection`. Seu método [`ready()`](#django.apps.AppConfig.ready) 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, o `manage.py test` ainda poderia executar algumas “queries” no seu banco de dados de **produção**. > **Note** > > 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, o `ready` talvez seja chamado mais de uma vez. Neste caso, ou escreva métodos indepotentes, ou coloque um indicador nas suas classes `AppConfig` 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**](https://peps.python.org/pep-0420/)). 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: 1. 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) 2. A classe [`AppConfig`](#django.apps.AppConfig) usada para configurar a aplicação tem um atributo de classe [`path`](#django.apps.AppConfig.path), 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`](/pt-br/1.11/ref/exceptions/#django.core.exceptions.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étodos [`AppConfig.ready()`](#django.apps.AppConfig.ready) são chamados. #### `apps.get_app_configs()` Retorna um iterável de instancias de [`AppConfig`](#django.apps.AppConfig). #### `apps.get_app_config(app_label)` Retorna uma [`AppConfig`](#django.apps.AppConfig) para a aplicação com o dado `app_label`. Emite um erro [`LookupError`](https://docs.python.org/3/library/exceptions.html#LookupError) 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`](/pt-br/1.11/ref/models/instances/#django.db.models.Model) com o dado `app_label` e\`\`model\_name\`\`. Como um atalho, esse método também aceita um simples argumento na forma de `app_label.model_name`. `model_name` é case-insensitive, ou seja, não diferencia maiúsculas e minúsculas. Emite [`LookupError`](https://docs.python.org/3/library/exceptions.html#LookupError) se a tal aplicação ou modelo não existir. Emite [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) 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 como `False`. Definindo o `require_ready` para `False` permite procurar por padrões :ref:\` enquanto o registro da aplicação esta sendo preenchido \\`, especificamente durante a segunda fase onde ele importa os modelos/padroes. Então `get_model()` têm o mesmo efeito de importar um modelo. O caso de uso principal é para configurar as classes de modelo com configurações, como [`AUTH_USER_MODEL`](/pt-br/1.11/ref/settings/#std-setting-AUTH_USER_MODEL). When `require_ready` is `False`, `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 leave `require_ready` to the default value of `True` 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()`](#django.setup) é responsável por popular o registro da aplicação. #### `setup(set_prefix=True)` 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 para [`FORCE_SCRIPT_NAME`](/pt-br/1.11/ref/settings/#std-setting-FORCE_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`](/pt-br/1.11/ref/settings/#std-setting-INSTALLED_APPS). 1. Primeiro Django importa cada item que está no [`INSTALLED_APPS`](/pt-br/1.11/ref/settings/#std-setting-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`](#django.apps.AppConfig.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`](/pt-br/1.11/ref/settings/#std-setting-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()`](#django.apps.apps.get_app_config) se tornam disponíveis. 2. 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 no `models/__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()`](#django.apps.apps.get_model) se tornam usáveis. 3. Finalmente o Django executa o método [`ready()`](#django.apps.AppConfig.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`](/pt-br/1.11/ref/exceptions/#django.core.exceptions.AppRegistryNotReady): This happens when importing an application configuration or a models module triggers code that depends on the app registry. Por exemplo, [`ugettext()`](/pt-br/1.11/ref/utils/#django.utils.translation.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 de [`ugettext_lazy()`](/pt-br/1.11/ref/utils/#django.utils.translation.ugettext_lazy). (Usar o [`ugettext()`](/pt-br/1.11/ref/utils/#django.utils.translation.ugettext) 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()`](#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 do `admin` nas aplicações instaladas. Para impedir isso, altere seu [`INSTALLED_APPS`](/pt-br/1.11/ref/settings/#std-setting-INSTALLED_APPS) para que contenha o `'django.contrib.admin.apps.SimpleAdminConfig'` ao invés do `'django.contrib.admin'`.