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

---

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

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

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

• エポック (epoch) は時刻の起点のことで、これはプラットフォーム依存です。 Unix では、エポックは (UTC で) 1970 年 1 月 1 日 0 時 0 分 0 秒です。 与えられたプラットフォームでエポックが何なのかを知るには、 time.gmtime(0) の値を見てください。

• エポック秒 (seconds since the epoch) は、エポックからの総経過秒数を示していますが、たいていはうるう秒 (leap seconds) は含まれていません。 全ての POSIX 互換のプラットフォームで、うるう秒はこの総秒数には含まれません。

• このモジュールの中の関数は、エポック以前あるいは遠い未来の日付や時刻を扱うことができません。将来カットオフ（関数が正しく日付や時刻を扱えなくなる）が起きる時点は、C ライブラリによって決まります。32-bit システムではカットオフは通常 2038 年です。

• 2000年問題 (Y2K): Python はプラットフォームの C ライブラリに依存しています。C ライブラリは日付および時刻をエポックからの経過秒で表現するので、一般的に 2000 年問題は存在しません。関数 strptime() は %y 書式コードが与えられた時に 2 桁の年表記を解析できます。2 桁の年を解析する場合、それらは POSIX および ISO C 標準に従って変換されます: 69-99 の西暦年は 1969-1999 となり、0–68 の西暦年は 2000–2068 になります。

• UTC は協定世界時 (Coordinated Universal Time) のことです (以前はグリニッジ標準時または GMT として知られていました)。UTC の頭文字の並びは誤りではなく、英仏の妥協によるものです。

• DST は夏時間 (Daylight Saving Time) のことで、一年のうちの一定期間に 1 時間タイムゾーンを修正することです。DST のルールは不可思議で (地域ごとに法律で定められています)、年ごとに変わることもあります。C ライブラリはローカルルールを記したテーブルを持っており (柔軟に対応するため、たいていはシステムファイルから読み込まれます)、この点に関しては唯一の真実の知識の源です。

• 多くの現時刻を返す関数 (real-time functions) の精度は、値や引数を表現するために使う単位から想像されるよりも低いかも知れません。例えば、ほとんどの Unix システムにおいて、クロックの 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 を参照してください。

  バージョン 3.3 で変更: struct_time オブジェクトは、プラットフォームが、対応する struct tm メンバーをサポートしている場合、tm_gmtoff および tm_zone 属性が拡張されるようになりました。

• 時間の表現を変換するには、以下の関数を利用してください:

  対象	変換先	関数
  エポックからの秒数	UTC の struct_time	gmtime()
  エポックからの秒数	ローカル時間の struct_time	localtime()
  UTC の struct_time	エポックからの秒数	calendar.timegm()
  ローカル時間の struct_time	エポックからの秒数	mktime()

The module defines the following functions and data items:

time.altzone

The offset of the local DST timezone, in seconds west of UTC, if one is defined. This is negative if the local DST timezone is east of UTC (as in Western Europe, including the UK). Only use this if daylight is nonzero.

time.asctime([t])

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

注釈

同名の C の関数と違って、asctime() は末尾に改行文字を加えません。

time.clock()

Unix では、現在のプロセッサー時間秒を浮動小数点数で返します。時刻の精度および "プロセッサー時間" の定義そのものは同じ名前の C 関数に依存します。

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

バージョン 3.3 で非推奨: この関数の挙動はプラットフォームに依存します: 必要に応じて挙動が明確に定義されている perf_counter() または process_time() を使用してください。

time.clock_getres(clk_id)

Return the resolution (precision) of the specified clock clk_id.

利用できる環境 : Unix 。

バージョン 3.3 で追加.

time.clock_gettime(clk_id)

Return the time of the specified clock clk_id.

利用できる環境 : Unix 。

バージョン 3.3 で追加.

time.clock_settime(clk_id, time)

Set the time of the specified clock clk_id.

利用できる環境 : Unix 。

バージョン 3.3 で追加.

time.CLOCK_HIGHRES

The Solaris OS has a CLOCK_HIGHRES timer that attempts to use an optimal hardware source, and may give close to nanosecond resolution. CLOCK_HIGHRES is the nonadjustable, high-resolution clock.

利用できる環境: Solaris

バージョン 3.3 で追加.

time.CLOCK_MONOTONIC

設定不可で、モノトニック時刻 (不特定のエポックからの単調増加な時刻) を表します。

