15.3. time — 時刻データへのアクセスと変換

このモジュールでは、時刻に関するさまざまな関数を提供します。関連した機能について、 datetime, calendar モジュールも参照してください。

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

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

  • エポック (epoch) は、時刻の計測がはじまった時点のことです。その年の 1 月 1 日の午前 0 時に “エポックからの経過時間” が 0 になるように設定されます。Unixではエポックは 1970 年です。エポックがどうなっているかを知るには、 gmtime(0) の値を見るとよいでしょう。
  • このモジュールの中の関数は、エポック以前あるいは遠い未来の日付や時刻を扱うことができません。将来カットオフ(関数が正しく日付や時刻を扱えなくなる)が起きる時点は、C ライブラリによって決まります。 Unixではカットオフは通常 2038 です。
  • 2000年問題 (Y2K): Python はプラットフォームの C ライブラリに依存しています。C ライブラリは日付および時刻をエポックからの経過秒で表現するので、一般的に 2000 年問題を持ちません。時刻を表現する struct_time (下記を参照してください)を入力として受け取る関数は一般的に 4 桁表記の西暦年を要求します。以前のバージョンとの互換性のために、モジュール変数 accept2dyear がゼロでない整数の場合、 2 桁の西暦年をサポートします。この変数の初期値は環境変数 PYTHONY2K が空文字列のとき 1 に設定されます。空文字列でない文字列が設定されている場合、 0 に設定されます。こうして、 PYTHONY2K を空文字列でない文字列に設定することで、西暦年の入力がすべて 4 桁の西暦年でなければならないようにすることができます。 2桁の西暦年が入力された場合には、POSIX または X/Open 標準に従って変換されます: 69-99 の西暦年は 1969-1999 となり、0–68 の西暦年は 2000–2068 になります。100-1899 は常に不正な値になります。この仕様は Python 1.5.2(a2) から新たに追加された機能であることに注意してください; それ以前のバージョン、すなわち Python 1.5.1 および 1.5.2a1 では、1900 以下の年に対して 1900 を足します。
  • UTC は協定世界時 (Coordinated Universal Time) のことです (以前はグリニッジ標準時 または GMTとして知られていました)。 UTC の頭文字の並びは誤りではなく、英仏の妥協によるものです。
  • DST は夏時間 (Daylight Saving Time) のことで、一年のうち部分的に 1 時間タイムゾーンを修正することです。DST のルールは不可思議で (局所的な法律で定められています)、年ごとに変わることもあります。 C ライブラリはローカルルールを記したテーブルを持っており (柔軟に対応するため、たいていはシステムファイルから読み込まれます)、この点に関しては唯一の真実の知識の源です。

  • 多くの現時刻を返す関数 (real-time functions) の精度は、値や引数を表現するのに使う単位から想像されるよりも低いかも知れません。例えば、ほとんどの Unix システムで、クロックの一刹那 (ticks) の精度は 1 秒の 50 から 100 分の 1 に過ぎません。

  • 反対に、 time() および sleep() は Unix の同等の関数よりましな精度を持っています: 時刻は浮動小数点で表され、 time() は可能なかぎり最も正確な時刻を (Unix の gettimeofday() があればそれを使って) 返します。また sleep() にはゼロでない端数を与えることができます (Unix の select() があれば、それを使って実装しています)。

  • gmtime(), localtime(), strptime() が返す時刻値、および asctime(), mktime(), strftime() に与える時刻値はどちらも 9 つの整数からなるシーケンスです。 gmtime(), localtime(), strptime() の戻り値は属性名でアクセスすることもできます。

    これらのオブジェクトについての解説は struct_time を参照してください。

    バージョン 2.2 で変更: 時刻値の配列はタプルから struct_time に変更され、それぞれのフィールドに属性名がつけられました。

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

time.accept2dyear

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

time.altzone

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

time.asctime([t])

gmtime()localtime() が返す時刻を表現するタプル又は struct_time を、 'Sun Jun 20 23:21:05 1993' といった書式の 24 文字の文字列に変換します。 t が与えられていない場合には、 localtime() が返す現在の時刻が使われます。 asctime() はロケール情報を使いません。

注釈

