# Documentação Django 5.2.8

# 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.

This registry is called `apps` and it’s available in `django.apps`:

    >>> 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 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, crie um modulo “apps.py” dentro da aplicação, então defina a subclasse do `AppConfig` lá.

Quando `INSTALLED_APPS` contém o caminho pontilhado para um módulo de aplicativo, por padrão, se o Django encontra exatamente uma subclasse `AppConfig` no submódulo `` apps.py``, este usa aquela configuração para o aplicativo. Este comportamento pode ser desabilitado definindo `AppConfig.default` como `False`.

Se o módulo `apps.py` contiver mais de uma subclasse `AppConfig`, o Django irá procurar por uma única onde `AppConfig.default` é `True`.

Se a subclasse `AppConfig` não for encontrada, a classe base `AppConfig` será usada.

Alternativamente, `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` contiver `'rock_n_roll'`. Se você precisa evitar isso, defina `default` como `False` na definição da classe.

Você pode fornecer várias subclasses `AppConfig` com comportamentos diferentes. Para dizer ao Django qual usar por padrão, defina `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`.

O atributo `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`.

As subclasses `AppConfig` podem ser definidas em qualquer lugar. A convenção `apps.py` simplesmente permite que o Django os carregue automaticamente quando `INSTALLED_APPS` contém o caminho para um módulo de aplicativo ao invés do caminho para uma classe de configuração.

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",
        # ...
    ]

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` podem ser definidas em qualquer lugar.

Nesta situação, `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`. 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.

  Aviso

  Changing this attribute after migrations have been applied for an application will result in breaking changes to a project or, in the case of a reusable app, any existing installs of that app. This is because `AppConfig.label` is used in database tables and migration files when referencing an app in the dependencies list.

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`. Em alguma situações isso é requerido; por exemplo se o pacote da aplicação é um 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` 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` 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` como o tipo de chave primária para aplicações de terceiros.

  Por padrão, este é o valor de `DEFAULT_AUTO_FIELD`.

### Atributos somente leitura

AppConfig.module

  Módulo raiz para a aplicação; por exemplo, `<módulo 'django.contrib.admin' vindo de 'django/contrib/admin/__init__.py'>`.

AppConfig.models_module

  Módulo contendo os models, e.g. `<module 'django.contrib.admin.models' from 'django/contrib/admin/models.py'>`.

  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` e `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` para esta aplicação.

  Requer que o registro do aplicativo esteja totalmente povoado.

AppConfig.get_model(model_name, require_ready=True)

  Retorna a `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.

  Requires the app registry to be fully populated unless the `require_ready` argument is set to `False`. `require_ready` behaves exactly as in `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` são definidas, você pode faze-lo in `ready()`, usando tanto uma instrução de ``import` ou `get_model()`.

  Se estiver registrando `model 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")

  Aviso

  Although you can access model classes as described above, avoid interacting with the database in your `ready()` implementation. This includes model methods that execute queries (`save()`, `delete()`, manager methods etc.), and also raw SQL queries via `django.db.connection`. Your `ready()` method will run during startup of every management command. For example, even though the test database configuration is separate from the production settings, `manage.py test` would still execute some queries against your production database!

  Nota

  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` usada para configurar a aplicação tem um atributo de classe `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`.

## 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()` são chamados.

apps.get_app_configs()

  Retorna um iterável de instancias de `AppConfig`.

apps.get_app_config(app_label)

  Retorna uma `AppConfig` para a aplicação com o dado `app_label`. Emite um erro `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` 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` se a tal aplicação ou modelo não existir. Emite `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 <app-loading-process>`, 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`.

  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

When Django starts, `django.setup()` is responsible for populating the application registry.

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` 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`.

1. Primeiro Django importa cada item que está no `INSTALLED_APPS`.

   Se for uma classe de configuração do app, o Django importa o pacote raiz do aplicativo, definido pelo atributo `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`, recomendamos fortemente não importar qualquer modelo neste estágio.

   Once this stage completes, APIs that operate on application configurations such as `get_app_config()` become usable.

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.

   Once this stage completes, APIs that operate on models such as `get_model()` become usable.

3. Finally Django runs the `ready()` method of each application configuration.

### Solução de Problemas

Aqui estão alguns problemas comuns que você talvez encontre durante a inicialização:

- `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()` uses the app registry to look up translation catalogs in applications. To translate at import time, you need `gettext_lazy()` instead. (Using `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.

  This exception also happens if you forget to call `django.setup()` in a standalone Python script.

- `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` para que contenha o `'django.contrib.admin.apps.SimpleAdminConfig'` ao invés do `'django.contrib.admin'`.

- `RuntimeWarning: Accessing the database during app initialization is discouraged.` This warning is triggered for database queries executed before apps are ready, such as during module imports or in the `AppConfig.ready()` method. Such premature database queries are discouraged because they will run during the startup of every management command, which will slow down your project startup, potentially cache stale data, and can even fail if migrations are pending.

  For example, a common mistake is making a database query to populate form field choices:

      class LocationForm(forms.Form):
          country = forms.ChoiceField(choices=[c.name for c in Country.objects.all()])

  In the example above, the query from `Country.objects.all()` is executed during module import, because the `QuerySet` is iterated over. To avoid the warning, the form could use a `ModelChoiceField` instead:

      class LocationForm(forms.Form):
          country = forms.ModelChoiceField(queryset=Country.objects.all())

  To make it easier to find the code that triggered this warning, you can make Python treat warnings as errors to reveal the stack trace, for example with `python -Werror manage.py shell`.