14.2 time -- 時刻データへのアクセスと変換

このモジュールでは、時刻に関するさまざまな関数を提供します。ほとんどの 関数が利用可能ですが、全ての関数が全てのプラットフォームで利用可能な わけではありません。 このモジュールで定義されているほとんどの関数は、プラットフォーム上の 同名の C ライブラリ関数を呼び出します。これらの関数に対する意味付け はプラットフォーム間で異なるため、プラットフォーム提供のドキュメント を読んでおくと便利でしょう。

まずいくつかの用語の説明と慣習について整理します。

このモジュールでは以下の関数とデータ型を定義します:

accept2dyear
2 桁の西暦年を使えるかを指定するブール型の値です。標準では真ですが、 環境変数 PYTHONY2K が空文字列でない値に設定されている場合には 偽になります。実行時に変更することもできます。

altzone
ローカルの夏時間タイムゾーンにおける UTC からの時刻オフセットで、西に 行くほど増加する秒で表した値です (ほとんどの西ヨーロッパでは負になり、 アメリカでは正、イギリスではゼロになります) 。 daylight がゼロでないときのみ使用してください。

asctime( [t])
gmtime()localtime() が返す時刻を表現する タプル又は struct_timeを、'Sun Jun 20 23:21:05 1993' といった書式の 24 文字 の文字列に変換します。t が与えられていない場合には、 localtime() が返す現在の時刻が使われます。 asctime() はロケール情報を使いません。 注意: 同名の C の関数と違って、末尾には改行文字はありません。 バージョン 2.1 で 変更 された仕様: tuple を省略できるようになりました。

clock( )
Unixでは、現在のプロセッサ時間秒を浮動小数点数で返します。 時刻の精度および ``プロセッサ時間 (processor time)'' の定義そのものは同じ 名前の C 関数に依存します。いずれにせよ、この関数は Python の ベンチマーク や 計時アルゴリズムに使われています。

Windows では、最初にこの関数が呼び出されてからの経過時間を wall-clock 秒で返します。この関数は Win32 関数 QueryPerformanceCounter() に基づいていて、その精度 は通常 1 マイクロ秒以下です。

ctime( [secs])
エポックからの経過秒数で表現された時刻を、ローカルの時刻を表現 する文字列に変換します。secs を指定しない、または None を指定した場合、time() が返す値を現在の時刻 として使います。 ctime(secs)asctime(localtime(secs)) と同じです。ctime() はロケール情報を使いません。 バージョン 2.1 で 変更 された仕様: secs を省略できるようになりました バージョン 2.4 で 変更 された仕様: secsNone の場合に現在時刻を 使うようになりました

daylight
DST タイムゾーンが定義されている場合ゼロでない値になります。

gmtime( [secs])
エポックからの経過時間で表現された時刻を、UTC におけるstruct_time に変換します。このとき dst フラグは常にゼロとして扱われます。 secs を指定しない、またはNone を指定した場合、 time() が返す値を現在の時刻として使います。 秒の端数は無視されます。struct_time のレイアウトについては上を参照してください。 バージョン 2.1 で 変更 された仕様: secs を省略できるようになりました バージョン 2.4 で 変更 された仕様: secsNone の場合に現在時刻を 使うようになりました

localtime( [secs])
gmtime() に似ていますが、ローカルタイムに変換します。 secs を指定しない、またはNone を指定した場合、 time() が返す値を現在の時刻として使います。 現在の時刻に DST が適用される場合、 dst フラグは 1 に設定 されます。 バージョン 2.1 で 変更 された仕様: secs を省略できるようになりました。 バージョン 2.4 で 変更 された仕様: secsNone の場合に現在時刻を 使うようになりました

mktime( t)
localtime() の逆を行う関数です。引数は struct_timeか 完全な 9 つの要素 全てに値の入ったタプル (dst フラグも必要です; 現在の時刻に DST が 適用されるか不明の場合には -1 を使ってください) で、 UTC ではなく ローカルの 時刻を指定します。 time() との互換性のために浮動小数点数の値を返します。 入力の値が正しい時刻で表現できない場合、例外OverflowError または ValueError が送出されます (どちらが送出されるかは Python および その下にある C ライブラリのどちらにとって無効な値が 入力されたかで決まります) 。この関数で生成できる最も昔の時刻値は プラットフォームに依存します。

sleep( secs)
与えられた秒数の間実行を停止します。より精度の高い実行停止時間を指定 するために、引数は浮動小数点にしてもかまいません。何らかのシステム シグナルがキャッチされた場合、それに続いてシグナル処理ルーチンが実行 され、 sleep() を停止してしまいます。従って実際の実行停止 時間は要求した時間よりも短くなるかもしれません。また、システムが 他の処理をスケジューリングするために、実行停止時間が要求した時間よりも 多少長い時間になることもあります。

