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

======================================================================

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

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

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

* 時刻の起点である *エポック* は、"time.gmtime(0)" の戻り値で表されま
  す。 すべてのプラットフォームで 1970 年 1 月 1 日 00:00:00 (UTC) で
  す。

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

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

* 関数 "strptime()" は "%y" 書式コードが与えられた時に 2 桁の年表記を
  解析できます。2 桁の年を解析する場合、それらは POSIX および ISO C 標
  準に従って変換されます: 69-99 の西暦年は 1969-1999 となり、0–68 の西
  暦年は 2000–2068 になります。

* UTC は Coordinated Universal Time (協定世界時) のことで、国際的な時
  刻の基準として Greenwich Mean Time (グリニッジ標準時、GMT) に取って
  代わりました。 UTC という略称は誤りではなく、UT0、UT1、UT2 など、以
  前からある言語に依存しない時刻標準の命名方式に従っています。

* 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" 属性が拡張されるようになりました。

  バージョン 3.6 で変更: "struct_time" の属性 "tm_gmtoff" および
  "tm_zone" が全てのプラットフォームで利用できるようになりました。

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

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


関数
====

time.asctime([time_tuple])

   時刻を表すタプル、または "gmtime()" や "localtime()" が返す
   "struct_time" を、"'Sun Jun 20 23:21:05 1993'" という形式の文字列に
   変換します。 日のフィールドは 2 文字で、1 桁の日には "'Wed Jun  9
   04:26:40 1993'" のように空白が補われます。

   *time_tuple* を指定しない場合は、"localtime()" が返す現在時刻を使い
   ます。 "asctime()" はロケール情報を使いません。

   注釈:

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

time.pthread_getcpuclockid(thread_id, /)

   指定された *thread_id* のスレッド固有の CPU 時間クロックの *clk_id*
   を返します。

   *thread_id* に適した値を取得するには、"threading.get_ident()" また
   は "threading.Thread" オブジェクトの "ident" 属性を使ってください。

   警告:

     無効な *thread_id* や有効期限が切れた *thread_id* を渡すと、セグ
     メンテーション違反などの未定義の動作が起こる可能性があります。

   利用可能な環境: Unix

   更なる情報については *pthread_getcpuclockid(3)* の man を参照してく
   ださい。

   Added in version 3.7.

time.clock_getres(clk_id, /)

   指定された *clk_id* クロックの分解能(精度)を返します。 *clk_id* と
   して受け付けられる値の一覧は クロック ID 定数 を参照してください。

   利用可能な環境: Unix.

   Added in version 3.3.

time.clock_gettime(clk_id, /) -> float

   指定された *clk_id* クロックの時刻を返します。 *clk_id* として受け
   付けられる値の一覧は クロック ID 定数 を参照してください。

   "float" 型による精度の損失を避けるには "clock_gettime_ns()" を使っ
   てください。

   利用可能な環境: Unix.

   Added in version 3.3.

time.clock_gettime_ns(clk_id, /) -> int

   "clock_gettime()" に似ていますが、ナノ秒単位の時刻を返します。

   利用可能な環境: Unix.

   Added in version 3.7.

time.clock_settime(clk_id, time, /)

   指定された *clk_id* クロックの時刻を設定します。 現在、
   "CLOCK_REALTIME" は *clk_id* が受け付ける唯一の値です。

   "float" 型による精度の損失を避けるには "clock_settime_ns()" を使っ
   てください。

   利用可能な環境: Unix, not Android, not iOS.

   Added in version 3.3.

   バージョン 3.15 で変更: *time* として、整数や浮動小数点数だけでなく
   任意の実数を受け付けます。

time.clock_settime_ns(clk_id, time: int, /)

   "clock_settime()" に似ていますが、ナノ秒単位の時刻を設定します。

   利用可能な環境: Unix, not Android, not iOS.

   Added in version 3.7.

time.ctime(seconds=None, /)

   epoch からの秒数で表された時刻を、ローカル時間を表す "'Sun Jun 20
   23:21:05 1993'" という形式の文字列に変換します。 日のフィールドは 2
   文字で、1 桁の日には "'Wed Jun  9 04:26:40 1993'" のように空白が補
   われます。

   *seconds* を指定しない場合や "None" の場合は、"time()" が返す現在時
   刻を使います。 "ctime(seconds)" は "asctime(localtime(seconds))" と
   等価です。 "ctime()" はロケール情報を使いません。

   バージョン 3.15 で変更: 整数や浮動小数点数だけでなく任意の実数を受
   け付けます。

