Les réglages de Django

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.

Principes de base

Un fichier de réglages n’est qu’un module Python avec des variables de niveau module.

Voici quelques exemples de réglages :

ALLOWED_HOSTS = ['www.example.com']
DEBUG = False
DEFAULT_FROM_EMAIL = '[e-mail]'

Note

Si vous définissez DEBUG à False, vous devez également définir correctement le réglage ALLOWED_HOSTS.

Comme un fichier de réglages est un module Python, les points suivants s’appliquent :

• Il n’accepte pas les erreurs de syntaxe Python.

• Il peut attribuer des valeurs de réglages dynamiques avec la syntaxe Python habituelle. Par exemple :

  MY_SETTING = [str(i) for i in range(30)]
  

• Il peut importer des valeurs provenant d’autres fichiers de réglages.

Définition du fichier de réglages

DJANGO_SETTINGS_MODULE

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.

L’utilitaire django-admin

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.

Exemple (shell Unix bash) :

export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver

Exemple (shell Windows) :

set DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver

Utilisez le paramètre de ligne de commande --settings pour indiquer manuellement le fichier de réglages :

django-admin runserver --settings=mysite.settings

Sur le serveur (mod_wsgi)

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

os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings'

Lisez la documentation Django de mod_wsgi pour plus d’informations ainsi que d’autres éléments communs à toute application WSGI Django.

Réglages par défaut

Un 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 :

• Charger 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.

Vision des réglages modifiés

Il existe une façon simple de voir quels sont les réglages qui diffèrent des réglages par défaut. 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.

Utilisation des réglages dans le code Python

Dans vos applications Django, utilisez les réglages en important l’objet django.conf.settings. Exemple :

from django.conf import settings

if settings.DEBUG:
    # Do something

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

Notez é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.

Modification des réglages en cours d’exécution

Vous ne devriez pas modifier les réglages de vos applications durant leur exécution. Par exemple, ne faites pas ceci dans une vue :

from django.conf import settings

settings.DEBUG = True   # Don't do this!

Le seul endroit où des réglages doivent recevoir des valeurs est le fichier des réglages.

Sécurité

Dans 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é.

Réglages disponibles

Pour une liste complète des réglages disponibles, consultez la référence des réglages.

Création de ses propres réglages

Rien ne vous empêche de créer vos propres réglages pour vos propres applications Django. Suivez simplement ces lignes de conduite :

• Les 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.

Utilisation des réglages sans définir DJANGO_SETTINGS_MODULE

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 :

django.conf.settings.configure(default_settings, **settings)

Exemple :

from django.conf import settings

settings.configure(DEBUG=True)

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

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

Réglages par défaut personnalisés

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
from myapp import myapp_defaults

settings.configure(default_settings=myapp_defaults, DEBUG=True)

L’exemple suivant qui place myapp_defaults comme paramètre positionnel est équivalent :

settings.configure(myapp_defaults, DEBUG=True)

Normalement, 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.

Nécessité de configure() ou de DJANGO_SETTINGS_MODULE

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é tout exprès pour ce cas de figure :

Par exemple :

from django.conf import settings
if not settings.configured:
    settings.configure(myapp_defaults, DEBUG=True)

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

Appel obligatoire de django.setup() pour utiliser Django de manière « indépendante »

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.

Aprè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
from django.conf import settings
from myapp import myapp_defaults

settings.configure(default_settings=myapp_defaults, DEBUG=True)
django.setup()

# Now this script or any imported module can use any part of Django it needs.
from myapp import models

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

django.setup() ne peut être appelée qu’une seule fois.

Ainsi, évitez de placer de la logique applicative réutilisable dans des scripts autonomes pour ne pas devoir importer le script depuis un autre endroit de votre application. Si c’est inévitable, placez l’appel à django.setup() à l’intérieur d’un bloc if:

if __name__ == '__main__':
    import django
    django.setup()

Voir aussi

La référence des réglages

Contient une liste complète des réglages de Django et de ses applications « contrib ».