Lorsque la prise en charge des fuseaux horaires est activée, Django stocke les informations de date/heure en UTC dans la base de données, utilise en interne des objets date/heure conscients de leur fuseau horaire et les convertit dans les gabarits et les formulaires en utilisant le fuseau horaire de l’utilisateur.
\nC’est très pratique si vos utilisateurs sont répartis sur plus d’un fuseau horaire et que vous vouliez afficher les informations temporelles selon l’heure locale de chacun.
\nMême si votre site Web n’est utilisé que dans un seul fuseau horaire, stocker les données en UTC dans la base de données fait partie des bonnes pratiques. La raison principale étant l’heure d’été (Daylight Saving Time - DST). Dans beaucoup de pays, l’heure d’été fait avancer d’une heure au printemps et reculer d’une heure en automne. Si vous travaillez en temps local, vous risquez d’obtenir des erreurs deux fois par année, au moment de la transition (la documentation de pytz aborde ces questions plus en détails). ce n’est probablement pas un problème pour votre blog, mais c’en est un si vous surfacturez ou sous-facturez vos clients d’une heure, deux fois par année, chaque année. La solution à ce problème est d’utiliser UTC dans le code, et le temps local uniquement lors des interactions avec les utilisateurs du site.
\nLa prise en charge des fuseaux horaires est désactivée par défaut. Pour l’activer, définissez USE_TZ = True dans votre fichier de réglages. La prise en charge des fuseaux horaires utilise pytz qui est installé en même temps que Django.
Si vous êtes empêtré dans un problème particulier, commencez par lire la FAQ des fuseaux horaires.
\ndatetime naïfs et conscientsLien vers cette rubrique#Les objets datetime.datetime de Python possèdent un attribut tzinfo pouvant être utilisé pour stocker le fuseau horaire, représenté par une instance d’une sous-classe de datetime.tzinfo. Lorsque cet attribut est défini et qu’il décrit un décalage horaire, l’objet datetime est conscient. Dans le cas contraire, il est naïf.
Vous pouvez utiliser is_aware() et is_naive() pour déterminer si les objets datetime sont conscients (aware) ou naïfs.
Lorsque la prise en charge des fuseaux horaires est désactivée, Django utilise des objets datetime naïfs en heure locale. C’est suffisant dans de nombreux cas. Dans ce mode, pour obtenir le temps actuel, vous écririez :
import datetime\n\nnow = datetime.datetime.now()\nLorsque la prise en charge des fuseaux horaires est activée (USE_TZ=True), Django utilise des objets datetime conscients de leur fuseau horaire. Si vote code crée des objets datetime, ils devraient également être conscients. Dans ce mode, l’exemple ci-dessus devient :
from django.utils import timezone\n\nnow = timezone.now()\ndatetime naïfsLien vers cette rubrique#Lorsque USE_TZ vaut True, Django accepte encore les objets datetime naïfs, afin de préserver la rétrocompatibilité. Lorsque la couche base de données en reçoit un, elle essaie de le rendre conscient en l’interprétant dans le fuseau horaire par défaut et génère un avertissement.
Malheureusement, durant les transitions d’heure d’été, certains objets datetime n’existent pas ou sont ambigus. Dans de telles situations, pytz génère une exception. C’est pourquoi vous devriez toujours créer des objets datetime conscients lorsque la prise en charge des fuseaux horaires est activée.
En pratique, c’est rarement un problème. Django produit des objets datetime conscients dans les modèles et les formulaires, et la plupart du temps, les nouveaux objets datetime sont créés à partir d’objets existants par des opérations timedelta. Le seul objet datetime qui est souvent créé dans du code applicatif est l’heure actuelle et timezone.now() fait automatiquement ce qu’il faut.
Le fuseau horaire par défaut est le fuseau horaire défini par le réglage TIME_ZONE.
Le fuseau horaire actuel est le fuseau horaire utilisé pour l’affichage.
\nVous devriez définir le fuseau horaire actuel au fuseau horaire réel de l’utilisateur avec activate(). Sinon, c’est le fuseau horaire par défaut qui est utilisé.
Le fuseau horaire actuel est l’équivalent de la langue actuelle pour les traductions. Cependant, il n’y a pas d’équivalent à l’en-tête HTTP Accept-Language que Django pourrait utiliser pour déterminer automatiquement le fuseau horaire de l’utilisateur. Au lieu de cela, Django fournit des fonctions de sélection du fuseau horaire. Utilisez-les pour bâtir une logique de sélection du fuseau horaire qui a du sens dans votre situation.
La plupart des sites Web se préoccupant des fuseaux horaires demandent aux utilisateurs leur fuseau horaire de domicile et stockent cette information dans le profil des utilisateurs. Pour les utilisateurs anonymes, ils utilisent le fuseau horaire de la majorité de leur public ou l’heure UTC. pytz propose des utilitaires, comme une liste de fuseaux horaires par pays, qu’il est possible d’exploiter pour faire une présélection des choix les plus probables.
\nVoici un exemple qui stocke le fuseau horaire actuel dans la session (la gestion d’erreur est totalement absente par simplicité).
\nAjoutez l’intergiciel suivant à MIDDLEWARE:
import pytz\n\nfrom django.utils import timezone\n\nclass TimezoneMiddleware:\n def __init__(self, get_response):\n self.get_response = get_response\n\n def __call__(self, request):\n tzname = request.session.get('django_timezone')\n if tzname:\n timezone.activate(pytz.timezone(tzname))\n else:\n timezone.deactivate()\n return self.get_response(request)\nCréez une vue capable de définir le fuseau horaire actuel :
\nfrom django.shortcuts import redirect, render\n\ndef set_timezone(request):\n if request.method == 'POST':\n request.session['django_timezone'] = request.POST['timezone']\n return redirect('/')\n else:\n return render(request, 'template.html', {'timezones': pytz.common_timezones})\nAjoutez un formulaire dans template.html dont la cible POST est cette vue :
{% load tz %}\n{% get_current_timezone as TIME_ZONE %}\n<form action="{% url 'set_timezone' %}" method="POST">\n {% csrf_token %}\n <label for="timezone">Time zone:</label>\n <select name="timezone">\n {% for tz in timezones %}\n <option value="{{ tz }}"{% if tz == TIME_ZONE %} selected{% endif %}>{{ tz }}</option>\n {% endfor %}\n </select>\n <input type="submit" value="Set">\n</form>\nLorsque vous activez la prise en charge des fuseaux horaires, Django interprète les dates/heures saisies dans les formulaires dans le fuseau horaire actuel et place des objets datetime conscients dans cleaned_data.
Si le fuseau horaire actuel génère une exception pour les dates/heures qui n’existent pas ou qui sont ambiguës car elles se trouvent dans une transition d’heure d’été (les fuseaux horaires dans pytz le font), ces dates/heures seront signalées comme non valables.
\nLorsque vous activez la prise en charge des fuseaux horaires, Django convertit les objets datetime dans le fuseau horaire actuel au moment où ils sont affichés dans un gabarit. Ce comportement est très semblable à la régionalisation des formats.
La conversion en temps local n’est pas toujours adéquate, par exemple dans le cas où vous générez du contenu à destination d’autres ordinateurs. Les filtres et balises suivants, mis à disposition par la bibliothèque de balises de gabarit tz, permettent de contrôler les conversions de fuseaux horaires.
Ces filtres acceptent aussi bien des objets datetime conscients que naïfs. À des fins de conversion, ils partent du principe que les objets naïfs sont dans le fuseau horaire par défaut. Ils renvoient toujours des objets datetime conscients.
localtimeLien vers cette rubrique#Force la conversion d’une valeur unique dans le fuseau horaire actuel.
\nPar exemple :
\n{% load tz %}\n\n{{ value|localtime }}\nutcLien vers cette rubrique#Force la conversion d’une seule valeur en UTC.
\nPar exemple :
\n{% load tz %}\n\n{{ value|utc }}\ntimezoneLien vers cette rubrique#Force la conversion d’une seule valeur dans un fuseau horaire arbitraire.
\nLe paramètre doit être une instance d’une sous-classe de tzinfo ou un nom de fuseau horaire.
Par exemple :
\n{% load tz %}\n\n{{ value|timezone:"Europe/Paris" }}\nVoici comment effectuer la migration d’un projet démarré avant que Django ne prenne en charge les fuseaux horaires.
\nLe moteur PostgreSQL stocke les dates/heures comme timestamp with time zone. En pratique, cela signifie qu’il convertit les objets datetime en UTC à partir du fuseau horaire de la connexion au moment du stockage, et à partir d’UTC vers le fuseau horaire de la connexion lors de la sélection.
En conséquence, si vous utilisez PostgreSQL, vous pouvez librement passer de USE_TZ = False à USE_TZ = True et inversement. Le fuseau horaire de la connexion de la base de données sera défini respectivement à TIME_ZONE et à UTC, ce qui fait que Django reçoit des dates/heures correctes dans tous les cas. Vous n’avez pas à convertir les données.
Les autres moteurs stockent les dates/heures sans information de fuseau horaire. Si vous passez de USE_TZ = False à USE_TZ = True, vous devez convertir vos données du temps local en UTC, ce qui n’est pas déterministe si votre temps local est sujet à l’heure d’été.
La première étape est d’ajouter USE_TZ = True à votre fichier de réglages. À ce stade, tout devrait fonctionner en principe. Si vous créez des objets datetime naïfs dans votre code, Django les rend conscients en cas de besoin.
Cependant, ces conversions peuvent échouer aux alentours des transitions d’heure d’été, ce qui signifie que vous n’obtenez pas encore tous les bénéfices de la prise en charge des fuseaux horaires. Il est également probable que vous rencontriez quelques problèmes car il est impossible de comparer une date/heure naïve avec une date/heure consciente. Comme Django vous donne maintenant des dates/heures conscientes, vous obtiendrez des exceptions chaque fois que vous comparez une date/heure provenant d’un modèle ou d’un formulaire avec une date/heure naïve que vous avez créée dans votre code.
\nLa seconde étape est donc de réviser votre code pour que chaque endroit où vous créer des objets datetime, ceux-ci soient conscients. Cela peut se faire progressivement. django.utils.timezone définit quelques utilitaires bien pratiques pour du code compatible : now(), is_aware(), is_naive(), make_aware() et make_naive().
Finalement, pour vous aider à trouver le code qui a besoin d’être mis à jour, Django émet un avertissement lorsque vous essayez d’enregistrer une date/heure naïve dans la base de données :
\nRuntimeWarning: DateTimeField ModelName.field_name received a naive\ndatetime (2012-01-01 00:00:00) while time zone support is active.\nDurant le développement, vous pouvez transformer ces avertissements en exceptions et obtenir une trace d’appel en ajoutant ce qui suit dans votre fichier de réglages :
\nimport warnings\nwarnings.filterwarnings(\n 'error', r"DateTimeField .* received a naive datetime",\n RuntimeWarning, r'django\\.db\\.models\\.fields',\n)\nLors de la sérialisation d’une date/heure consciente, le décalage UTC est pris en compte, comme ceci :
\n"2011-09-01T13:20:30+03:00"\nAlors que pour une date/heure naïve, ce n’est pas le cas :
\n"2011-09-01T13:20:30"\nPour les modèles comportant des champs DateTimeField, cette différence rend impossible l’écriture d’un instantané fonctionnant à la fois avec et sans prise en charge des fuseaux horaires.
Les instantanés générés avec USE_TZ = False ou avant Django 1.4 utilisent le format « naïf ». Si votre projet contient de tels instantanés et que vous activez la prise en charge des fuseaux horaires, vous verrez des exceptions RuntimeWarning lorsque vous les chargez. Pour vous débarrasser des ces avertissements, vous devez convertir vos instantanés au format « conscient ».
Vous pouvez régénérer les instantanés avec loaddata, puis dumpdata. Ou s’ils ne sont pas trop gros, vous pouvez les modifier et ajouter le décalage UTC correspondant à votre TIME_ZONE dans chaque objet datetime sérialisé.
Je n’ai pas besoin de plusieurs fuseaux horaires. Dois-je activer la prise en charge des fuseaux horaires ?
\nOui. Lorsque la prise en charge des fuseaux horaires est activée, Django utilise un modèle plus précis du temps local. Cela vous protège de bogues subtils et non reproductibles lors des transitions d’heure d’été (DST).
\nLorsque vous activez la prise en charge des fuseaux horaires, vous allez rencontrer certaines erreurs parce que vous utilisez des dates/heures naïves là où Django s’attend à des dates/heures conscientes. De telles erreurs apparaissent lors de l’exécution des tests. Vous apprendrez rapidement comment éviter les opérations non valides.
\nD’un autre côté, les bogues qui proviennent d’une non prise en charge des fuseaux horaires sont beaucoup plus durs à prévenir, à diagnostiquer et à corriger. Tout ce qui touche aux tâches planifiées ou à l’arithmétique des dates/heures est sujet à de subtils bogues qui ne vous affecteront qu’une ou deux fois par année.
\nC’est pour ces raisons que la prise en charge des fuseaux horaires est activée par défaut dans les nouveaux projets, et vous devriez garder ce réglage pour autant que vous n’ayez pas une bonne raison de ne pas le faire.
\nJ’ai activé la prise en charge des fuseaux horaires. Suis-je tranquille ?
\nPeut-être. Vous êtes mieux protégé des bogues liés à l’heure d’été, mais il est toujours possible que vous vous trompiez en convertissant sans précaution des objets datetime naïfs en objets datetime conscients et vice-versa.
Si votre application se connecte à d’autres systèmes, par exemple si elle interroge un service Web, prenez soin de bien définir les dates/heures. Pour les transmettre de manière fiable, leur représentation doit inclure le décalage UTC ou leur valeur doit être en UTC (ou les deux !).
\nFinalement, notre système de calendrier contient des pièges intéressants pour les ordinateurs :
\n>>> import datetime\n>>> def one_year_before(value): # DON'T DO THAT!\n... return value.replace(year=value.year - 1)\n>>> one_year_before(datetime.datetime(2012, 3, 1, 10, 0))\ndatetime.datetime(2011, 3, 1, 10, 0)\n>>> one_year_before(datetime.datetime(2012, 2, 29, 10, 0))\nTraceback (most recent call last):\n...\nValueError: day is out of range for month\n(Pour implémenter cette fonction, vous devez décider si 2012-02-29 moins une année est 2011-02-28 ou 2011-03-01, ce qui dépend de vos exigences métier)
\nComment interagir avec une base de données stockant les dates/heures en temps local ?
\nDéfinissez l’option TIME_ZONE au fuseau horaire correspondant à cette base de données dans le réglage DATABASES.
C’est utile pour se connecter à une base de données qui ne gère pas les fuseaux horaires et qui n’est pas gérée par Django lorsque USE_TZ vaut True.
Mon application plante avec TypeError: can't compare offset-naive and offset-aware datetimes , qu’est-ce que je fais faux ?
Reproduisons cette erreur en comparant des objets datetime naïf et conscient :
>>> import datetime\n>>> from django.utils import timezone\n>>> naive = datetime.datetime.utcnow()\n>>> aware = timezone.now()\n>>> naive == aware\nTraceback (most recent call last):\n...\nTypeError: can't compare offset-naive and offset-aware datetimes\nSi vous rencontrez cette erreur, il est très probable que votre code compare ces deux choses :
\nun objet datetime fourni par Django, par exemple une valeur lue à partir d’un champ de formulaire ou d’un champ de modèle. Comme vous avez activé la prise en charge des fuseaux horaires, cet objet est conscient.
un objet datetime généré dans votre code de manière naïve (sinon vous ne liriez pas ceci).
Généralement, la solution correcte est de modifier votre code pour qu’il utilise plutôt un objet datetime conscient.
Si vous écrivez une application réutilisable qui doit fonctionner indépendamment de la valeur de USE_TZ, il peut être utile d’appeler django.utils.timezone.now(). Cette fonction renvoie la date et l’heure actuelle sous forme d’objet datetime naïf lorsque USE_TZ = False et sous forme d’objet datetime conscient lorsque USE_TZ = True. Vous pouvez y ajouter ou soustraire une valeur datetime.timedelta selon vos besoins.
Je vois beaucoup de RuntimeWarning: DateTimeField received a naive datetime (YYYY-MM-DD HH:MM:SS) while time zone support is active , est-ce mauvais signe ?
Lorsque la prise en charge des fuseaux horaires est activée, la couche de base de données s’attend à ne recevoir que des objets datetime conscients de votre code. Cet avertissement se produit lorsqu’elle reçoit un objet datetime naïf. Cela indique que vous n’avez pas terminé de transformer votre code pour la prise en charge des fuseaux horaires. Veuillez vous référer au guide de migration pour des indications supplémentaires sur ce processus.
Dans l’intervalle et par rétrocompatibilité, Django considère l’objet datetime comme se trouvant dans le fuseau horaire par défaut, ce qui correspond généralement à la réalité.
now.date() est hier ! (ou demain)
Si vous avez toujours utilisé des objets datetime naïfs, vous pensez probablement pouvoir convertir un objet datetime en objet date en appelant sa méthode date(). Vous considérez également que date est très semblable à datetime, avec moins de précision.
Rien de cela n’est vrai dans un environnement conscient des fuseaux horaires :
\n>>> import datetime\n>>> import pytz\n>>> paris_tz = pytz.timezone("Europe/Paris")\n>>> new_york_tz = pytz.timezone("America/New_York")\n>>> paris = paris_tz.localize(datetime.datetime(2012, 3, 3, 1, 30))\n# This is the correct way to convert between time zones with pytz.\n>>> new_york = new_york_tz.normalize(paris.astimezone(new_york_tz))\n>>> paris == new_york, paris.date() == new_york.date()\n(True, False)\n>>> paris - new_york, paris.date() - new_york.date()\n(datetime.timedelta(0), datetime.timedelta(1))\n>>> paris\ndatetime.datetime(2012, 3, 3, 1, 30, tzinfo=<DstTzInfo 'Europe/Paris' CET+1:00:00 STD>)\n>>> new_york\ndatetime.datetime(2012, 3, 2, 19, 30, tzinfo=<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>)\nComme le montre cet exemple, le même objet datetime peut représenter une date différente selon le fuseau horaire dans lequel il est représenté. Mais le problème réel est plus fondamental.
Un objet datetime représente un point dans le temps. C’est absolu et cela ne dépend de rien d’autre. Au contraire, une date est un concept calendaire. Il s’agit d’une période de temps dont les limites dépendent du fuseau horaire dans lequel la date est considérée. Comme vous pouvez le voir, ces deux concepts sont fondamentalement différents et la conversion d’un objet datetime en un objet date n’est pas une opération déterministe.
Qu’est-ce que cela signifie en pratique ?
\nGénéralement, vous devriez éviter de convertir un objet datetime en date. Par exemple, vous pouvez utiliser le filtre de gabarit date pour n’afficher que la partie date d’un objet datetime. Ce filtre convertit l’objet datetime dans le fuseau horaire actuel avant de le mettre en forme, s’assurant ainsi que le résultat produit sera correct.
Si vous avez réellement besoin d’effectuer vous-même la conversion, vous devez d’abord prendre soin de convertir l’objet datetime dans le fuseau horaire approprié. Il s’agit généralement du fuseau horaire actuel :
>>> from django.utils import timezone\n>>> timezone.activate(pytz.timezone("Asia/Singapore"))\n# For this example, we set the time zone to Singapore, but here's how\n# you would obtain the current time zone in the general case.\n>>> current_tz = timezone.get_current_timezone()\n# Again, this is the correct way to convert between time zones with pytz.\n>>> local = current_tz.normalize(paris.astimezone(current_tz))\n>>> local\ndatetime.datetime(2012, 3, 3, 8, 30, tzinfo=<DstTzInfo 'Asia/Singapore' SGT+8:00:00 STD>)\n>>> local.date()\ndatetime.date(2012, 3, 3)\nJ’obtiens une erreur « Are time zone definitions for your database installed? »
Si vous utilisez MySQL, consultez la section Définitions de fuseaux horaires des notes MySQL pour plus d’instructions sur le chargement des définitions de fuseaux horaires.
\nJ’ai une chaîne "2012-02-21 10:28:45" et je sais qu’elle est dans le fuseau horaire ** `` »Europe/Helsinki »``. Comment puis-je la transformer en un objet ``datetime`` conscient ?
C’est exactement le rôle de pytz.
\n>>> from django.utils.dateparse import parse_datetime\n>>> naive = parse_datetime("2012-02-21 10:28:45")\n>>> import pytz\n>>> pytz.timezone("Europe/Helsinki").localize(naive, is_dst=None)\ndatetime.datetime(2012, 2, 21, 10, 28, 45, tzinfo=<DstTzInfo 'Europe/Helsinki' EET+2:00:00 STD>)\nNotez que localize est une extension de pytz à l’API tzinfo. Il peut être nécessaire d’intercepter les erreurs pytz.InvalidTimeError. La documentation de pytz contient davantage d’exemples. Il est recommandé de la consulter avant d’essayer de manipuler des objets datetime conscients.
Comment puis-je obtenir le temps local dans le fuseau horaire actuel ?
\nEt bien, la première question à se poser est : est-ce réellement nécessaire ?
\nLe temps local ne doit être utilisé que lorsque l’on interagit avec des humains, et la couche des gabarits fournit des filtres et des balises pour convertir des objets datetime dans le fuseau horaire de votre choix.
De plus, Python sait comparer des objets datetime conscients, en prenant en compte les décalages UTC si nécessaire. C’est beaucoup plus simple (et potentiellement plus rapide) d’écrire tout le code des modèles et des vues en UTC. Ainsi, dans la plupart des cas, l’objet datetime en UTC renvoyé par django.utils.timezone.now() sera suffisant.
Par souci d’exhaustivité, si vous devez vraiment obtenir le temps local dans le fuseau horaire actuel, voici comment vous pouvez l’obtenir :
\n>>> from django.utils import timezone\n>>> timezone.localtime(timezone.now())\ndatetime.datetime(2012, 3, 3, 20, 10, 53, 873365, tzinfo=<DstTzInfo 'Europe/Paris' CET+1:00:00 STD>)\nDans cet exemple, le fuseau horaire actuel est "Europe/Paris".
Comment puis-je voir tous les fuseaux horaires disponibles ?
\npytz fournit des utilitaires, y compris une liste des fuseaux horaires actuels et une liste de tous les fuseaux horaires disponibles, parmi lesquels se trouvent aussi certains qui n’ont qu’un intérêt historique.
\n