Un fichier de réglages Django contient toute la configuration de votre installation de Django. Ce document explique le fonctionnement des réglages et quels sont les réglages disponibles.
\nUn fichier de réglages n’est qu’un module Python avec des variables de niveau module.
\nVoici quelques exemples de réglages :
\nALLOWED_HOSTS = ['www.example.com']\nDEBUG = False\nDEFAULT_FROM_EMAIL = 'webmaster@example.com'\nComme un fichier de réglages est un module Python, les points suivants s’appliquent :
\nIl n’accepte pas les erreurs de syntaxe Python.
Il peut attribuer des valeurs de réglages dynamiques avec la syntaxe Python habituelle. Par exemple :
\nMY_SETTING = [str(i) for i in range(30)]\nIl peut importer des valeurs provenant d’autres fichiers de réglages.
Quand vous utilisez Django, vous devez lui indiquer le fichier de réglages qu’il doit utiliser. Vous pouvez le faire par une variable d’environnement, DJANGO_SETTINGS_MODULE.
La valeur de DJANGO_SETTINGS_MODULE doit respecter la syntaxe des chemins Python, par ex. mysite.settings. Notez que le module de réglages doit se trouver dans le chemin de recherche d’importation Python.
django-adminLien vers cette rubrique#Quand vous utilisez django-admin, vous pouvez soit définir une seule fois la variable d’environnement, soit lui transmettre explicitement le module de réglages à chaque lancement de la commande.
\nExemple (shell Unix bash) :
\nexport DJANGO_SETTINGS_MODULE=mysite.settings\ndjango-admin runserver\nExemple (shell Windows) :
\nset DJANGO_SETTINGS_MODULE=mysite.settings\ndjango-admin runserver\nUtilisez le paramètre de ligne de commande --settings pour indiquer manuellement le fichier de réglages :
django-admin runserver --settings=mysite.settings\nmod_wsgi)Lien vers cette rubrique#Dans l’environnement de production de votre serveur, vous devrez indiquer à votre application WSGI quel fichier de réglages il doit utiliser. Faites-le avec os.environ:
import os\n\nos.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings'\nLisez la documentation Django de mod_wsgi pour plus d’informations ainsi que d’autres éléments communs à toute application WSGI Django.
\nUn fichier de réglages Django n’a aucune obligation de définir des réglages s’il n’y a pas de besoins avérés. Chaque réglage possède une valeur par défaut logique. Ces valeurs par défaut se trouvent dans le module django/conf/global_settings.py.
Voici l’algorithme utilisé par Django pour compiler les réglages :
\nCharger les réglages de
Charger les réglages du fichier de réglages en vigueur, surchargeant les réglages globaux si nécessaire.
Notez qu’un fichier de réglages ne doit pas importer global_settings, car ce serait redondant.
La commande python manage.py diffsettings affiche les différences entre le fichier de réglages actuel et les réglages par défaut de Django.
Pour en savoir plus, lisez la documentation de diffsettings.
Dans vos applications Django, utilisez les réglages en important l’objet django.conf.settings. Exemple :
from django.conf import settings\n\nif settings.DEBUG:\n # Do something\nNotez que django.conf.settings n’est pas un module, c’est un objet. L’importation de réglages individuels n’est donc pas possible :
from django.conf.settings import DEBUG # This won't work.\nNotez également que votre code ne doit pas importer ni de global_settings, ni de votre propre fichier de réglages. django.conf.settings est une abstraction du concept de réglages par défaut et de réglages spécifiques par site ; il présente une interface unifiée. Il découple aussi le code qui utilise les réglages de l’emplacement de vos réglages.
Vous ne devriez pas modifier les réglages de vos applications durant leur exécution. Par exemple, ne faites pas ceci dans une vue :
\nfrom django.conf import settings\n\nsettings.DEBUG = True # Don't do this!\nLe seul endroit où des réglages doivent recevoir des valeurs est le fichier des réglages.
\nDans la mesure où un fichier de réglages contient des informations sensibles comme des mots de passe de base de données, vous devez faire tout votre possible pour limiter l’accès à ces fichiers. Par exemple, modifiez les permissions du fichier pour que seuls vous et le serveur Web puissiez le lire. C’est particulièrement important dans le contexte d’un environnement d’hébergement partagé.
\nPour une liste complète des réglages disponibles, consultez la référence des réglages.
\nRien ne vous empêche de créer vos propres réglages pour vos propres applications Django, mais suivez ces lignes de conduite :
\nLes noms des réglages doivent être tout en majuscules.
Ne réinventez pas un réglage existant.
Pour les réglages qui sont de type liste, Django utilise lui-même des listes Python, mais ce n’est qu’une convention.
\nDJANGO_SETTINGS_MODULELien vers cette rubrique#Dans certains cas, il peut être souhaitable de ne pas tenir compte de la variable d’environnement DJANGO_SETTINGS_MODULE. Par exemple, si vous utilisez le système de gabarits pour lui-même, il n’est probablement pas utile de configurer une variable d’environnement pointant vers un module de réglages.
Dans ces situations, vous pouvez configurer manuellement les réglages de Django. Faites-le en appelant :
\nExemple :
\nfrom django.conf import settings\n\nsettings.configure(DEBUG=True)\nVous pouvez transmettre autant de paramètres que nécessaire à configure(), sachant que chaque paramètre nommé constituera un réglage avec sa valeur. Chaque nom de paramètre devrait être entièrement en majuscules et correspondre à l’un des paramètres existants. Si un réglage particulier n’est pas transmis à configure() et qu’il est requis plus loin dans le code, Django utilise alors la valeur par défaut du réglage.
La configuration de Django de cette manière est surtout nécessaire (et même recommandée) lorsque vous utilisez une partie de l’infrastructure Django dans une application plus vaste.
\nEn conséquence, quand Django est configuré par settings.configure(), il ne fera aucune modification aux variables d’environnement du processus (consultez la documentation de TIME_ZONE pour savoir pourquoi cela se passe normalement). Django suppose alors que vous avez déjà le contrôle complet de votre environnement.
Si vous aimeriez que des valeurs par défaut proviennent d’endroits différents de django.conf.global_settings, vous pouvez transmettre un module ou une classe responsable de fournir les valeurs par défaut dans le paramètre default_settings (ou comme premier paramètre positionnel) dans l’appel à configure().
Dans cet exemple, les réglages par défaut proviennent de myapp_defaults et le paramètre DEBUG est défini à True, quelle que soit sa valeur dans myapp_defaults:
from django.conf import settings\nfrom myapp import myapp_defaults\n\nsettings.configure(default_settings=myapp_defaults, DEBUG=True)\nL’exemple suivant qui place myapp_defaults comme paramètre positionnel est équivalent :
settings.configure(myapp_defaults, DEBUG=True)\nNormalement, il n’est pas nécessaire de surcharger les valeurs par défaut de cette manière. Les valeurs par défaut de Django sont suffisamment éprouvées pour pouvoir les utiliser avec confiance. Sachez que lorsque vous transmettez un nouveau module de valeurs par défaut, il remplace entièrement les valeurs par défaut de Django, il est donc indispensable de fournir des valeurs pour chaque réglage potentiellement utilisé dans le code que vous importez. Parcourez django.conf.settings.global_settings pour voir la liste complète.
configure() ou de DJANGO_SETTINGS_MODULELien vers cette rubrique#Si vous ne définissez pas la variable d’environnement DJANGO_SETTINGS_MODULE, vous devez appeler configure() avant que du code se mette à lire des réglages.
Si vous ne définissez pas DJANGO_SETTINGS_MODULE et n’appelez pas configure(), Django lèvera une exception ImportError lors du premier accès à un réglage.
Si vous définissez DJANGO_SETTINGS_MODULE, puis vous accédez à des valeurs de réglages d’une manière ou d’une autre, puis vous appelez configure(), Django lèvera une exception RuntimeError indiquant que les réglages ont déjà été configurés. Il existe une propriété pour ce cas de figure :
Par exemple :
\nfrom django.conf import settings\nif not settings.configured:\n settings.configure(myapp_defaults, DEBUG=True)\nIl est également erroné d’appeler configure() plus d’une fois, ou d’appeler configure() après qu’au moins un réglage ait été lu.
En conclusion : utilisez soit configure(), soit DJANGO_SETTINGS_MODULE, mais jamais les deux et toujours au moins un des deux.
django.setup() pour utiliser Django de manière « indépendante »Lien vers cette rubrique#Si vous utilisez des composants de Django de manière indépendante, par exemple en écrivant un script Python qui charge certains gabarits Django et les produit, ou en utilisant l’ORM pour récupérer certaines données, une étape supplémentaire est nécessaire en plus de la configuration des réglages.
\nAprès avoir soit défini DJANGO_SETTINGS_MODULE ou appelé configure(), vous devrez appeler django.setup() pour charger les réglages et remplir le registre des applications de Django. Par exemple :
import django\nfrom django.conf import settings\nfrom myapp import myapp_defaults\n\nsettings.configure(default_settings=myapp_defaults, DEBUG=True)\ndjango.setup()\n\n# Now this script or any imported module can use any part of Django it needs.\nfrom myapp import models\nNotez que l’appel à django.setup() n’est nécessaire que si votre code est réellement indépendant. Lorsqu’il est appelé par un serveur Web ou par l’intermédiaire de django-admin, Django se charge de procéder à cette initialisation.