利用できる環境 : Unix 。

バージョン 3.3 で追加.

time.CLOCK_MONOTONIC_RAW

CLOCK_MONOTONIC と似ていますが、NTP の影響を受けていない、ハードウェアベースの時刻へのアクセスを提供します。

利用できる環境: Linux 2.6.28 以降

バージョン 3.3 で追加.

time.CLOCK_PROCESS_CPUTIME_ID

CPU による高分解能のプロセスごとのタイマーです。

利用できる環境 : Unix 。

バージョン 3.3 で追加.

time.CLOCK_REALTIME

システム全体のリアルタイムクロックです。このクロックを設定するには適切な権限が必要です。

利用できる環境 : Unix 。

バージョン 3.3 で追加.

time.CLOCK_THREAD_CPUTIME_ID

スレッド固有の CPU タイムクロックです。

利用できる環境 : Unix 。

バージョン 3.3 で追加.

time.ctime([secs])

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

time.daylight

Nonzero if a DST timezone is defined.

time.get_clock_info(name)

指定されたクロックの情報を名前空間オブジェクトとして取得します。サポートされているクロック名およびそれらの値を取得する関数は以下の通りです:

• 'clock': time.clock()
• 'monotonic': time.monotonic()
• 'perf_counter': time.perf_counter()
• 'process_time': time.process_time()
• 'time': time.time()

結果は以下の属性をもちます:

• adjustable: 自動 (NTP デーモンによるなど) またはシステム管理者による手動で変更できる場合は True、それ以外の場合は False になります。
• implementation: The name of the underlying C function used to get the clock value
• monotonic: クロック値が後戻りすることがない場合 True が、そうでない場合は False になります。
• resolution: クロックの分解能を秒 (float) で表します。

バージョン 3.3 で追加.

time.gmtime([secs])

エポックからの経過時間で表現された時刻を、UTC で struct_time に変換します。このとき dst フラグは常にゼロとして扱われます。secs を指定しないか None を指定した場合、time() が返す値を現在の時刻として使用します。秒の端数は無視されます。struct_time オブジェクトについては前述の説明を参照してください。calendar.timegm() はこの関数と逆の変換を行います。

time.localtime([secs])

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

time.mktime(t)

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

time.monotonic()

モノトニッククロックの値 (小数点以下がミリ秒) を返します。戻り値の基準点は定義されていませんが、このクロックは値が後戻りすることはなく、システムクロックの更新の影響も受けません。すなわち、モノトニック時間の重要な点はその値ではなく、値が厳密に増加していくことが保証されている点です。このため、正しい利用法は、呼び出した 2 点間の時間差を計測することです。

Vista より古いバージョンの Windows では、monotonic() は GetTickCount() の整数オーバーフロー (32 bits, 連続稼働で 49.7 日後) を検出します。これは内部エポック (参照時刻) を、オーバーフローを検出する 2³² 毎に増加させます。エポックは各プロセスのローカル内に保存されるため、monotonic() の値は、49 日以上動作させている 2 つの Python プロセス間では異なる場合があります。これより新しいバージョンの Windows およびその他のオペレーティングシステムでは、monotonic() はシステム全体で一意です。

バージョン 3.3 で追加.

バージョン 3.5 で変更: 常に利用出来るようになりました。

time.perf_counter()

パフォーマンスカウンターの値 (小数点以下がミリ秒) を返します。クロックは短期間の計測が行えるよう、可能な限り高い分解能をもちます。これにはスリープ中の経過時間も含まれ、システム全体で一意です。

バージョン 3.3 で追加.

time.process_time()

現在のプロセスのシステムおよびユーザー CPU 時間の合計値 (小数点以下はミリ秒) を返します。プロセスごとに定義され、スリープ中の経過時間は含まれません。戻り値の参照点は定義されていないため、正しい利用法は、呼び出した 2 点間の時間差を計測することです。

バージョン 3.3 で追加.

time.sleep(secs)

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

バージョン 3.5 で変更: スリープがシグナルに中断されてもシグナルハンドラが例外を送出しない限り、少なくとも secs だけスリープするようになりました (論拠については PEP 475 を参照してください)。

time.strftime(format[, t])

gmtime() や localtime() が返す時刻値タプルまたは struct_time を、format で指定した文字列形式に変換します。t が与えられていない場合、localtime() が返す値を現在の時刻として使用します。format は文字列でなくてはなりません。t のいずれかのフィールドが許容範囲外の数値であった場合、ValueError を送出します。

