タイムゾーンのサポートが有効のとき、Django は内部的に aware なタイムゾーンオブジェクトを使用して、データベース内に UTC で日時の情報を保持します。そして、テンプレートやフォーム内でエンドユーザのタイムゾーンに変換します。
\nこの機能は、ユーザが複数のタイムゾーンを使用しており、またユーザに対して彼らの時計と同じ日時を表示したいときに有用です。
\nたとえウェブサイトが 1 つのタイムゾーンでしか使われないとしても、それでもデータベース内に UTC でデータを保持するのは良い実装方法です。主な理由は夏時間 (DST) です。多くの国では DST の制度を採用しており、時計は春に進んで秋に戻ります。もし現地時刻で運用していたら、この変換が起きる年に 2 回、エラーに遭遇することになるでしょう。(pytz ドキュメントが この問題 を大変詳しく論じています。) これはブログにとっては重要な問題ではありませんが、年に 2 回請求金額が 1 時間分多くなったり少なくなったりするのは問題です。この問題の解決策は、コード内では UTC を使い、エンドユーザとやり取りするときだけ現地時刻を使用することです。
\nタイムゾーンサポートは、デフォルトでは無効化されています。有効化するためには、設定ファイルで set USE_TZ = True とセットしてください。pytz をインストールすることが強く推奨されますが、特定のデータベースバックエンド、オペレーティングシステム、タイムゾーンによっては必ずしも必要ではありません。日付や時刻に対する問い合わせでエラーに遭遇した場合は、バグを疑う前に pytz をインストールしてみてください。インストールは以下のようにシンプルです:
$ pip install pytz\n特定の問題と格闘している場合は、time zone FAQ を参照してください。
\nPython の datetime.datetime のオブジェクトには、タイムゾーン情報を保持するために使える tzinfo 属性があり、これは datetime.tzinfo のサブクラスのインスタンスで表されます。 この属性がセットされオフセットを示すとき、datetime オブジェクトは aware となります。それ以外の場合は naive となります。
is_aware() is_naive() を使って、datatime を aware にするか native にするかを決めることもできます。
タイムゾーンサポートが無効化されているときは、Django は現地時刻で native な datetime オブジェクトを使用します。これは、多くのケースでシンプルかつ十分です。このモードでは、現在時刻を取得するには以下のように記述します:
\nimport datetime\n\nnow = datetime.datetime.now()\nタイムゾーンサポートが有効化 (USE_TZ=True ) されているときは、Django は タイムゾーンを認識する (awareな) datetime オブジェクトを使用します。コード内で datetime オブジェクトを作成した場合も、aware となります。このモードでは、上の例は以下のようになります:
from django.utils import timezone\n\nnow = timezone.now()\n後方互換性を維持するため、setting:USE_TZ が True のときでも、Django は naive な datetime オブジェクトを受け入れます。データベースレイヤがこれを受け取ったとき、default time zone で変換して aware に直そうとし、警告を投げます。
残念ながら、DST の移行の間、いくつかの datetimes は存在しないか不明瞭になります。このような状況では、pytz は例外を投げます。たとえば pytz がインストールされていない場合に備えたフォールバックとして使われるローカルタイムゾーンのような、他の tzinfo の実装は、例外を投げるか不正確な結果を返す可能性があります。したがって、タイムゾーンサポートを有効化しているときには、常に aware な datetime オブジェクトを作成するべきなのです。
実際には、これはめったに問題になりません。Django はモデルやーフォームでは aware な datetime オブジェクトを渡し、ほとんどの場合、新しい datetime オブジェクトは timedelta 計算を通じて他の日時から作成されます。唯一アプリケーションのコード内でよく作成される datetime は現在の時刻で、timezone.now() は自動的に適切な処理を行います。
デフォルトタイムゾーン は、TIME_ZONE 設定によって定義されるタイムゾーンです。
タイムゾーン は、レンダリングに使われるタイムゾーンです。
\nactivate() を使って、エンドユーザの実際のタイムゾーンに対するカレントタイムゾーンをセットする必要があります。 そうしないと、デフォルトタイムゾーンが使用されます。
カレントタイムゾーンは、翻訳に対する locale に相当します。ただし、Django がユーザのタイムゾーンを自動的に決めるために使える Accept-Language HTTP ヘッダに相当するものはありません。代わりに、Django は タイムゾーン選択関数 を提供しています。これらを使って、あなたにとって有用なタイムゾーン選択ロジックを組み立ててください。
タイムゾーンを扱うほとんどのウェブサイトは、ユーザにどのタイムゾーンに住んでいるかを尋ねて、その情報をユーザのプロフィールに保存します。匿名ユーザに対しては、ウェブサイトが優先する訪問者のタイムゾーンか UTC を使います。pytz には、国ごとのタイムゾーンのリストのようなヘルパーがあり、最も可能性の高いタイムゾーンを事前選択するために使うことができます。
\n以下は、セッション内にカレントタイムゾーンを保持する例です。(シンプルにするため、全体的にエラー処理を省略しています。)
\n以下のミドルウェアを MIDDLEWARE に追加します:
import pytz\n\nfrom django.utils import timezone\nfrom django.utils.deprecation import MiddlewareMixin\n\nclass TimezoneMiddleware(MiddlewareMixin):\n def process_request(self, request):\n tzname = request.session.get('django_timezone')\n if tzname:\n timezone.activate(pytz.timezone(tzname))\n else:\n timezone.deactivate()\nカレントタイムゾーンをセットできるビューを作成します:
\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})\nこのビューに POST するフォームを template.html に入れます:
{% 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="selected"{% endif %}>{{ tz }}</option>\n {% endfor %}\n </select>\n <input type="submit" value="Set" />\n</form>\nタイムゾーンサポートを有効にしたとき、Django はフォーム内に入力された日時を カレントタイムゾーン で変換し、cleaned_data 内で aware な datetime オブジェクトを返します。
カレントタイムゾーンが、(pytz によるタイムゾーンが行う) DST 変換でうまくいかなかったために、存在しなかったり曖昧な日時に対して例外を投げた場合、この日時は無効な値としてレポートされます。
\nタイムゾーンサポートを有効にしているとき、Django はテンプレートでレンダリングする際に aware な datetime オブジェクトを カレントタイムゾーン に連関します。この動作は、 表示形式のローカル化 と非常によく似ています。
\n\n現地時刻への転換は、適切ではないことがあります -- 人手はなくコンピュータに対してアウトプットを生成するときなどです。以下のフィルタやタグ (tz テンプレートタグライブラリによって提供されています) で、タイムゾーンの転換をコントロールできます。
以下のフィルタは、aware と native の日時の両表を受け入れます。転換するために、これらは native な日時はデフォルトタイムゾーンにあると仮定します。これらは常に aware な日時を返します。
\nlocaltimeLink to this heading#単一の値からカレントタイムゾーンへの変換を強制します。
\nFor example:
\n{% load tz %}\n\n{{ value|localtime }}\nutcLink to this heading#単一の値から UTC への転換を強制します。
\nFor example:
\n{% load tz %}\n\n{{ value|utc }}\ntimezoneLink to this heading#単一の値から指定したタイムゾーンへの転換を強制します。
\n属性は tzinfo サブクラスのインスタンスかタイムゾーン名である必要があります。タイムゾーン名の場合は、pytz が必要です。
For example:
\n{% load tz %}\n\n{{ value|timezone:"Europe/Paris" }}\n以下は、Django がタイムゾーンをサポートする以前に開始したプロジェクトを移行する方法です。
\nThe PostgreSQL backend stores datetimes as timestamp with time zone. In\npractice, this means it converts datetimes from the connection's time zone to\nUTC on storage, and from UTC to the connection's time zone on retrieval.
As a consequence, if you're using PostgreSQL, you can switch between USE_TZ\n= False and USE_TZ = True freely. The database connection's time zone\nwill be set to TIME_ZONE or UTC respectively, so that Django\nobtains correct datetimes in all cases. You don't need to perform any data\nconversions.
他のバックエンドは、タイムゾーン情報なしで日時を保持します。USE_TZ = False から USE_TZ = True に切り替えた場合、現地時刻から UTC に転換する必要があります -- あなたの現地時刻に DST がある場合、これは確実に 1 つに決まるわけではありません。
最初のステップは、設定ファイルに USE_TZ = True を加えて (可能ならば) pytz をインストールすることです。 この時点では、ほとんどのことは動作します。コード内で naive な datetime オブジェクトを作成した場合、Django は必要に応じてこれらを aware に変更します。
ただし、これらの変換ではDSTの移行が失敗する可能性があります。これは、まだ対ー無ゾーンサポートの利点が完全には得られていないことを意味します。 また、naive な日時と aware な日時を比較することは不可能なため、いくつかの問題に遭遇する可能性があります。 Django はaware な日時を提供するので、モデルやフォームから来た datetime と、コード内に作成した naive な datetime を比較すると例外が発生します。
\nしたがって、第2のステップは、datetime オブジェクトをインスタンス化している部分を aware に変更するため、コードをリファクタリングすることです。 これは段階的に行うことができます。django.utils.timezone は、互換性のための便利なヘルパーをいくつ定義しています now()、is_aware()、is_naive()、make_aware() そして make_naive() です。
最後に、アップグレードが必要なコードを特定しやすいように、naive な日時をデータベースに保存しようとすると、Django は警告を出します:
\nRuntimeWarning: DateTimeField ModelName.field_name received a naive\ndatetime (2012-01-01 00:00:00) while time zone support is active.\n開発中、以下を設定ファイルに追加することで、これらの警告を例外として発生するように変更し、トラックバックを得ることができます:
\nimport warnings\nwarnings.filterwarnings(\n 'error', r"DateTimeField .* received a naive datetime",\n RuntimeWarning, r'django\\.db\\.models\\.fields',\n)\naware な日時をシリアライズするとき、以下のように UTC オフセットが含まれます:
\n"2011-09-01T13:20:30+03:00"\nnaive な日時に対しては、当然ながら含まれません:
\n"2011-09-01T13:20:30"\nDateTimeField を使ったモデルに対しては、この違いにより、タイムゾーンサポートのありとなし両方に対して動作するフィクスチャーを記述することができません。
USE_TZ = False もしくは Django 1.4 以前 で生成されたフィクスチャーは、"naive" 形式を使用します。このようなフィクス茶がプロジェクトに含まれる場合、タイムゾーンサポートを有効化した後に、これらをロードする際に RuntimeWarning を参照してください。警告を破棄するには、これらのフィクスチャーを "aware" 形式に転換する必要があります。
loaddata と dumpdata を使って、フィクスチャーを際生成できます。もしくは、これらが十分小さい場合には、TIME_ZONE がシリアライズされたそれぞれの日時と一致する UTC オフセットをこれらに単に追加できます。
複数のタイムゾーンを必要としません。タイムゾーンサポートを有効化するべきですか？
\nはい。タイムゾーンサポートが有効のとき、Django は現地時刻のより正確なモデルを使用します。これは、夏時間 (DST) 変換まわりの微細で再現不可能なバグからあなたを守ります。
\nIn this regard, time zones are comparable to unicode in Python. At first\nit's hard. You get encoding and decoding errors. Then you learn the rules.\nAnd some problems disappear -- you never get mangled output again when your\napplication receives non-ASCII input.
When you enable time zone support, you'll encounter some errors because\nyou're using naive datetimes where Django expects aware datetimes. Such\nerrors show up when running tests and they're easy to fix. You'll quickly\nlearn how to avoid invalid operations.
\nOn the other hand, bugs caused by the lack of time zone support are much\nharder to prevent, diagnose and fix. Anything that involves scheduled tasks\nor datetime arithmetic is a candidate for subtle bugs that will bite you\nonly once or twice a year.
\nFor these reasons, time zone support is enabled by default in new projects,\nand you should keep it unless you have a very good reason not to.
\nタイムゾーンサポートを有効化しました。私は安全ですか？
\nおそらく。DST 関連のバグからは守られるようになりましたが、それでも不用意な変換 ( naive な日時を aware な日時に変更する、およびその逆）ことによって自ら墓穴を掘る可能性があります。
\nIf your application connects to other systems -- for instance, if it queries\na Web service -- make sure datetimes are properly specified. To transmit\ndatetimes safely, their representation should include the UTC offset, or\ntheir values should be in UTC (or both!).
\nFinally, our calendar system contains interesting traps for computers:
\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(To implement this function, you must decide whether 2012-02-29 minus\none year is 2011-02-28 or 2011-03-01, which depends on your business\nrequirements.)
\npytz をインストールするべきですか？
\nはい。Django は外部依存を要求としないことをポリシーとしており、この理由のために pytz は任意となっています。しかし、インストールすると非常に安全となります。
\nAs soon as you activate time zone support, Django needs a definition of the\ndefault time zone. When pytz is available, Django loads this definition\nfrom the tz database. This is the most accurate solution. Otherwise, it\nrelies on the difference between local time and UTC, as reported by the\noperating system, to compute conversions. This is less reliable, especially\naround DST transitions.
\nFurthermore, if you want to support users in more than one time zone, pytz\nis the reference for time zone definitions.
\n現地時刻で日時を保持しているデータベースと、どのようにやり取りすればいいですか？
\nTIME_ZONE オプションを、DATABASES 設定内のデータベースに適したタイムゾーンにセットしてください。
This is useful for connecting to a database that doesn't support time zones\nand that isn't managed by Django when USE_TZ is True.
私のアプリケーションが TypeError: can't compare offset-naive and offset-aware datetimes とともにクラッシュします -- 何がいけませんか？
naive と aware な日時を比較することによって、このエラーを再現してみましょう:
\n>>> 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\nこのエラーに遭遇した場合、あなたのコードはこれら 2 つを比較している可能性が高いです:
\na datetime provided by Django -- for instance, a value read from a form or\na model field. Since you enabled time zone support, it's aware.
a datetime generated by your code, which is naive (or you wouldn't be\nreading this).
Generally, the correct solution is to change your code to use an aware\ndatetime instead.
\nIf you're writing a pluggable application that's expected to work\nindependently of the value of USE_TZ, you may find\ndjango.utils.timezone.now() useful. This function returns the current\ndate and time as a naive datetime when USE_TZ = False and as an aware\ndatetime when USE_TZ = True. You can add or subtract\ndatetime.timedelta as needed.
多くの RuntimeWarning: DateTimeField received a naive datetime (YYYY-MM-DD HH:MM:SS) while time zone support is active が発生します。 -- これは悪いことですか？
When time zone support is enabled, the database layer expects to receive\nonly aware datetimes from your code. This warning occurs when it receives a\nnaive datetime. This indicates that you haven't finished porting your code\nfor time zone support. Please refer to the migration guide for tips on this process.
\nIn the meantime, for backwards compatibility, the datetime is considered to\nbe in the default time zone, which is generally what you expect.
\nnow.date() が昨日 (もしくは明日) になります！
If you've always used naive datetimes, you probably believe that you can\nconvert a datetime to a date by calling its date()\nmethod. You also consider that a date is a lot like a\ndatetime, except that it's less accurate.
None of this is true in a time zone aware environment:
\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>)\nAs this example shows, the same datetime has a different date, depending on\nthe time zone in which it is represented. But the real problem is more\nfundamental.
\nA datetime represents a point in time. It's absolute: it doesn't depend\non anything. On the contrary, a date is a calendaring concept. It's a\nperiod of time whose bounds depend on the time zone in which the date is\nconsidered. As you can see, these two concepts are fundamentally different,\nand converting a datetime to a date isn't a deterministic operation.
\nWhat does this mean in practice?
\nGenerally, you should avoid converting a datetime to\ndate. For instance, you can use the date\ntemplate filter to only show the date part of a datetime. This filter will\nconvert the datetime into the current time zone before formatting it,\nensuring the results appear correctly.
If you really need to do the conversion yourself, you must ensure the\ndatetime is converted to the appropriate time zone first. Usually, this\nwill be the current timezone:
\n>>> from django.utils import timezone\n>>> timezone.activate(pytz.timezone("Asia/Singapore"))\n# For this example, we just 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)\nエラー "Are time zone definitions for your database and pytz installed?" が発生します。pytz はインストールされているので、データベースが問題だと推測するのですが？
If you are using MySQL, see the Time zone definitions section\nof the MySQL notes for instructions on loading time zone definitions.
\n文字列 "2012-02-21 10:28:45" があり、 "Europe/Helsinki" タイムゾーンであることが分かっています。どうやって aware な日時に変換しますか？
これは、まさに 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>)\nNote that localize is a pytz extension to the tzinfo\nAPI. Also, you may want to catch pytz.InvalidTimeError. The\ndocumentation of pytz contains more examples. You should review it\nbefore attempting to manipulate aware datetimes.
どうやってカレントタイムゾーンで現在時刻を取得しますか？
\nそうですね。最初に質問させてください。それは本当に必要ですか？
\n人間とやり取りするときだけ、現地時刻を使うべきです。そして、テンプレートレイヤは日時をあなたが選択したタイムゾーンに転換するための フィルタとタグ タグを提供しています。
\nFurthermore, Python knows how to compare aware datetimes, taking into\naccount UTC offsets when necessary. It's much easier (and possibly faster)\nto write all your model and view code in UTC. So, in most circumstances,\nthe datetime in UTC returned by django.utils.timezone.now() will be\nsufficient.
For the sake of completeness, though, if you really want the local time\nin the current time zone, here's how you can obtain it:
\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>)\nこの例では、pytz がインストールされていて、カレントタイムゾーンは "Europe/Paris" です。
全ての利用可能なタイムゾーンを参照するにはどうすればいいですか？
\npytz はヘルパーを提供しており、これはカレントタイムゾーンのリストと全ての利用可能なタイムゾーンのリストを含んでいます -- そのうちのいくつかは単に歴史的な関連です。
\n