strftime( format[, t])
gmtime()localtime() が返す時刻値タプル 又はstruct_timeを、 format で指定した文字列形式に変換します。 t が与えられていない場合、localtime() が返す 現在の時刻が使われます。format は文字列でなくてはなりません。 t のいずれかのフィールドが許容範囲外の数値であった場合、 ValueError を送出します。 バージョン 2.1 で 変更 された仕様: t を省略できるようになりました。 バージョン 2.4 で 変更 された仕様: t のフィールド値が許容範囲外の値の場合に ValueError を送出するようになりました バージョン 2.5 で 変更 された仕様: 0 は時刻値タプルのどこでも使用可能になりました。 もし不正な値の場合には正常な値に修正されます。

format 文字列には以下の指示語 (directive) を埋め込むことが できます。これらはフィールド長や精度のオプションを付けずに表され、 strftime() の結果の対応する文字列と入れ替えられます:

Directive Meaning Notes
%a ロケールにおける省略形の曜日名。
%A ロケールにおける省略なしの曜日名。
%b ロケールにおける省略形の月名。
%B ロケールにおける省略なしの月名。
%c ロケールにおける適切な日付および時刻表現。
%d 月の始めから何日目かを表す 10 進数 [01,31]。
%H (24 時間計での) 時を表す 10 進数 [00,23]。
%I (12 時間計での) 時を表す 10 進数 [01,12]。
%j 年の初めから何日目かを表す 10 進数 [001,366]。
%m 月を表す 10 進数 [01,12]。
%M 分を表す 10 進数 [00,59]。
%p ロケールにおける AM または PM に対応する文字列。 (1)
%S 秒を表す 10 進数 [00,61]。 (2)
%U 年の初めから何週目か (日曜を週の始まりとします)を表す 10 進数 [00,53]。年が明けてから最初の日曜日までの全ての 曜日は 0 週目に属すると見なされます。 (3)
%w 曜日を表す 10 進数 [0(日曜日),6]。
%W 年の初めから何週目か (日曜を週の始まりとします)を表す 10 進数 [00,53]。年が明けてから最初の月曜日までの全ての 曜日は 0 週目に属すると見なされます。 (3)
%x ロケールにおける適切な日付の表現。
%X ロケールにおける適切な時刻の表現。
%y 上 2 桁なしの西暦年を表す 10 進数 [00,99]。
%Y 上 2 桁付きの西暦年を表す 10 進数。
%Z タイムゾーンの名前 (タイムゾーンがない場合には空文字列)。
%% 文字 "%" 自体の表現。

注意:

(1)
strptime() 関数で使う場合、%p ディレクティブが 出力結果の時刻フィールドに影響を及ぼすのは、時刻を解釈するために %I を使ったときのみです。
(2)
値の幅は間違いなく 0 to 61 です; これはうるう秒と、 (ごく稀ですが)2 重のうるう秒のためのものです。
(3)
strptime() 関数で使う場合、%U および %W を計算に使うのは曜日と年を指定したときだけです。

以下に RFC 2822 インターネット電子メール標準で定義されている日付 表現と互換の書式の例を示します。 14.1

>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'

いくつかのプラットフォームではさらにいくつかの指示語がサポートされて いますが、標準 ANSI C で意味のある値はここで列挙したものだけです。

いくつかのプラットフォームでは、フィールドの幅や精度を指定する オプションが以下のように指示語の先頭の文字 "%" の直後に 付けられるようになっていました; この機能も移植性はありません。 フィールドの幅は通常 2 ですが、%j は例外で 3 です。

strptime( string[, format])
時刻を表現する文字列をフォーマットに従って解釈します。返される値は gmtime()localtime() が返すようなstruct_time です。format パラメタは strftime() で使うものと 同じ指示語を使います; このパラメタの値はデフォルトでは "%a %b %d %H:%M:%S %Y" で、ctime() が 返すフォーマットに一致します。 stringformat に従って解釈できなかった場合、 例外 ValueError が送出されます。 解析しようとする文字列が解析後に余分なデータを持っていた場合、 ValueError が送出されます。欠落したデータについて、適切な値を推測できない 場合はデフォルトの値で埋められ、その値は (1900, 1, 1, 0, 0, 0, 0, 1, -1) です。

%Z 指示語へのサポートは tzname に収められている値と daylight が真かどうかで決められます。このため、常に既知の (かつ夏時間でないと考えられている) UTC や GMT を認識する時以外は プラットフォーム固有の動作になります。

struct_time
gmtime()localtime() および strptime() が返す時刻値シーケンスのタイプです。 バージョン 2.2 で 新たに追加 された仕様です。