time.get_clock_info(name, /)

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

   * "'monotonic'": "time.monotonic()"

   * "'perf_counter'": "time.perf_counter()"

   * "'process_time'": "time.process_time()"

   * "'thread_time'": "time.thread_time()"

   * "'time'": "time.time()"

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

   * *adjustable*: クロックの時刻を前後に飛ばして設定できる場合は
     "True"、そうでなければ "False" です。 NTP による緩やかな進み方の
     調整は指していません。

   * *implementation*: クロック値を取得するために内部で使用している C
     関数の名前です。 使える値については クロック ID 定数 を参照してく
     ださい。

   * *monotonic*: クロック値が後戻りすることがない場合 "True" が、そう
     でない場合は "False" になります。

   * *resolution*: クロックの分解能を秒 ("float") で表します。

   Added in version 3.3.

time.gmtime(seconds=None, /)

   epoch からの秒数で表された時刻を、UTC の "struct_time" に変換します
   。 dst フラグは常にゼロになります。 *seconds* を指定しない場合や
   "None" の場合は、"time()" が返す現在時刻を使います。 1 秒未満の端数
   は無視します。 "struct_time" オブジェクトの説明は上記を参照してくだ
   さい。 この関数の逆変換については "calendar.timegm()" を参照してく
   ださい。

   バージョン 3.15 で変更: 整数や浮動小数点数だけでなく任意の実数を受
   け付けます。

time.localtime(seconds=None, /)

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

   タイムスタンプがプラットフォームの C 関数 "localtime()" または
   "gmtime()" のサポート範囲外の場合、"localtime()" は "OverflowError"
   を送出することがあります。 また、"localtime()" または "gmtime()" が
   失敗した場合は "OSError" を送出することがあります。 この範囲は通常
   、1970 年から 2038 年までに制限されています。

   バージョン 3.15 で変更: 整数や浮動小数点数だけでなく任意の実数を受
   け付けます。

time.mktime(time_tuple, /)

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

time.monotonic() -> float

   モノトニッククロック、すなわち後戻りしないクロックの値を (小数秒で)
   返します。このクロックはシステムクロックの更新の影響を受けません。
   戻り値の基準点は定義されていないので、二回の呼び出しの結果の差だけ
   が有効です。

   使用するクロック:

   * Windows では "QueryPerformanceCounter()" と
     "QueryPerformanceFrequency()" を呼び出します。

   * macOS では "mach_absolute_time()" と "mach_timebase_info()" を呼
     び出します。

   * HP-UX では "gethrtime()" を呼び出します。

   * 利用可能なら "clock_gettime(CLOCK_HIGHRES)" を呼び出します。

   * それ以外の場合は "clock_gettime(CLOCK_MONOTONIC)" を呼び出します
     。

   "float" 型による精度の損失を避けるには "monotonic_ns()" を使ってく
   ださい。

   Added in version 3.3.

   バージョン 3.5 で変更: この関数が常に利用できるようになり、すべての
   プロセスで同じクロックを使うようになりました。

   バージョン 3.10 で変更: macOS で、すべてのプロセスが同じクロックを
   使うようになりました。

time.monotonic_ns() -> int

   "monotonic()" に似ていますが、ナノ秒単位の時刻を返します。

   Added in version 3.7.

time.perf_counter() -> float

   パフォーマンスカウンター、すなわち短い時間を測定するための、利用可
   能な中で最も分解能が高いクロックの値を、秒単位の小数で返します。 ス
   リープ中の経過時間も含みます。 すべてのプロセスで同じクロックを使い
   ます。 戻り値の基準点は未定義なので、2 回の呼び出し結果の差だけが有
   効です。

   CPython では "time.monotonic()" と同じクロックを使い、後戻りしない
   単調クロックになっています。

   "float" 型による精度の損失を避けるには "perf_counter_ns()" を使って
   ください。

   Added in version 3.3.

   バージョン 3.10 で変更: Windows で、すべてのプロセスが同じクロック
   を使うようになりました。

   バージョン 3.13 で変更: "time.monotonic()" と同じクロックを使うよう
   になりました。

