Applications¶
Django contient un registre des applications installées qui stocke la configuration et fournit l’introspection. Il maintient également une liste des modèles disponibles.
Ce registre est tout simplement appelé apps
et est disponible dans django.apps
:
>>> from django.apps import apps
>>> apps.get_app_config('admin').verbose_name
'Admin'
Projets et applications¶
Le terme projet décrit une application Web Django. Le paquet Python du projet est définit principalement par un module de réglages settings
, mais il contient généralement d’autres choses. Par exemple, lorsque vous exécutez django-admin startproject monsite
, vous obtenez un répertoire de projet monsite
contenant un paquet Python monsite
avec les fichiers settings.py
, urls.py
et wsgi.py
. Le paquet de projet est souvent étendu par l’ajout de choses comme des instantanés, des fichiers CSS et des gabarits qui ne sont pas liés à une application particulière.
Un répertoire racine de projet (celui qui contient manage.py
) est généralement un conteneur pour toutes les applications d’un projet qui ne sont pas installées séparément.
Le terme application décrit un paquet Python qui fournit un certain ensemble de fonctionnalités. Les applications peuvent être réutilisées dans différents projets.
Les applications comprennent une combinaison de modèles, vues, gabarits, balises de gabarits, fichiers statiques, URL, intergiciels, etc. Elles sont généralement liées à des projets via le réglage INSTALLED_APPS
et éventuellement avec d’autres mécanismes tels que les configurations d’URL, le réglage MIDDLEWARE
ou l’héritage de gabarit.
Il est important de comprendre qu’une application Django n’est qu’un ensemble de code qui interagit avec les différentes parties du système. Il n’existe pas d’objet Application
en tant que tel. Cependant, il y a quelques endroits où Django a besoin d’interagir avec les applications installées, principalement pour la configuration et aussi l’introspection. C’est pourquoi le registre des applications maintient des métadonnées dans une instance de AppConfig
pour chaque application installée.
Il n’y a pas restriction au fait qu’un paquet de projet ne puisse pas aussi être considéré comme une application et qu’il contienne des modèles, etc. (ce qui demanderait de l’ajouter dans la liste INSTALLED_APPS
).
Configuration des applications¶
Pour configurer une application, héritez de AppConfig
et placez le chemin de cette sous-classe avec la syntaxe pointée dans INSTALLED_APPS
.
Lorsque INSTALLED_APPS
contient simplement le chemin vers un module d’application avec la syntaxe pointée, Django recherche une variable default_app_config
dans ce module.
Si elle est définie, il s’agit du chemin en syntaxe pointée vers la sous-classe de AppConfig
pour cette application.
S’il n’y a pas de default_app_config
, Django utilise la classe de base AppConfig
.
default_app_config
permet aux applications créées avant Django 1.7 telles que django.contrib.admin
de faire la transition vers la fonctionnalité AppConfig
sans exiger des utilisateurs qu’ils mettent à jour leur réglage INSTALLED_APPS
.
Les nouvelles applications devraient éviter default_app_config
. Elles devraient plutôt exiger le chemin pointé vers la sous-classe AppConfig
appropriée de manière explicite dans le réglage INSTALLED_APPS
.
Pour les auteurs d’applications¶
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"
Vous pouvez faire en sorte que votre application charge cette sous-classe de AppConfig
par défaut comme cela :
# rock_n_roll/__init__.py
default_app_config = 'rock_n_roll.apps.RockNRollConfig'
Cela entraîne l’utilisation de RockNRollConfig
lorsque INSTALLED_APPS
contient seulement 'rock_n_roll'
. Cela permet d’utiliser les fonctionnalités de AppConfig
sans exiger des utilisateurs qu’ils mettent à jour leur réglage INSTALLED_APPS
. En dehors de ce cas d’utilisation, il est préférable d’éviter l’utilisation de default_app_config
mais de plutôt indiquer la classe de configuration d’application dans INSTALLED_APPS
comme expliqué ci-après.
Bien entendu, vous pouvez aussi dire à vos utilisateurs de mettre 'rock_n_roll.apps.RockNRollConfig'
dans leur réglage INSTALLED_APPS
. Vous pouvez même fournir plusieurs sous-classes de AppConfig
différentes avec des comportements différents et permettre aux utilisateurs d’en choisir une via leur réglage INSTALLED_APPS
.
La convention recommandée est de mettre la classe de configuration dans un sous-module de l’application nommé apps
. Cependant, ce n’est pas requis par Django.
Vous devez inclure l’attribut name
pour que Django puisse déterminer à quelle application cette configuration s’applique. Vous pouvez définir n’importe quel attribut documenté dans la référence de l’API de AppConfig
.
Note
Si votre code importe le registre des applications dans le fichier __init__.py
d’une application, le nom apps
entrera en conflit avec le sous-module apps
. La meilleure approche consiste à déplacer ce code vers un sous-module et de l’importer. Une solution de contournement consiste à importer le registre sous un nom différent :
from django.apps import apps as django_apps
Pour les utilisateurs d’applications¶
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',
# ...
]
Encore une fois, la définition de classes de configuration spécifiques au projet dans un sous-module appelé apps
est une convention, pas une obligation.
Configuration d’applications¶
-
class
AppConfig
[source]¶ Les objets de configuration d’application stockent les métadonnées d’une application. Certains attributs peuvent être configurés dans des sous-classes de
AppConfig
. D’autres sont définis par Django et sont en lecture seule.
Attributs configurables¶
-
AppConfig.
name
¶ 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.
label
¶ 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 dename
. Il doit être un identifiant Python valide.Il doit être unique dans le contexte d’un même projet Django.
-
AppConfig.
verbose_name
¶ Nom convivial de l’application, par ex. « Administration ».
Par défaut, cet attribut est équivalent à
label.title()
.
-
AppConfig.
path
¶ Chemin du système de fichiers vers le répertoire de l’application, e.g.
'/usr/lib/python3.4/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.
Attributs en lecture seule¶
-
AppConfig.
module
¶ Module racine de l’application, par ex.
<module 'django.contrib.admin' from 'django/contrib/admin/__init__.pyc'>
.
-
AppConfig.
models_module
¶ Module contenant les modèles, par ex.
<module 'django.contrib.admin.models' from 'django/contrib/admin/models.pyc'>
.Il peut valoir
None
si l’application ne contient pas de modulemodels
. Notez que les signaux relatifs à la base de données tels quepre_migrate
etpost_migrate
ne sont émis que pour les applications qui ont un modulemodels
.
Méthodes¶
-
AppConfig.
get_models
()[source]¶ 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)[source]¶ Renvoie la classe
Model
ayant le nommodel_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
estFalse
.require_ready
a le même comportement que pourapps.get_model()
.New in Django 1.11:Le paramètre nommé
require_ready
a été ajouté.
-
AppConfig.
ready
()[source]¶ 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 dansready()
, en utilisant soit une instructionimport
ouget_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 :
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')
Avertissement
Bien que vous puissiez accéder aux classes de modèles comme expliqué ci-dessus, évitez d’interagir avec la base de données dans l’implémentation de
ready()
. Ceci inclut les méthodes de modèles qui exécutent des requêtes (save()
,delete()
, les méthodes de gestionnaires de modèles, etc.), ainsi que les requêtes SQL brutes viadjango.db.connection
. La méthodeready()
s’exécute lors du démarrage de chaque commande de gestion. Par exemple, bien que la configuration de la base de données de test soit séparée des réglages de production,manage.py test
pourrait malgré tout exécuter des requêtes sur votre base de données de production !Note
Dans le processus d’initialisation normal, la méthode
ready
est appelée une seule fois par Django. Mais dans certains cas limites, en particulier dans les tests qui manipulent les applications installées,ready
pourrait être appelée plus d’une fois. Dans ce cas, soit écrivez des méthodes idempotentes, soit placez un drapeau sur vos classesAppConfig
pour empêcher de ré-exécuter le code qui ne devrait être exécuté qu’une seule fois.
Paquets avec espace de noms en tant qu’applications (Python 3.3+)¶
Les versions de Python 3.3 et supérieures prennent en charge les paquets Python sans la présence d’un fichier __init __.py
. Ces paquets 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 :
- 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).
- La classe
AppConfig
utilisée pour configurer l’application possède un attribut de classepath
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
.
Registre d’applications¶
-
apps
¶ Le registre d’applications fournit l’API publique suivante. Les méthodes qui ne sont pas énumérées ci-dessous sont considérées comme privées et peuvent changer sans préavis.
-
apps.
ready
¶ Attribut booléen défini à
True
après que le registre a été entièrement peuplé et que toutes les méthodesAppConfig.ready()
ont été appelées.
-
apps.
get_app_config
(app_label)¶ Renvoie une instance
AppConfig
de l’application correspondant àapp_label
. GénèreLookupError
si une telle application n’existe pas.
-
apps.
is_installed
(app_name)¶ Vérifie si une application avec le nom donné existe dans le registre.
app_name
est le nom complet de l’application, par ex.'django.contrib.admin'
.
-
apps.
get_model
(app_label, model_name, require_ready=True)¶ Renvoie la classe
Model
correspondant aux paramètresapp_label
etmodel_name
. Cette méthode accepte aussi en raccourci un paramètre unique sous la formeapp_label.model_name
.model_name
est insensible à la casse.Génère
LookupError
si aucune application ou modèle correspondant n’existe. GénèreValueError
lorsque un paramètre unique est fourni sans contenir exactement un seul point.Nécessite que le registre des applications soit complètement défini, sauf dans le cas où le paramètre
require_ready
estFalse
.La définition de
require_ready
àFalse
permet de consulter des modèles pendant que le registre des applications est en cours de remplissage, particulièrement dans la seconde phase où les modèles sont importés.get_model()
a donc le même effet que l’importation du modèle. Le principal cas d’utilisation concerne la configuration de classes de modèles en fonction de réglages, tels queAUTH_USER_MODEL
.Lorsque
require_ready
vautFalse
,get_model()
renvoie une classe de modèle qui peut ne pas être complètement fonctionnelle (par exemple, l’accès aux relations inversées peut être manquant) en attendant que le registre des applications soit complètement rempli. Pour cette raison, il est préférable de laisserrequire_ready
à sa valeur par défautTrue
autant que possible.New in Django 1.11:Le paramètre nommé
require_ready
a été ajouté.
Processus d’initialisation¶
Chargement des applications¶
Lorsque Django démarre, django.setup()
est responsable de peupler le registre des applications.
-
setup
(set_prefix=True)[source]¶ Configure Django en :
- chargeant les réglages ;
- configurant la journalisation ;
- Si
set_prefix
vautTrue
, 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.
Changed in Django 1.10:La possibilité de définir le préfixe de script de résolution d’URL a été ajoutée.
Cette fonction est appelée automatiquement :
- lors de l’exécution d’un serveur HTTP via le support 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
.
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 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.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
oumodels/__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.Enfin, Django exécute la méthode
ready()
de chaque configuration d’application.
Dépannage¶
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,
ugettext()
utilise le registre d’applications pour rechercher des catalogues de traduction dans les applications. Pour traduire au moment de l’importation, vous devez utiliserugettext_lazy()
à la place (l’utilisation deugettext()
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 modulesadmin
dans les applications installées. Pour l’en empêcher, modifiez le réglageINSTALLED_APPS
pour qu’il contienne'django.contrib.admin.apps.SimpleAdminConfig'
au lieu de'django.contrib.admin'
.