time( )
時刻を浮動小数点数で返します。単位は UTC におけるエポックからの秒数です。 時刻は常に浮動小数点で返されますが、全てのシステムが 1 秒より高い精度で 時刻を提供するとは限らないので注意してください。この関数が返す値は通常 減少していくことはありませんが、この関数を 2 回呼び出し、呼び出しの間に システムクロックの時刻を巻き戻して設定した場合には、以前の呼び出しよりも 低い値が返ることもあります。

timezone
(DST でない) ローカルタイムゾーンの UTC からの時刻オフセットで、西に 行くほど増加する秒で表した値です (ほとんどの西ヨーロッパでは負になり、 アメリカでは正、イギリスではゼロになります) 。

tzname
二つの文字列からなるタプルです。最初の要素は DST でないローカルの タイムゾーン名です。ふたつめの要素は DST のタイムゾーンです。 DST のタイムゾーンが定義されていない場合。二つ目の文字列を使うべきでは ありません。

tzset( )
ライブラリで使われている時刻変換規則をリセットします。 どのように行われるかは、環境変数 TZ で指定されます。 バージョン 2.3 で 新たに追加 された仕様です。

利用できるシステム: Unix

注意: 多くの場合、環境変数 TZ を変更すると、tzset を 呼ばない限り localtime のような関数の出力に影響を 及ぼすため、値が信頼できなくなってしまいます。

TZ 環境変数には空白文字を含めてはなりません。

環境変数 TZ の標準的な書式は以下です: (分かりやすいように空白を入れています)

std offset [dst [offset] [,start[/time], end[/time]
]]

各値は以下のようになっています:

std と dst
三文字またはそれ以上の英数字で、タイムゾーンの略称を与えます。 この値は time.tzname になります。

offset
オフセットは形式: ± hh[:mm[:ss]] をとります。 この表現は、UTC 時刻にするためにローカルな時間に加算する必要の ある時間値を示します。'-' が先頭につく場合、そのタイムゾーンは 本子午線 (Prime Meridian) より東側にあります; それ以外の場合は 本子午線の西側です。オフセットが dst の後ろに続かない場合、 夏時間は標準時より一時間先行しているものと仮定します。

start[/time],end[/time]
いつ DST に移動し、DST から戻ってくるかを示します。開始および終了 日時の形式は以下のいずれかです:

Jn
ユリウス日 (Julian day) n (1 <= n <= 365) を表します。 うるう日は計算に含められないため、2 月 28 日は常に 59 で、 3 月 1 日は 60 になります。

n
ゼロから始まるユリウス日 (0 <= n <= 365) です。うるう日は 計算に含められるため、2 月 29 日を参照することができます。

Mm.n.d
m 月の第 n 週における d 番目の日 (0 <= d <= 6, 1 <= n <= 5, 1 <= m <= 12) を表します。週 5 は月における最終週の d 番目の日を表し、 第 4 週か第 5 週のどちらかになります。週 1 は日 d が最初に 現れる日を指します。日 0 は日曜日です。

時間はオフセットと同じで、先頭に符号 ('-' や '+') を付けてはいけない ところが違います。時刻が指定されていなければ、デフォルトの値 02:00:00 になります。

>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'02:07:36 05/08/03 EDT'
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'16:08:12 05/08/03 AEST'

多くの Unix システム (*BSD, Linux, Solaris, および Darwin を含む) では、システムの zoneinfo (tzfile(5)) データベース を使ったほうが、タイムゾーンごとの規則を指定する上で便利です。 これを行うには、必要なタイムゾーンデータファイルへのパスを システムの 'zoneinfo' タイムゾーンデータベースからの相対で表した値 を環境変数 TZ に設定します。システムの 'zoneinfo' は 通常/usr/share/zoneinfo にあります。例えば、 'US/Eastern''Australia/Melbourne''Egypt' ないし 'Europe/Amsterdam' と指定します。

>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')

参考:

datetime:モジュール
日付と時刻に対する、 よりオブジェクト指向のインタフェースです。.
locale:モジュール
国際化サービス。ロケールの設定は time モジュールのいくつかの関数が返す値に影響をおよぼすことがあります。.
calendar:モジュール
一般的なカレンダー関連の関数。 timegm() はこのモジュールの gmtime() の逆の操作を行います。.


脚注

... 表現と互換の書式の例を示します。14.1
現在では %Z の利用は推奨されていません。しかし ここで実現したい時間及び分オフセットへの展開を行ってくれる %Z エスケープは全ての ANSI C ライブラリでサポートされているわけではありません。 また、オリジナルの 1982 年に提出された RFC 822 標準は西暦年の表現を 2 桁 と要求しています(%Y でなく%y )。しかし実際には 2000 年になるだいぶ 以前から 4 桁の西暦年表現に移行しています。4 桁の西暦年表現は RFC 2822 に おいて義務付けられ、伴って RFC 822 での取り決めは撤廃されました。
ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。