このモジュールでは、時刻に関するさまざまな関数を提供します。関連した機能について、 datetime, calendar モジュールも参照してください。
このモジュールは常に利用可能ですが、全ての関数が全てのプラットフォームで利用可能なわけではありません。このモジュールで定義されているほとんどの関数は、プラットフォーム上の同名の C ライブラリ関数を呼び出します。これらの関数に対する意味付けはプラットフォーム間で異なるため、プラットフォーム提供のドキュメントを読んでおくと便利でしょう。
まずいくつかの用語の説明と慣習について整理します。
このモジュールの中の関数は、エポック以前あるいは遠い未来の日付や時刻を扱うことができません。将来カットオフ(関数が正しく日付や時刻を扱えなくなる)が起きる時点は、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() の戻り値は属性名でアクセスすることもできます。
Index |
Attribute |
Values |
---|---|---|
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; 以下を参照してください |
C の構造体と違って、月の値が 0-11 でなく 1-12 であることに注意してください。西暦年の値は上の “2000年問題 (Y2K) ” で述べたように扱われます。夏時間フラグを -1 にして mktime() に渡すと、たいていは正確な夏時間の状態を実現します。
struct_time を引数とする関数に正しくない長さの struct_time や要素の型が正しくない struct_time を与えた場合には、 TypeError が送出されます。
バージョン 2.2 で変更: 時刻値の配列はタプルから struct_time に変更され、それぞれのフィールドに属性名がつけられました。
時間の表現を変換するためには、以下の関数を利用してください。
From |
To |
Use |
---|---|---|
epochからの秒数 |
struct_time in UTC |
|
epochからの秒数 |
struct_time in local time |
|
struct_time in UTC |
epochからの秒数 |
|
struct_time in local time |
epochからの秒数 |
このモジュールでは以下の関数とデータ型を定義します:
2 桁の西暦年を使えるかを指定するブール型の値です。標準では真ですが、環境変数 PYTHONY2K が空文字列でない値に設定されている場合には偽になります。実行時に変更することもできます。
ローカルの夏時間タイムゾーンにおける UTC からの時刻オフセットで、西に行くほど増加する秒で表した値です (ほとんどの西ヨーロッパでは負になり、アメリカでは正、イギリスではゼロになります) 。 daylight がゼロでないときのみ使用してください。
gmtime() や localtime() が返す時刻を表現するタプル又は struct_time を、 'Sun Jun 20 23:21:05 1993' といった書式の 24 文字の文字列に変換します。 t が与えられていない場合には、 localtime() が返す現在の時刻が使われます。 asctime() はロケール情報を使いません。
ノート
同名の C の関数と違って、末尾には改行文字はありません。
バージョン 2.1 で変更: tuple を省略できるようになりました。
Unixでは、現在のプロセッサ時間秒を浮動小数点数で返します。時刻の精度および “プロセッサ時間 (processor time)” の定義そのものは同じ名前の C 関数に依存します。いずれにせよ、この関数は Python のベンチマークや計時アルゴリズムに使われています。
Windows では、最初にこの関数が呼び出されてからの経過時間を wall-clock 秒で返します。この関数は Win32 関数 QueryPerformanceCounter() に基づいていて、その精度は通常 1 マイクロ秒以下です。
エポックからの経過秒数で表現された時刻を、ローカルの時刻を表現する文字列に変換します。 secs を指定しない、または None を指定した場合、 time() が返す値を現在の時刻として使います。 ctime(secs) は asctime(localtime(secs)) と同じです。 ctime() はロケール情報を使いません。
バージョン 2.1 で変更: secs を省略できるようになりました.
バージョン 2.4 で変更: secs が None の場合に現在時刻を使うようになりました.
DST タイムゾーンが定義されている場合ゼロでない値になります。
エポックからの経過時間で表現された時刻を、UTC における struct_time に変換します。このとき dst フラグは常にゼロとして扱われます。 secs を指定しない、または None を指定した場合、 time() が返す値を現在の時刻として使います。秒の端数は無視されます。 struct_time のレイアウトについては上を参照してください。
バージョン 2.1 で変更: secs を省略できるようになりました.
バージョン 2.4 で変更: secs が None の場合に現在時刻を使うようになりました.
gmtime() に似ていますが、ローカルタイムに変換します。 secs を指定しない、または None を指定した場合、 time() が返す値を現在の時刻として使います。現在の時刻に DST が適用される場合、 dst フラグは 1 に設定されます。
バージョン 2.1 で変更: secs を省略できるようになりました。
バージョン 2.4 で変更: secs が None の場合に現在時刻を使うようになりました.
localtime() の逆を行う関数です。引数は struct_time か完全な 9 つの要素全てに値の入ったタプル (dst フラグも必要です; 現在の時刻に DST が適用されるか不明の場合には -1 を使ってください) で、 UTC ではなく ローカルの 時刻を指定します。 time() との互換性のために浮動小数点数の値を返します。入力の値が正しい時刻で表現できない場合、例外 OverflowError または ValueError が送出されます (どちらが送出されるかは Python およびその下にある C ライブラリのどちらにとって無効な値が入力されたかで決まります) 。この関数で生成できる最も昔の時刻値はプラットフォームに依存します。
与えられた秒数の間実行を停止します。より精度の高い実行停止時間を指定するために、引数は浮動小数点にしてもかまいません。何らかのシステムシグナルがキャッチされた場合、それに続いてシグナル処理ルーチンが実行され、 sleep() を停止してしまいます。従って実際の実行停止時間は要求した時間よりも短くなるかもしれません。また、システムが他の処理をスケジューリングするために、実行停止時間が要求した時間よりも多少長い時間になることもあります。
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 | タイムゾーンの名前 (タイムゾーンがない場合には空文字列)。 | |
%% | 文字 '%' 自体の表現。 |
注意:
以下に 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 です。
時刻を表現する文字列をフォーマットに従って解釈します。返される値は gmtime() や localtime() が返すような struct_time です。
format パラメタは strftime() で使うものと同じ指示語を使います; このパラメタの値はデフォルトでは "%a %b %d %H:%M:%S %Y" で、 ctime() が返すフォーマットに一致します。 string が format に従って解釈できなかった場合、例外 ValueError が送出されます。解析しようとする string が解析後に余分なデータを持っていた場合、 ValueError が送出されます。欠落したデータについて、適切な値を推測できない場合はデフォルトの値で埋められ、その値は (1900, 1, 1, 0, 0, 0, 0, 1, -1) です。
例:
>>> import time
>>> time.strptime("30 Nov 00", "%d %b %y") # doctest: +NORMALIZE_WHITESPACE
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() はプラットフォーム非依存なので、サポートされているディレクティブ以外は利用できないかもしれません。
gmtime() 、 localtime() および strptime() が返す時刻値シーケンスのタイプです。
バージョン 2.2 で追加.
時刻を浮動小数点数で返します。単位は UTC におけるエポックからの秒数です。時刻は常に浮動小数点で返されますが、全てのシステムが 1 秒より高い精度で時刻を提供するとは限らないので注意してください。この関数が返す値は通常減少していくことはありませんが、この関数を 2 回呼び出し、呼び出しの間にシステムクロックの時刻を巻き戻して設定した場合には、以前の呼び出しよりも低い値が返ることもあります。
(DST でない) ローカルタイムゾーンの UTC からの時刻オフセットで、西に行くほど増加する秒で表した値です (ほとんどの西ヨーロッパでは負になり、アメリカでは正、イギリスではゼロになります) 。
二つの文字列からなるタプルです。最初の要素は DST でないローカルのタイムゾーン名です。ふたつめの要素は DST のタイムゾーンです。 DST のタイムゾーンが定義されていない場合。二つ目の文字列を使うべきではありません。
ライブラリで使われている時刻変換規則をリセットします。どのように行われるかは、環境変数 TZ で指定されます。
バージョン 2.3 で追加.
利用できるシステム: Unix。
ノート
多くの場合、環境変数 TZ を変更すると、 tzset() を呼ばない限り localtime() のような関数の出力に影響を及ぼすため、値が信頼できなくなってしまいます。
TZ 環境変数には空白文字を含めてはなりません。
環境変数 TZ の標準的な書式は以下です (分かりやすいように空白を入れています):
std offset [dst [offset [,start[/time], end[/time]]]]
各値は以下のようになっています:
いつ DST に移動し、DST から戻ってくるかを示します。開始および終了日時の形式は以下のいずれかです:
time は offset とほぼ同じで、先頭に符号 (‘-‘ や ‘+’) を付けてはいけないところだけが違います。時刻が指定されていなければ、デフォルトの値 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')
参考
Footnotes
[1] | 現在では %Z の利用は推奨されていません。しかしここで実現したい時間及び分オフセットへの展開を行ってくれる %Z エスケープは全ての ANSI C ライブラリでサポートされているわけではありません。また、オリジナルの 1982 年に提出された RFC 822 標準は西暦年の表現を 2 桁と要求しています(%Y でなく%y )。しかし実際には 2000 年になるだいぶ以前から 4 桁の西暦年表現に移行しています。4 桁の西暦年表現は RFC 2822 において義務付けられ、伴って RFC 822 での取り決めは撤廃されました。 |