--- title: "Aplicações" version: 3.2 locale: pt-br source: https://docs.djangoproject.com/pt-br/3.2/ref/applications/ canonical: https://djangodocs.dev/pt-br/3.2/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 'Administration' ``` ## 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`, e `wsgi.py`. O pacote do projeto geralmente é extendido para incluir outras coisas como fixtures, CSS e templates que não estão atrelados à 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/3.2/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/3.2/ref/settings/#std-setting-INSTALLED_APPS) e opcionalmente em outros mecanismos como URLconfs, a definição [`MIDDLEWARE`](/pt-br/3.2/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/3.2/ref/settings/#std-setting-INSTALLED_APPS)). ## Configurandos as aplicações To configure an application, create an `apps.py` module inside the application, then define a subclass of [`AppConfig`](#django.apps.AppConfig) there. When [`INSTALLED_APPS`](/pt-br/3.2/ref/settings/#std-setting-INSTALLED_APPS) contains the dotted path to an application module, by default, if Django finds exactly one [`AppConfig`](#django.apps.AppConfig) subclass in the `apps.py` submodule, it uses that configuration for the application. This behavior may be disabled by setting [`AppConfig.default`](#django.apps.AppConfig.default) to `False`. If the `apps.py` module contains more than one [`AppConfig`](#django.apps.AppConfig) subclass, Django will look for a single one where [`AppConfig.default`](#django.apps.AppConfig.default) is `True`. Se a subclasse [`AppConfig`](#django.apps.AppConfig) não for encontrada, a classe base [`AppConfig`](#django.apps.AppConfig) será usada. Alternatively, [`INSTALLED_APPS`](/pt-br/3.2/ref/settings/#std-setting-INSTALLED_APPS) may contain the dotted path to a configuration class to specify it explicitly: ``` INSTALLED_APPS = [ ... 'polls.apps.PollsAppConfig', ... ] ``` ### 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" ``` `RockNRollConfig` will be loaded automatically when [`INSTALLED_APPS`](/pt-br/3.2/ref/settings/#std-setting-INSTALLED_APPS) contains `'rock_n_roll'`. If you need to prevent this, set [`default`](#django.apps.AppConfig.default) to `False` in the class definition. You can provide several [`AppConfig`](#django.apps.AppConfig) subclasses with different behaviors. To tell Django which one to use by default, set [`default`](#django.apps.AppConfig.default) to `True` in its definition. If your users want to pick a non-default configuration, they must replace `'rock_n_roll'` with the dotted path to that specific class in their [`INSTALLED_APPS`](/pt-br/3.2/ref/settings/#std-setting-INSTALLED_APPS) setting. The [`AppConfig.name`](#django.apps.AppConfig.name) attribute tells Django which application this configuration applies to. You can define any other attribute documented in the [`AppConfig`](#django.apps.AppConfig) API reference. [`AppConfig`](#django.apps.AppConfig) subclasses may be defined anywhere. The `apps.py` convention merely allows Django to load them automatically when [`INSTALLED_APPS`](/pt-br/3.2/ref/settings/#std-setting-INSTALLED_APPS) contains the path to an application module rather than the path to a configuration class. > **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 > ``` > **Changed in Django 3.2** > > In previous versions, a `default_app_config` variable in the application > module was used to identify the default application configuration class. ### 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', # ... ] ``` This example shows project-specific configuration classes located in a submodule called `apps.py`. This is a convention, not a requirement. [`AppConfig`](#django.apps.AppConfig) subclasses may be defined anywhere. In this situation, [`INSTALLED_APPS`](/pt-br/3.2/ref/settings/#std-setting-INSTALLED_APPS) must contain the dotted path to the configuration class because it lives outside of an application and thus cannot be automatically detected. ## 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/pythonX.Y/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. #### `AppConfig.default` > **New in Django 3.2** Set this attribute to `False` to prevent Django from selecting a configuration class automatically. This is useful when `apps.py` defines only one [`AppConfig`](#django.apps.AppConfig) subclass but you don’t want Django to use it by default. Set this attribute to `True` to tell Django to select a configuration class automatically. This is useful when `apps.py` defines more than one [`AppConfig`](#django.apps.AppConfig) subclass and you want Django to use one of them by default. Por padrão, este atributo não é definido. #### `AppConfig.default_auto_field` > **New in Django 3.2** The implicit primary key type to add to models within this app. You can use this to keep [`AutoField`](/pt-br/3.2/ref/models/fields/#django.db.models.AutoField) as the primary key type for third party applications. Por padrão, este é o valor de [`DEFAULT_AUTO_FIELD`](/pt-br/3.2/ref/settings/#std-setting-DEFAULT_AUTO_FIELD). ### Atributos somente leitura #### `AppConfig.module` Root module for the application, e.g. ``. #### `AppConfig.models_module` Módulo contendo os models, e.g. ``. 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/3.2/ref/signals/#django.db.models.signals.pre_migrate) e [`post_migrate`](/pt-br/3.2/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/3.2/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/3.2/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). #### `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/3.2/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.apps import AppConfig from django.db.models.signals import pre_save class RockNRollConfig(AppConfig): # ... 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/3.2/ref/models/instances/#django.db.models.Model.save), [`delete()`](/pt-br/3.2/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. ### Namespace packages as apps Pacotes Python sem o “\_\_init\_\_.py” são conhecidos como “namespace packages” e podem estar espalhados entre multiplos diretorios em locais diferentes em “sys.path” (veja :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: 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/3.2/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/3.2/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/3.2/ref/settings/#std-setting-AUTH_USER_MODEL). Quando `require_ready` é `False`, `get_model()` retorna uma classe de modelo que talvez não seja totalmente funcional (acessores reversos podem estar faltando, por exemplo) enquanto o registro do app não está completo. Por isso, é melhor deixar `require_ready` com seu valor padrão `True` sempre que possível. ## 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/3.2/ref/settings/#std-setting-FORCE_SCRIPT_NAME) se estiver definido, ou caso contrário para `/`. - Inicializando o registro do aplicativo. 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/3.2/ref/settings/#std-setting-INSTALLED_APPS). 1. Primeiro Django importa cada item que está no [`INSTALLED_APPS`](/pt-br/3.2/ref/settings/#std-setting-INSTALLED_APPS). If it’s an application configuration class, Django imports the root package of the application, defined by its [`name`](#django.apps.AppConfig.name) attribute. If it’s a Python package, Django looks for an application configuration in an `apps.py` submodule, or else creates a default application configuration. *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/3.2/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/3.2/ref/exceptions/#django.core.exceptions.AppRegistryNotReady): Isso acontece quando se importa uma configuração de aplicação ou um módulo de um modelo que aciona um código que depende do registro do app. For example, [`gettext()`](/pt-br/3.2/ref/utils/#django.utils.translation.gettext) uses the app registry to look up translation catalogs in applications. To translate at import time, you need [`gettext_lazy()`](/pt-br/3.2/ref/utils/#django.utils.translation.gettext_lazy) instead. (Using [`gettext()`](/pt-br/3.2/ref/utils/#django.utils.translation.gettext) would be a bug, because the translation would happen at import time, rather than at each request depending on the active language.) 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/3.2/ref/settings/#std-setting-INSTALLED_APPS) para que contenha o `'django.contrib.admin.apps.SimpleAdminConfig'` ao invés do `'django.contrib.admin'`.