0 は時刻タプル内のいずれの位置の引数にも使用できます; それが一般に不正な値であれば、正しい値に強制的に置き換えられます。

format 文字列には以下のディレクティブ (指示語) を埋め込むことができます。これらはフィールド長や精度のオプションを付けずに表され、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	西暦 ( 4桁) の 10 進表記を表します。
%z	タイムゾーンと UTC/GMT との時差を表す正または負の時間を +HHMM、-HHMM で表します。H は時間の、M は分の 10 進表記になります [-23:59, +23:59]。
%Z	タイムゾーンの名前を表します (タイムゾーンがない場合には空文字列)。
%%	文字 '%' を表します。

注釈:

1. strptime() 関数で使う場合、%p ディレクティブが出力結果の時刻フィールドに影響を及ぼすのは、時刻を解釈するために %I を使ったときのみです。
2. 値の幅は実際に 0 から 61 です; 60 は うるう秒<leap seconds> を表し、 61 は歴史的理由によりサポートされています。
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 で意味のある値はここで列挙したものだけです。あなたのプラットフォームでサポートされている書式コードの全一覧については、strftime(3) のドキュメントを参照してください。

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

time.strptime(string[, format])

時刻を表現する文字列を書式に従って解釈します。返される値は 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) です。string も format も文字列でなければなりません。

例えば:

>>> 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() はプラットフォーム非依存なので、ドキュメント内でサポートされているとされているディレクティブ以外は利用できません。

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() の説明にある (2) を読んで下さい
6	tm_wday	[0,6] の間の数、月曜が 0 になります
7	tm_yday	[1,366] の間の数
8	tm_isdst	0, 1 または -1; 以下を参照してください
N/A	tm_zone	タイムゾーンの短縮名
N/A	tm_gmtoff	UTC から東方向へのオフセット (秒)

C の構造体とは異なり、月の値は [0, 11] ではなく [1, 12] であることに注意してください。

mktime() の呼び出し時に、tm_isdst は夏時間が有効な場合は 1、そうでない場合は 0 に設定されることがあります。 値が -1 の場合は夏時間について不明なことを表していて、普通 tm_isdst は正しい状態に設定されます。

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

バージョン 3.3 で変更: tm_gmtoff and tm_zone attributes are available on platforms with C library supporting the corresponding fields in struct tm.

time.time()

エポック からの秒数を浮動小数点数で返します。 エポックの具体的な日付とうるう秒 (leap seconds) の扱いはプラットフォーム依存です。 Windows とほとんどの Unix システムでは、エポックは (UTC で) 1970 年 1 月 1 日 0 時 0 分 0 秒で、うるう秒はエポック秒の時間の勘定には入りません。 これは一般に Unix 時間 と呼ばれています。 与えられたプラットフォームでエポックが何なのかを知るには、 time.gmtime(0) の値を見てください。

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

time() が返す数値は、 gmtime() 関数に渡されて UTC の、あるいは localtime() 関数に渡されて現地時間の、より一般的な時間のフォーマット (つまり、年、月、日、時間など) に変換されているかもしれません。 どちらの場合でも struct_time オブジェクトが返され、このオブジェクトの属性としてカレンダー日付の構成要素へアクセスできます。

time.timezone

The offset of the local (non-DST) timezone, in seconds west of UTC (negative in most of Western Europe, positive in the US, zero in the UK).

time.tzname

A tuple of two strings: the first is the name of the local non-DST timezone, the second is the name of the local DST timezone. If no DST timezone is defined, the second string should not be used.

time.tzset()

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

利用できる環境 : 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

The d'th day (0 <= d <= 6) or week n of month m of the year (1 <= n <= 5, 1 <= m <= 12, where week 5 means "the last d day in month m" which may occur in either the fourth or the fifth week). Week 1 is the first week in which the d'th day occurs. Day zero is Sunday.

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')

参考

datetime モジュール

日付と時刻に対する、よりオブジェクト指向のインタフェースです。

locale モジュール

国際化サービスです。ロケールの設定は strftime() および strptime() の多くの書式指定子の解釈に影響を及ぼします。

calendar モジュール

一般的なカレンダーに関する関数群です。timegm() はこのモジュールの gmtime() の逆を行う関数です。

脚注

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