--- title: "Aplicações" version: 4.2 locale: pt-br source: https://docs.djangoproject.com/pt-br/4.2/ref/applications/ canonical: https://djangodocs.dev/pt-br/4.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/4.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/4.2/ref/settings/#std-setting-INSTALLED_APPS) e opcionalmente em outros mecanismos como URLconfs, a definição [`MIDDLEWARE`](/pt-br/4.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/4.2/ref/settings/#std-setting-INSTALLED_APPS)). ## Configurandos as aplicações Para configurar uma aplicação, crie um modulo “apps.py” dentro da aplicação, então defina a subclasse do [`AppConfig`](#django.apps.AppConfig) lá. Quando [`INSTALLED_APPS`](/pt-br/4.2/ref/settings/#std-setting-INSTALLED_APPS) contém o caminho pontilhado para um módulo de aplicativo, por padrão, se o Django encontra exatamente uma subclasse [`AppConfig`](#django.apps.AppConfig) no submódulo \`\` apps.py\`\`, este usa aquela configuração para o aplicativo. Este comportamento pode ser desabilitado definindo [`AppConfig.default`](#django.apps.AppConfig.default) como `False`. Se o módulo `apps.py` contiver mais de uma subclasse [`AppConfig`](#django.apps.AppConfig), o Django irá procurar por uma única onde [`AppConfig.default`](#django.apps.AppConfig.default) é `True`. Se a subclasse [`AppConfig`](#django.apps.AppConfig) não for encontrada, a classe base [`AppConfig`](#django.apps.AppConfig) será usada. Alternativamente, [`INSTALLED_APPS`](/pt-br/4.2/ref/settings/#std-setting-INSTALLED_APPS) pode conter o caminho pontilhado para uma classe de configuração para especificá-lo explicitamente: ``` 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` será carregado automaticamente se o [`INSTALLED_APPS`](/pt-br/4.2/ref/settings/#std-setting-INSTALLED_APPS) contiver `'rock_n_roll'`. Se você precisa evitar isso, defina [`default`](#django.apps.AppConfig.default) como `False` na definição da classe. Você pode fornecer várias subclasses [`AppConfig`](#django.apps.AppConfig) com comportamentos diferentes. Para dizer ao Django qual usar por padrão, defina [`default`](#django.apps.AppConfig.default) como `True` em sua definição. Se seus usuários quiserem escolher uma configuração não padrão, eles devem substituir `'rock_n_roll'` pelo caminho pontilhado para essa classe específica em sua configuração [`INSTALLED_APPS`](/pt-br/4.2/ref/settings/#std-setting-INSTALLED_APPS). O atributo [`AppConfig.name`](#django.apps.AppConfig.name) diz ao Django a qual aplicativo esta configuração se aplica. Você pode definir qualquer outro atributo documentado na referência da API [`AppConfig`](#django.apps.AppConfig). As subclasses [`AppConfig`](#django.apps.AppConfig) podem ser definidas em qualquer lugar. A convenção `apps.py` simplesmente permite que o Django os carregue automaticamente quando [`INSTALLED_APPS`](/pt-br/4.2/ref/settings/#std-setting-INSTALLED_APPS) contém o caminho para um módulo de aplicativo ao invés do caminho para uma classe de configuração. > **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", # ... ] ``` Este exemplo mostra as classes de configuração específicas do projeto localizadas em um submódulo chamado `apps.py`. Isso é uma convenção, não uma exigência. As subclasses [`AppConfig`](#django.apps.AppConfig) podem ser definidas em qualquer lugar. Nesta situação, [`INSTALLED_APPS`](/pt-br/4.2/ref/settings/#std-setting-INSTALLED_APPS) deve conter o caminho pontilhado para a classe de configuração porque reside fora de um aplicativo e, portanto, não pode ser detectado automaticamente. ## 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` Defina este atributo como `False` para evitar que o Django selecione uma classe de configuração automaticamente. Isso é útil quando `apps.py` define apenas uma subclasse [`AppConfig`](#django.apps.AppConfig) mas você não quer que o Django a use por padrão. Defina este atributo como `True` para que o Django selecione uma classe de configuração automaticamente. Isso é útil quando `apps.py` define mais de uma subclasse [`AppConfig`](#django.apps.AppConfig) e você quer que o Django use uma delas por padrão. Por padrão, este atributo não é definido. #### `AppConfig.default_auto_field` O tipo de chave primária implícita a ser adicionada aos modelos dentro deste app. Você pode usar isso para manter a [`AutoField`](/pt-br/4.2/ref/models/fields/#django.db.models.AutoField) como o tipo de chave primária para aplicações de terceiros. Por padrão, este é o valor de [`DEFAULT_AUTO_FIELD`](/pt-br/4.2/ref/settings/#std-setting-DEFAULT_AUTO_FIELD). ### Atributos somente leitura #### `AppConfig.module` Módulo raiz para a aplicação; por exemplo, ``. #### `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/4.2/ref/signals/#django.db.models.signals.pre_migrate) e [`post_migrate`](/pt-br/4.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(include_auto_created=False, include_swapped=False)` Retornar um iterável de classes [`Model`](/pt-br/4.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/4.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/4.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/4.2/ref/models/instances/#django.db.models.Model.save), [`delete()`](/pt-br/4.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 usual, o método `ready` é chamado apenas uma vez pelo Django. No entanto, em alguns casos específicos, particularmente em testes que estão mexendo com aplicativos instalados, `ready` pode ser chamado mais de uma vez. Nesse caso, escreva métodos idempotentes ou coloque uma flag em suas classes `AppConfig` para evitar que o código seja executado mais de uma vez quando deveria ser executado exatamente uma vez. ### Pacotes de namespace como 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/4.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/4.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/4.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/4.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. - When running an HTTP server via Django’s ASGI or WSGI support. - 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/4.2/ref/settings/#std-setting-INSTALLED_APPS). 1. Primeiro Django importa cada item que está no [`INSTALLED_APPS`](/pt-br/4.2/ref/settings/#std-setting-INSTALLED_APPS). Se for uma classe de configuração do app, o Django importa o pacote raiz do aplicativo, definido pelo atributo [`name`](#django.apps.AppConfig.name). Se for um pacote Python, o Django procura uma configuração de aplicativo em um submódulo `apps.py`, ou então cria uma configuração de aplicativo 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/4.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/4.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. Por exemplo, a função [`gettext()`](/pt-br/4.2/ref/utils/#django.utils.translation.gettext) usa o registro de aplicativos para procurar catálogos de tradução em aplicativos. Para traduzir no momento da importação, você precisa usar [`gettext_lazy()`](/pt-br/4.2/ref/utils/#django.utils.translation.gettext_lazy) em vez disso. (Usar [`gettext()`](/pt-br/4.2/ref/utils/#django.utils.translation.gettext) seria um erro, porque a tradução ocorreria no momento da importação, em vez de em cada solicitação, dependendo do idioma ativo.) 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/4.2/ref/settings/#std-setting-INSTALLED_APPS) para que contenha o `'django.contrib.admin.apps.SimpleAdminConfig'` ao invés do `'django.contrib.admin'`.