同名の C の関数と違って、末尾には改行文字はありません。

バージョン 2.1 で変更: tuple を省略できるようになりました。

time.clock()

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

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

time.ctime([secs])

エポックからの経過秒数で表現された時刻を、ローカルの時刻を表現する文字列に変換します。 secs を指定しない、または None を指定した場合、 time() が返す値を現在の時刻として使います。 ctime(secs)asctime(localtime(secs)) と同じです。 ctime() はロケール情報を使いません。

バージョン 2.1 で変更: secs を省略できるようになりました.

バージョン 2.4 で変更: secsNone の場合に現在時刻を使うようになりました.

time.daylight

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

time.gmtime([secs])

エポックからの経過時間で表現された時刻を、UTC における struct_time に変換します。このとき dst フラグは常にゼロとして扱われます。 secs を指定しない、または None を指定した場合、 time() が返す値を現在の時刻として使います。秒の端数は無視されます。 struct_time のレイアウトについては上を参照してください。

バージョン 2.1 で変更: secs を省略できるようになりました.

バージョン 2.4 で変更: secsNone の場合に現在時刻を使うようになりました.

time.localtime([secs])

gmtime() に似ていますが、ローカルタイムに変換します。 secs を指定しない、または None を指定した場合、 time() が返す値を現在の時刻として使います。現在の時刻に DST が適用される場合、 dst フラグは 1 に設定されます。

バージョン 2.1 で変更: secs を省略できるようになりました。

バージョン 2.4 で変更: secsNone の場合に現在時刻を使うようになりました.

time.mktime(t)

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

time.sleep(secs)

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

time.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() の結果の対応する文字列と入れ替えられます:

ディレクティブ

意味

注釈

%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 インターネット電子メール標準で定義されている日付表現と互換の書式の例を示します。 [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 です。

time.strptime(string[, format])

時刻を表現する文字列をフォーマットに従って解釈します。返される値は gmtime()localtime() が返すような struct_time です。

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

例:

>>> import time
>>> time.strptime("30 Nov 00", "%d %b %y")   
time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
                 tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)

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

ドキュメント内で説明されているディレクティブだけがサポートされています。 strftime() はプラットフォームによって実装されているので、説明されていないディレクティブも利用できるかもしれません。しかし、 strptime() はプラットフォーム非依存なので、サポートされているディレクティブ以外は利用できないかもしれません。

class time.struct_time

gmtime(), localtime() および strptime() が返す時刻値シーケンスのタイプです。これは名前付きタプル(named tuple)のインタフェースをもったオブジェクトです。値はインデックスでも属性名でもアクセス可能です。以下の値があります。

インデックス

属性

0 tm_year (例えば 1993)
1 tm_mon [1,12] の間の数
2 tm_mday [1,31] の間の数
3 tm_hour [0,23] の間の数
4 tm_min [0,59] の間の数
5 tm_sec [0,61] の間の数 strftime() の説明にある (1) を読んで下さい
6 tm_wday [0,6] の間の数、月曜が 0 になります
7 tm_yday [1,366] の間の数
8 tm_isdst 0, 1 または -1; 以下を参照してください

バージョン 2.2 で追加.

C の構造体と違って、月の値が 0-11 でなく 1-12 であることに注意してください。西暦年の値は上の 2000年問題 (Y2K) で述べたように扱われます。夏時間フラグを -1 にして mktime() に渡すと、たいていは正確な夏時間の状態を実現します。

struct_time を引数とする関数に正しくない長さの struct_time や要素の型が正しくない struct_time を与えた場合には、 TypeError が送出されます。

time.time()

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

time.timezone

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

time.tzname

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

time.tzset()

ライブラリで使われている時刻変換規則をリセットします。どのように行われるかは、環境変数 TZ で指定されます。

バージョン 2.3 で追加.

利用できるシステム: Unix。

注釈

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

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

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

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

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

stddst
三文字またはそれ以上の英数字で、タイムゾーンの略称を与えます。この値は 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 は日曜日です。

timeoffset とほぼ同じで、先頭に符号 (‘-‘ や ‘+’) を付けてはいけないところだけが違います。時刻が指定されていなければ、デフォルトの値 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')

参考

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

注記

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