time.perf_counter_ns() -> int

   "perf_counter()" に似ていますが、ナノ秒単位の時刻を返します。

   Added in version 3.7.

time.process_time() -> float

   現在のプロセスのシステム CPU 時間とユーザー CPU 時間の合計を、秒単
   位の小数で返します。 スリープ中の経過時間は含みません。 これは定義
   上、プロセス全体の値です。 戻り値の基準点は未定義なので、2 回の呼び
   出し結果の差だけが有効です。

   "float" 型による精度の損失を避けるには "process_time_ns()" を使って
   ください。

   Added in version 3.3.

time.process_time_ns() -> int

   "process_time()" に似ていますが、ナノ秒単位の時刻を返します。

   Added in version 3.7.

time.sleep(seconds, /)

   呼び出したスレッドの実行を、指定された秒数だけ停止します。 より細か
   い停止時間を指定するために、引数には整数以外の値も使えます。

   シグナルによりスリープが中断され、シグナルハンドラーが例外を送出し
   なかった場合は、タイムアウトを再計算してスリープを再開します。

   システム内の他の処理のスケジューリングによっては、停止時間が指定時
   間より長くなることがあり、その超過時間に上限はありません。

   -[ Windows での実装 ]-

   Windows では *seconds* がゼロの場合、スレッドはタイムスライスの残り
   を、実行可能な他のスレッドに譲ります。 実行可能な他のスレッドがなけ
   れば、関数は直ちに戻り、スレッドは実行を続けます。 Windows 10 以降
   の実装では、100 ナノ秒の分解能を持つ 高分解能タイマー を使います。
   *seconds* がゼロの場合は "Sleep(0)" を使います。

   -[ Unix での実装 ]-

   * 利用可能なら "clock_nanosleep()" を使います (分解能: 1 ナノ秒)。

   * そうでなければ、利用可能なら "nanosleep()" を使います (分解能: 1
     ナノ秒)。

   * それ以外の場合は "select()" を使います (分解能: 1 マイクロ秒)。

   注釈:

     何もしない操作を行うには、"time.sleep(0)" ではなく "pass" を使っ
     てください。自発的に CPU を譲るには、リアルタイムの スケジューリ
     ングポリシー を指定し、代わりに "os.sched_yield()" を使ってくださ
     い。

   引数 "seconds" を指定して 監査イベント "time.sleep" を送出します。

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

   バージョン 3.11 で変更: Unix では、利用可能なら "clock_nanosleep()"
   関数と "nanosleep()" 関数を使うようになりました。 Windows では待機
   可能タイマーを使うようになりました。

   バージョン 3.13 で変更: 監査イベントを送出するようになりました。

   バージョン 3.15 で変更: 整数や浮動小数点数だけでなく任意の実数を受
   け付けます。

