# Documentation Django 6.0.7

# 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 = "webmaster@example.com"

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 système `sys.path` de 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 `global_settings.py`.

- 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

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, mais suivez 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é pour ce cas de figure :

django.conf.settings.configured

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