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

このモジュールでは、時刻に関するさまざまな関数を提供します。ほとんどの 関数が利用可能ですが、全ての関数が全てのプラットフォームで利用可能な わけではありません。 このモジュールで定義されているほとんどの関数は、プラットフォーム上の 同名の 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 に過ぎません。また、Mac では時刻は 秒きっかりのとき以外正確ではありません。

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

- `gmtime()`、`localtime()`、`strptime()` が返す時刻値、 および `asctime()`、`mktime()`、 `strftime()` に与える時刻値はどちらも 9 つの整数からなる 配列です。

  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`に変更され、 それぞれのフィールドに属性名がつけられました。

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

`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 の ベンチマーク Python や 計時アルゴリズムに使われています。

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

`ctime`( | [secs])

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

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

`gmtime`( | [secs])

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

`localtime`( | [secs])

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

`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 は文字列でなくてはなりません。 バージョン2.1 以降で変更された 仕様: t を省略できるようになりました。

  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 に対応する文字列。 |
  `%S` | 秒を表す 10 進数 [00,61]。 | (1)
  `%U` | 年の初めから何週目か (日曜を週の始まりとします)を表す 10 進数 [00,53]。年が明けてから最初の日曜日までの全ての 曜日は 0 週目に属すると見なされます。 |
  `%w` | 曜日を表す 10 進数 [0(日曜日),6]。 |
  `%W` | 年の初めから何週目か (日曜を週の始まりとします)を表す 10 進数 [00,53]。年が明けてから最初の月曜日までの全ての 曜日は 0 週目に属すると見なされます。 |
  `%x` | ロケールにおける適切な日付の表現。 |
  `%X` | ロケールにおける適切な時刻の表現。 |
  `%y` | 上 2 桁なしの西暦年を表す 10 進数 [00,99]。 |
  `%Y` | 上 2 桁付きの西暦年を表す 10 進数。 |
  `%Z` | タイムゾーンの名前 (タイムゾーンがない場合には空文字列)。 |
  `%%` | 文字 "`%`" 自体の表現。 |

  注意:

  (1)
    値の幅は間違いなく `0` to `61` です; これはうるう秒と、 （ごく稀ですが）2 重のうるう秒のためのものです。

  以下に RFC 2822 インターネット電子メール標準で定義されている日付 表現と互換の書式の例を示します。 6.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()` が 返すフォーマットに一致します。 string が format に従って解釈できなかった場合、 例外 `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 and 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')

参考資料:

`locale`モジュール:
  国際化サービス。ロケールの設定は `time` モジュールのいくつかの関数が返す値に影響をおよぼすことがあります。.

`calendar`モジュール:
  一般的なカレンダー関連の関数。 `timegm()` はこのモジュールの `gmtime()` の逆の操作を行います。.

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