time.strftime(format[, time_tuple])

   時刻を表すタプル、または "gmtime()" や "localtime()" が返す
   "struct_time" を、*format* 引数で指定された形式の文字列に変換します
   。 *time_tuple* を指定しない場合は、"localtime()" が返す現在時刻を
   使います。 *format* は文字列でなければなりません。 *time_tuple* の
   いずれかのフィールドが許容範囲外の場合は "ValueError" を送出します
   。

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

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

   +-------------+--------------------------------------------------+---------+
   | ディレクテ  | 意味                                             | 注釈    |
   | ィブ        |                                                  |         |
   |=============|==================================================|=========|
   | "%a"        | ロケールの短縮された曜日名になります。           |         |
   +-------------+--------------------------------------------------+---------+
   | "%A"        | ロケールの曜日名になります。                     |         |
   +-------------+--------------------------------------------------+---------+
   | "%b"        | ロケールの短縮された月名になります。             |         |
   +-------------+--------------------------------------------------+---------+
   | "%B"        | ロケールの月名になります。                       |         |
   +-------------+--------------------------------------------------+---------+
   | "%c"        | ロケールの日時を適切な形式で表します。           |         |
   +-------------+--------------------------------------------------+---------+
   | "%d"        | 月中の日にちの 10 進表記になります [01,31]。     |         |
   +-------------+--------------------------------------------------+---------+
   | "%f"        | Microseconds as a decimal number                 | (1)     |
   |             | [000000,999999].                                 |         |
   +-------------+--------------------------------------------------+---------+
   | "%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 と等価な文字列になりま | (2)     |
   |             | す。                                             |         |
   +-------------+--------------------------------------------------+---------+
   | "%S"        | 秒の 10 進表記になります [00,61]。               | (3)     |
   +-------------+--------------------------------------------------+---------+
   | "%U"        | 年の初めから何週目か (日曜を週の始まりとします)  | (4)     |
   |             | を表す 10 進数にな ります [00,53]。 年が明けてか |         |
   |             | ら最初の日曜日の前日までのすべての曜日 は 0 週目 |         |
   |             | に属すると見なされます。                         |         |
   +-------------+--------------------------------------------------+---------+
   | "%u"        | 曜日の 10 進表記です (月曜日が 1、日曜日が 7)    |         |
   |             | [1, 7]。                                         |         |
   +-------------+--------------------------------------------------+---------+
   | "%w"        | 曜日の 10 進表記になります [0 (日曜日),6]。      |         |
   +-------------+--------------------------------------------------+---------+
   | "%W"        | 年の初めから何週目か (月曜を週の始まりとします)  | (4)     |
   |             | を表す 10 進数にな ります [00,53]。 年が明けてか |         |
   |             | ら最初の月曜日の前日までの全ての曜日は 0 週目に  |         |
   |             | 属すると見なされます。                           |         |
   +-------------+--------------------------------------------------+---------+
   | "%x"        | ロケールの日付を適切な形式で表します。           |         |
   +-------------+--------------------------------------------------+---------+
   | "%X"        | ロケールの時間を適切な形式で表します。           |         |
   +-------------+--------------------------------------------------+---------+
   | "%y"        | 西暦の下 2 桁の 10 進表記になります [00,99]。    |         |
   +-------------+--------------------------------------------------+---------+
   | "%Y"        | 西暦 ( 4桁) の 10 進表記を表します。             |         |
   +-------------+--------------------------------------------------+---------+
   | "%z"        | タイムゾーンと UTC/GMT との時差を表す正または負  |         |
   |             | の時間を +HHMM、 -HHMM で表します。H は時間の、M |         |
   |             | は分の 10 進表記になります [-23:59, +23:59]。    |         |
   |             | [1]                                              |         |
   +-------------+--------------------------------------------------+---------+
   | "%Z"        | タイムゾーンの名前を表します (タイムゾーンがない |         |
   |             | 場合には空文字列)。 非推奨です。 [1]             |         |
   +-------------+--------------------------------------------------+---------+
   | "%G"        | ISO 8601 の年です ("%Y" と似ていますが、ISO 8601 |         |
   |             | の暦年の規則に従い ます)。 年の最初の木曜日を含  |         |
   |             | む週から、その年が始まります。                   |         |
   +-------------+--------------------------------------------------+---------+
   | "%V"        | ISO 8601 の週番号です (10 進表記 [01,53])。 年の |         |
   |             | 最初の木曜日を含む 週が、その年の第 1 週です。   |         |
   |             | 週は月曜日から始まります。                       |         |
   +-------------+--------------------------------------------------+---------+
   | "%%"        | 文字 "'%'" を表します。                          |         |
   +-------------+--------------------------------------------------+---------+

   注釈:

   1. 書式ディレクティブ "%f" は "strptime()" にだけ適用され、
      "strftime()" には適用されません。 ただし、
      "datetime.datetime.strptime()" と "datetime.datetime.strftime()"
      では、書式ディレクティブ "%f" が マイクロ秒に適用される ので、こ
      ちらも参照してください。

   2. "strptime()" 関数で使う場合、"%p" ディレクティブが出力結果の時刻
      フィールドに影響を及ぼすのは、時刻を解釈するために "%I" を使った
      ときのみです。

   3. 値の幅は実際に "0" から "61" です; "60" は うるう秒<leap
      seconds> を表し、 "61" は歴史的理由によりサポートされています。

   4. "strptime()" 関数で使う場合、"%U" および "%W" を計算に使うのは曜
      日と年を指定したときだけです。

   以下に **RFC 5322** インターネット電子メール標準で定義されている日
   付表現と互換の書式の例を示します。  [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")
   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()" が返す時刻値シーケン
   スの型です。これは *名前付きタプル* のインターフェースをもったオブ
   ジェクトです。値はインデックスでも属性名でもアクセス可能です。以下
   の値があります:

   +-----------------------------------+-----------------------------------+-----------------------------------+
   | インデックス                      | 属性                              | 値                                |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | 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                            | range [0, 61]; see Note (2) in    |
   |                                   |                                   | "strftime()"                      |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | 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 は夏時間かどうかが不明であることを表
   し、通常は正しい状態が補われます。

   "struct_time" を受け取る関数に、長さが正しくないタプルや要素の型が
   正しくないタプルを渡すと、"TypeError" が送出されます。

time.time() -> float

   エポック (epoch) からの秒数を浮動小数点数で返します。 うるう秒
   (leap seconds) の扱いはプラットフォーム依存です。 Windows とほとん
   どの Unix システムでは、うるう秒はエポック (epoch) 秒の時間の勘定に
   は入りません。 これは一般に Unix 時間 と呼ばれています。

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

   "time()" が返す数値は、"gmtime()" に渡すと UTC の、"localtime()" に
   渡すとローカル時間の、より一般的な時刻の形式 (年、月、日、時など)
   に変換できます。 どちらも "struct_time" オブジェクトを返し、日付や
   時刻の各要素を属性として取得できます。

   使用するクロック:

   * Windows では "GetSystemTimePreciseAsFileTime()" を呼び出します。

   * 利用可能なら "clock_gettime(CLOCK_REALTIME)" を呼び出します。

   * それ以外の場合は "gettimeofday()" を呼び出します。

   "float" 型による精度の損失を避けるには "time_ns()" を使ってください
   。

バージョン 3.13 で変更: Windows では "GetSystemTimeAsFileTime()" の代
わりに "GetSystemTimePreciseAsFileTime()" を呼び出すようになりました。

time.time_ns() -> int

   "time()" に似ていますが、時刻を epoch を基点としたナノ秒単位の整数
   で返します。

   Added in version 3.7.

time.thread_time() -> float

   現在のスレッドのシステム CPU 時間とユーザー CPU 時間の合計を、秒単
   位の小数で返します。 スリープ中の経過時間は含みません。 これは定義
   上、スレッド固有の値です。 戻り値の基準点は未定義なので、同一スレッ
   ドでの 2 回の呼び出し結果の差だけが有効です。

   "float" 型による精度の損失を避けるには "thread_time_ns()" を使って
   ください。

   利用可能な環境: Linux, Unix, Windows.

   "CLOCK_THREAD_CPUTIME_ID" をサポートする Unix システム。

   Added in version 3.7.

time.thread_time_ns() -> int

   "thread_time()" に似ていますが、ナノ秒単位の時刻を返します。

   Added in version 3.7.

time.tzset()

   ライブラリの関数が使う時刻変換の規則を再設定します。 再設定の内容は
   環境変数 "TZ" で指定します。 また、"tzname" ("TZ" 環境変数に基づく
   値)、"timezone" (夏時間でない場合の UTC から西向きの秒数)、
   "altzone" (夏時間の場合の UTC から西向きの秒数)、"daylight" (このタ
   イムゾーンに夏時間の規則がなければ 0、過去・現在・未来に夏時間が適
   用される期間があればゼロ以外) も設定します。

   利用可能な環境: 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 から戻ってくるかを示します。開始および終
      了日時の形式は以下のいずれかです:

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

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

      "M*m*.*n*.*d*"
         *m* 月の第 *n* 週の曜日 *d* (0 <= *d* <= 6) を表します (1 <=
         *n* <= 5、1 <= *m* <= 12)。 第 5 週は「*m* 月の最後の曜日 *d*
         」を意味し、第 4 週または第 5 週に当たります。 第 1 週は曜日
         *d* が初めて現れる週です。 曜日 0 は日曜日です。

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


クロック ID 定数
================

これらの定数は "clock_getres()" と "clock_gettime()" の引数として使い
ます。

time.CLOCK_BOOTTIME

   "CLOCK_MONOTONIC" と同じですが、システムがサスペンドしていた時間も
   含みます。

   これにより、アプリケーションはサスペンド時間を考慮した単調クロック
   を利用できます。 "settimeofday()" などで時刻を変更すると不連続にな
   ることがある "CLOCK_REALTIME" の複雑さに対処する必要はありません。

   利用可能な環境: Linux >= 2.6.39.

   Added in version 3.7.

time.CLOCK_HIGHRES

   Solaris OS の "CLOCK_HIGHRES" タイマーは、最適なハードウェアソース
   の使用を試み、ナノ秒に近い分解能を提供することがあります。
   "CLOCK_HIGHRES" は調整不可の高分解能クロックです。

   利用可能な環境: Solaris.

   Added in version 3.3.

time.CLOCK_MONOTONIC

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

   利用可能な環境: Unix.

   Added in version 3.3.

time.CLOCK_MONOTONIC_RAW

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

   利用可能な環境: Linux >= 2.6.28, macOS >= 10.12.

   Added in version 3.3.

time.CLOCK_MONOTONIC_RAW_APPROX

   "CLOCK_MONOTONIC_RAW" と似ていますが、コンテキストスイッチ時にシス
   テムがキャッシュした値を読むため、精度は低くなります。

   利用可能な環境: macOS >= 10.12.

   Added in version 3.13.

time.CLOCK_PROCESS_CPUTIME_ID

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

   利用可能な環境: Unix.

   Added in version 3.3.

time.CLOCK_PROF

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

   利用可能な環境: FreeBSD, NetBSD >= 7, OpenBSD.

   Added in version 3.7.

time.CLOCK_TAI

   国際原子時

   正しい値を得るには、システムに最新のうるう秒テーブルが必要です。
   PTP または NTP ソフトウェアでうるう秒テーブルを維持できます。

   利用可能な環境: Linux.

   Added in version 3.9.

time.CLOCK_THREAD_CPUTIME_ID

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

   利用可能な環境: Unix.

   Added in version 3.3.

time.CLOCK_UPTIME

   システムがサスペンドせずに動作していた時間を絶対値として持つ時刻で
   す。 起動後の稼働時間と、ある区間の稼働時間のどちらも正確に測定でき
   ます。

   利用可能な環境: FreeBSD, OpenBSD >= 5.5.

   Added in version 3.7.

time.CLOCK_UPTIME_RAW

   任意の時点からの経過時間を追跡する、単調増加するクロックです。 周波
   数や時刻の調整の影響を受けず、システムがスリープしている間は増加し
   ません。

   利用可能な環境: macOS >= 10.12.

   Added in version 3.8.

time.CLOCK_UPTIME_RAW_APPROX

   "CLOCK_UPTIME_RAW" と似ていますが、値がコンテキストスイッチ時にシス
   テムによってキャッシュされるため、精度は低くなります。

   利用可能な環境: macOS >= 10.12.

   Added in version 3.13.

次の定数は "clock_settime()" に渡せる唯一のクロック ID です。

time.CLOCK_REALTIME

   実時間クロックです。 このクロックの設定には適切な権限が必要です。
   すべてのプロセスで同じクロックを使います。

   利用可能な環境: Unix.

   Added in version 3.3.


タイムゾーン定数
================

time.altzone

   ローカルの夏時間タイムゾーンが定義されている場合、その UTC から西向
   きのオフセットを秒単位で表します。 英国を含む西ヨーロッパのように夏
   時間タイムゾーンが UTC より東側にある場合、この値は負になります。
   "daylight" がゼロでない場合にのみ使用してください。 以下の注釈を参
   照してください。

time.daylight

   DST タイムゾーンが定義されている場合ゼロでない値になります。以下の
   注釈を参照してください。

time.timezone

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

time.tzname

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

注釈:

  上記のタイムゾーン定数 ("altzone"、"daylight"、"timezone"、"tzname")
  の値は、モジュール読み込み時または最後の "tzset()" 呼び出し時に有効
  なタイムゾーン規則によって決まるため、過去の時刻には正しくない場合が
  あります。 タイムゾーン情報を取得するには、"localtime()" の結果の
  "tm_gmtoff" と "tm_zone" を使うことを推奨します。

参考:

  "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** で必須となり、**RFC 5322** でもこの要件が引
    き継がれています。
