ApplicationsLien vers cette rubrique#

Pour les auteurs d’applicationsLien vers cette rubrique#

Si vous créez une application réutilisable appelée « Rock “n” roll », voici comment vous pourriez définir un nom approprié pour l’interface d’administration :

# rock_n_roll/apps.py

from django.apps import AppConfig


class RockNRollConfig(AppConfig):
    name = "rock_n_roll"
    verbose_name = "Rock ’n’ roll"

RockNRollConfig sera chargée automatiquement si INSTALLED_APPS contient 'rock_n_roll'. Si vous voulez empêcher cela, définissez default à False dans la définition de la classe.

Vous pouvez écrire plusieurs sous-classes AppConfig avec différents comportements. Pour indiquer à Django la classe à utiliser par défaut, définissez l’attribut default de la classe à True. Si un utilisateur de l’application souhaite choisir une configuration qui n’est pas celle par défaut, il doit remplacer 'rock_n_roll' par le chemin à syntaxe pointée vers cette classe spécifique dans son réglage INSTALLED_APPS.

L’attribut AppConfig.name indique à Django à quelle application cette configuration s’applique. Vous pouvez définir tout autre attribut documenté dans la référence de l’API de AppConfig.

Les sous-classes de AppConfig peuvent être définies n’importe où. La convention apps.py ne sert qu’à indiquer à Django comment charger automatiquement la configuration lorsque INSTALLED_APPS contient le chemin vers le module principal d’une application plutôt que le chemin vers sa classe de configuration.

Pour les utilisateurs d’applicationsLien vers cette rubrique#

Si vous utilisez « Rock “n” roll » dans un projet appelé anthology, mais que vous souhaitez plutôt qu’il apparaisse comme « Jazz Manouche », vous pouvez fournir votre propre configuration :

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

Cet exemple montre des classes de configuration spécifiques au projet situées dans un sous-module appelé apps.py. Ceci est une convention, pas une obligation. Les sous-classes AppConfig peuvent être définies n’importe où.

Dans cette situation, INSTALLED_APPS doit contenir le chemin à syntaxe pointée vers la classe de configuration, car celle-ci se trouve en dehors d’une application et ne peut donc pas être automatiquement détectée.

Attributs configurablesLien vers cette rubrique#

AppConfig.nameLien vers cette définition#

Chemin Python complet vers l’application, par ex. 'django.contrib.admin'.

Cet attribut détermine à quelle application la configuration s’applique. Il doit être défini dans toutes les sous-classes de AppConfig.

Il doit être unique dans le contexte d’un même projet Django.

AppConfig.labelLien vers cette définition#

Nom court de l’application, par ex. 'admin'

Cet attribut permet de ré-étiqueter une application lorsque deux applications ont des étiquettes incompatibles. Par défaut, label est le dernier élément de name. Il doit être un identifiant Python valide.

Il doit être unique dans le contexte d’un même projet Django.

AppConfig.verbose_nameLien vers cette définition#

Nom convivial de l’application, par ex. « Administration ».

Par défaut, cet attribut est équivalent à label.title().

AppConfig.pathLien vers cette définition#

Chemin du système de fichiers vers le répertoire de l’application, par ex. '/usr/lib/pythonX.Y/dist-packages/django/contrib/admin'.

Dans la plupart des cas, Django peut automatiquement détecter et définir cet attribut, mais vous pouvez également fournir une dérogation explicite comme attribut de classe sur la sous-classe de AppConfig. Dans certains cas, c’est une nécessité ; par exemple, si le paquet de l’application est un paquet avec espace de noms comprenant plusieurs chemins.

AppConfig.defaultLien vers cette définition#

Définissez cet attribut à False pour empêcher Django de choisir automatiquement une classe de configuration. C’est utile lorsque apps.py définit une seule sous-classe AppConfig mais que vous ne souhaitez pas que celle-ci soit choisie par défaut.

Définissez cet attribut à True pour indiquer à Django de choisir automatiquement une classe de configuration. C’est utile lorsque apps.py définit plus d’une sous-classe AppConfig et que vous souhaitez que Django en utilise une par défaut.

Par défaut, cet attribut n’est pas défini.

AppConfig.default_auto_fieldLien vers cette définition#

Le type de clé primaire implicite à ajouter aux modèles de cette application.

Les applications réutilisables qui définissent des modèles doivent définir cet attribut pour s’assurer que les migrations incluses dans l’application correspondent aux modèles. Sinon, des migrations seront générées pour l’application quand une personne exécutera makemigrations avec un réglage DEFAULT_AUTO_FIELD différent, ce qui pourrait entrer en conflit avec de futures migrations produites par l’application.

Par exemple, pour continuer d’utiliser AutoField:

Code

default_auto_field = "django.db.models.AutoField"

Par défaut, il s’agit de la valeur du réglage DEFAULT_AUTO_FIELD.

Attributs en lecture seuleLien vers cette rubrique#

AppConfig.moduleLien vers cette définition#

Module racine de l’application, par ex. <module 'django.contrib.admin' from 'django/contrib/admin/__init__.py'>.

AppConfig.models_moduleLien vers cette définition#

Module contenant les modèles, par ex. <module 'django.contrib.admin.models' from 'django/contrib/admin/models.py'>.

Il peut valoir None si l’application ne contient pas de module models. Notez que les signaux relatifs à la base de données tels que pre_migrate et post_migrate ne sont émis que pour les applications qui ont un module models.

MéthodesLien vers cette rubrique#

AppConfig.get_models(include_auto_created=False, include_swapped=False)Lien vers cette définition#

Renvoie un objet itérable de classes Model pour cette application.

Nécessite que le registre des applications soit complètement défini.

AppConfig.get_model(model_name, require_ready=True)Lien vers cette définition#

Renvoie la classe Model ayant le nom model_name donné. model_name est insensible à la casse.

Génère LookupError si aucun modèle de ce nom n’existe dans cette application.

Nécessite que le registre des applications soit complètement défini, sauf dans le cas où le paramètre require_ready est False. require_ready a le même comportement que pour apps.get_model().

AppConfig.ready()Lien vers cette définition#

Les sous-classes peuvent étendre cette méthode pour effectuer des tâches d’initialisation telles que l’enregistrement de signaux. Elle est appelée dès que le registre est entièrement peuplé.

Même s’il n’est pas possible d’importer des modèles au niveau des modules où les classes AppConfig sont définies, il est possible de les importer dans ready(), en utilisant soit une instruction import ou get_model().

Si vous inscrivez des signaux de modèle, vous pouvez faire référence à l’expéditeur par son étiquette textuelle au lieu d’utiliser la classe de modèle en elle-même.

Exemple :

Code

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")

Paquets avec espace de noms en tant qu’applicationsLien vers cette rubrique#

Les paquets Python sans la présence d’un fichier __init __.py sont appelés « paquets avec espace de noms » (namespace packages) et peuvent être dispersés dans plusieurs répertoires et à différents endroits de sys.path (voir PEP 420).

Les applications Django nécessitent un chemin de base unique du système de fichiers où Django (selon la configuration) recherche les gabarits, les fichiers statiques, etc. Ainsi, les paquets avec espace de noms ne peuvent être des applications Django que si l’une des conditions suivantes est vraie :

1. Le paquet avec espace de noms n’a en fait qu’un seul emplacement (c’est-à-dire qu’il n’est pas dispersé sur plus d’un répertoire).

2. La classe AppConfig utilisée pour configurer l’application possède un attribut de classe path qui correspond au chemin de répertoire absolu que Django utilise comme chemin de base unique pour l’application.

Si aucune de ces conditions n’est remplie, Django génère une exception ImproperlyConfigured.

Chargement des applicationsLien vers cette rubrique#

Lorsque Django démarre, django.setup() est responsable de peupler le registre des applications.

setup(set_prefix=True)Lien vers cette définition#

Configure Django en :

• chargeant les réglages ;

• configurant la journalisation ;

• Si set_prefix vaut True, définissant le préfixe de script de résolution d’URL à FORCE_SCRIPT_NAME s’il est défini ou sinon à /.

• initialisant le registre d’applications.

Cette fonction est appelée automatiquement :

• lors de l’exécution d’un serveur HTTP via le support ASGI ou WSGI de Django ;

• lors de l’appel d’une commande de gestion.

Elle doit être appelée explicitement dans d’autres cas, comme par exemple dans les scripts Python ordinaires.

Le registre d’applications est initialisé en trois étapes. À chaque étape, Django traite toutes les applications dans l’ordre de INSTALLED_APPS.

1. Tout d’abord, Django importe chaque élément de INSTALLED_APPS.

   S’il s’agit d’une classe de configuration de l’application, Django importe le paquet racine de l’application, défini par son attribut name. S’il s’agit d’un paquet Python, Django recherche une configuration d’application dans un sous-module apps.py, ou sinon crée une configuration d’application par défaut.

   À ce stade, votre code ne devrait pas importer de modèles !

   En d’autres termes, les paquets racines de vos applications et les modules qui définissent vos classes de configuration d’application ne devraient pas importer de modèles, même indirectement.

   Strictement parlant, Django permet d’importer des modèles une fois que leur configuration d’application est chargée. Toutefois, afin d’éviter toute contrainte inutile sur l’ordre dans INSTALLED_APPS, il est fortement recommandé de ne pas importer de modèles à ce stade.

   Une fois cette étape terminée, les API qui exploitent les configurations d’application telles que get_app_config() deviennent utilisables.

2. Puis Django tente d’importer le sous-module models de chaque application, s’il en existe un.

   Vous devez définir ou importer tous les modèles dans les fichiers models.py ou models/__init__.py de votre application. Autrement, le registre des applications pouvant ne pas être entièrement peuplé à ce point, cela pourrait provoquer un dysfonctionnement de l’ORM.

   Une fois cette étape terminée, les API qui agissent sur des modèles telles que get_model() deviennent utilisables.

3. Enfin, Django exécute la méthode ready() de chaque configuration d’application.

DépannageLien vers cette rubrique#

Voici quelques problèmes courants que vous pouvez rencontrer lors de l’initialisation :

• AppRegistryNotReady: cela se produit lorsque l’importation d’une configuration d’application ou d’un module de modèles exécute du code qui dépend du registre d’applications.

  Par exemple, gettext() utilise le registre d’applications pour rechercher des catalogues de traduction dans les applications. Pour traduire au moment de l’importation, vous devez utiliser gettext_lazy() à la place (l’utilisation de gettext() serait une erreur, parce que la traduction s’effectuerait au moment de l’importation plutôt qu’à chaque requête en fonction de la langue active).

  L’exécution de requêtes en base de données avec l’ORM au moment de l’importation dans les modules de modèles déclenche également cette exception. L’ORM ne peut pas fonctionner correctement avant que tous les modèles ne soient disponibles.

  Cette exception se produit également si vous oubliez d’appeler django.setup() dans un script Python autonome.

• ImportError: cannot import name ... Cela se produit si la séquence d’importation se trouve être une boucle.

  Pour éliminer de tels problèmes, vous devez réduire les dépendances entre vos modules de modèles et réaliser le moins de travail possible au moment de l’importation. Pour éviter d’exécuter du code au moment de l’importation, vous pouvez le déplacer dans une fonction et mettre en cache ses résultats. Le code sera exécuté la première fois que vous aurez besoin de ses résultats. Ce concept est connu sous le nom d”« évaluation différée ».

• django.contrib.admin effectue automatiquement la découverte des modules admin dans les applications installées. Pour l’en empêcher, modifiez le réglage INSTALLED_APPS pour qu’il contienne 'django.contrib.admin.apps.SimpleAdminConfig' au lieu de 'django.contrib.admin'.

• RuntimeWarning: Accessing the database during app initialization is discouraged. Cet avertissement est généré par des requêtes de base de données exécutées avant que les applications ne soient prêtes, comme par exemple durant l’importation des modules ou dans la méthode AppConfig.ready(). De telles requêtes de base de données prématurées sont découragées car elles vont s’exécuter durant le démarrage de chaque commande d’administration, ce qui va ralentir le démarrage du projet, mettre potentiellement en cache des données obsolètes et elles peuvent même échouer si des migrations sont pendantes.

  Typiquement, une erreur courante est d’interroger la base de données pour remplir des choix de champ de formulaire :

  Code

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

  Dans l’exemple ci-dessus, la requête sous-jacente de Country.objects.all() est exécutée durant l’importation du module, car il y a itération de l’objet QuerySet. Pour éviter l’avertissement, le formulaire pourrait utiliser ModelChoiceField à la place :

  Code

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

  Pour faciliter le repérage du code qui a généré l’avertissement, vous pouvez demander à Python de traiter les avertissements comme des erreurs pour révéler la trace d’erreur, par exemple avec python -Werror manage.py shell.