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

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

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

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

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

* The *epoch* is the point where the time starts, the return value of
  "time.gmtime(0)". It is January 1, 1970, 00:00:00 (UTC) on all
  platforms.

* *エポック秒* (*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 is Coordinated Universal Time and superseded Greenwich Mean Time
  or GMT as the basis of international timekeeping. The acronym UTC is
  not a mistake but conforms to an earlier, language-agnostic naming
  scheme for time standards such as UT0, UT1, and 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])

   Convert a tuple or "struct_time" representing a time as returned by
   "gmtime()" or "localtime()" to a string of the following form:
   "'Sun Jun 20 23:21:05 1993'". The day field is two characters long
   and is space padded if the day is a single digit, for example:
   "'Wed Jun  9 04:26:40 1993'".

   If *time_tuple* is not provided, the current time as returned by
   "localtime()" is used. Locale information is not used by
   "asctime()".

   注釈:

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

time.pthread_getcpuclockid(thread_id, /)

   Return the *clk_id* of the thread-specific CPU-time clock for the
   specified *thread_id*.

   Use "threading.get_ident()" or the "ident" attribute of
   "threading.Thread" objects to get a suitable value for *thread_id*.

   警告:

     Passing an invalid or expired *thread_id* may result in undefined
     behavior, such as segmentation fault.

   Availability: Unix

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

   Added in version 3.7.

time.clock_getres(clk_id, /)

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

   Availability: Unix.

   Added in version 3.3.

time.clock_gettime(clk_id, /) -> float

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

   Use "clock_gettime_ns()" to avoid the precision loss caused by the
   "float" type.

   Availability: Unix.

   Added in version 3.3.

time.clock_gettime_ns(clk_id, /) -> int

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

   Availability: Unix.

   Added in version 3.7.

time.clock_settime(clk_id, time: float, /)

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

   Use "clock_settime_ns()" to avoid the precision loss caused by the
   "float" type.

   Availability: Unix, not Android, not iOS.

   Added in version 3.3.

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

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

   Availability: Unix, not Android, not iOS.

   Added in version 3.7.

time.ctime(seconds=None, /)

   Convert a time expressed in seconds since the epoch to a string of
   a form: "'Sun Jun 20 23:21:05 1993'" representing local time. The
   day field is two characters long and is space padded if the day is
   a single digit, for example: "'Wed Jun  9 04:26:40 1993'".

   If *seconds* is not provided or "None", the current time as
   returned by "time()" is used. "ctime(seconds)" is equivalent to
   "asctime(localtime(seconds))". Locale information is not used by
   "ctime()".

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" if the clock can be set to jump forward or
     backward in time, "False" otherwise. Does not refer to gradual
     NTP rate adjustments.

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

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

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

   Added in version 3.3.

time.gmtime(seconds=None, /)

   Convert a time expressed in seconds since the epoch to a
   "struct_time" in UTC in which the dst flag is always zero.  If
   *seconds* is not provided or "None", the current time as returned
   by "time()" is used.  Fractions of a second are ignored.  See above
   for a description of the "struct_time" object. See
   "calendar.timegm()" for the inverse of this function.

time.localtime(seconds=None, /)

   Like "gmtime()" but converts to local time. If *seconds* is not
   provided or "None", the current time as returned by "time()" is
   used. The dst flag is set to "1" when DST applies to the given
   time.

   "localtime()" may raise "OverflowError", if the timestamp is
   outside the range of values supported by the platform C
   "localtime()" or "gmtime()" functions, and "OSError" on
   "localtime()" or "gmtime()" failure. It's common for this to be
   restricted to years between 1970 and 2038.

time.mktime(time_tuple, /)

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

time.monotonic() -> float

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

   Clock:

   * On Windows, call "QueryPerformanceCounter()" and
     "QueryPerformanceFrequency()".

   * On macOS, call "mach_absolute_time()" and "mach_timebase_info()".

   * On HP-UX, call "gethrtime()".

   * Call "clock_gettime(CLOCK_HIGHRES)" if available.

   * Otherwise, call "clock_gettime(CLOCK_MONOTONIC)".

   Use "monotonic_ns()" to avoid the precision loss caused by the
   "float" type.

   Added in version 3.3.

   バージョン 3.5 で変更: The function is now always available and the
   clock is now the same for all processes.

   バージョン 3.10 で変更: On macOS, the clock is now the same for all
   processes.

time.monotonic_ns() -> int

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

   Added in version 3.7.

time.perf_counter() -> float

   Return the value (in fractional seconds) of a performance counter,
   i.e. a clock with the highest available resolution to measure a
   short duration.  It does include time elapsed during sleep. The
   clock is the same for all processes. The reference point of the
   returned value is undefined, so that only the difference between
   the results of two calls is valid.

   **CPython 実装の詳細:** On CPython, use the same clock as
   "time.monotonic()" and is a monotonic clock, i.e. a clock that
   cannot go backwards.

   Use "perf_counter_ns()" to avoid the precision loss caused by the
   "float" type.

   Added in version 3.3.

   バージョン 3.10 で変更: On Windows, the clock is now the same for
   all processes.

   バージョン 3.13 で変更: Use the same clock as "time.monotonic()".

time.perf_counter_ns() -> int

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

   Added in version 3.7.

time.process_time() -> float

   現在のプロセスのシステムおよびユーザー CPU 時間の値を (小数秒で) 返
   します。これはスリープ中の経過時間を含みません。これは定義上プロセ
   スワイドです。戻り値の基準点は定義されていないので、二回の呼び出し
   の結果の差だけが有効です。

   Use "process_time_ns()" to avoid the precision loss caused by the
   "float" type.

   Added in version 3.3.

time.process_time_ns() -> int

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

   Added in version 3.7.

time.sleep(seconds, /)

   Suspend execution of the calling thread for the given number of
   seconds. The argument may be a floating-point number to indicate a
   more precise sleep time.

   If the sleep is interrupted by a signal and no exception is raised
   by the signal handler, the sleep is restarted with a recomputed
   timeout.

   The suspension time may be longer than requested by an arbitrary
   amount, because of the scheduling of other activity in the system.

   -[ Windows implementation ]-

   On Windows, if *seconds* is zero, the thread relinquishes the
   remainder of its time slice to any other thread that is ready to
   run. If there are no other threads ready to run, the function
   returns immediately, and the thread continues execution. On Windows
   10 and newer the implementation uses a high-resolution timer which
   provides resolution of 100 nanoseconds. If *seconds* is zero,
   "Sleep(0)" is used.

   -[ Unix implementation ]-

   * Use "clock_nanosleep()" if available (resolution: 1 nanosecond);

   * Or use "nanosleep()" if available (resolution: 1 nanosecond);

   * Or use "select()" (resolution: 1 microsecond).

   注釈:

     To emulate a "no-op", use "pass" instead of "time.sleep(0)".To
     voluntarily relinquish the CPU, specify a real-time scheduling
     policy and use "os.sched_yield()" instead.

   Raises an auditing event "time.sleep" with argument "seconds".

   バージョン 3.5 で変更: The function now sleeps at least *seconds*
   even if the sleep is interrupted by a signal, except if the signal
   handler raises an exception (see **PEP 475** for the rationale).

   バージョン 3.11 で変更: On Unix, the "clock_nanosleep()" and
   "nanosleep()" functions are now used if available. On Windows, a
   waitable timer is now used.

   バージョン 3.13 で変更: Raises an auditing event.

time.strftime(format[, time_tuple])

   Convert a tuple or "struct_time" representing a time as returned by
   "gmtime()" or "localtime()" to a string as specified by the
   *format* argument.  If *time_tuple* is not provided, the current
   time as returned by "localtime()" is used.  *format* must be a
   string.  "ValueError" is raised if any field in *time_tuple* is
   outside of the allowed range.

   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"        | Day of the week (Monday is 1; Sunday is 7) as a  |         |
   |             | decimal number [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 year (similar to "%Y" but follows the   |         |
   |             | rules for the ISO 8601 calendar year). The year  |         |
   |             | starts with the week that contains the first     |         |
   |             | Thursday of the calendar year.                   |         |
   +-------------+--------------------------------------------------+---------+
   | "%V"        | ISO 8601 week number (as a decimal number        |         |
   |             | [01,53]). The first week of the year is the one  |         |
   |             | that contains the first Thursday of the year.    |         |
   |             | Weeks start on Monday.                           |         |
   +-------------+--------------------------------------------------+---------+
   | "%%"        | 文字 "'%'" を表します。                          |         |
   +-------------+--------------------------------------------------+---------+

   注釈:

   1. The "%f" format directive only applies to "strptime()", not to
      "strftime()". However, see also "datetime.datetime.strptime()"
      and "datetime.datetime.strftime()" where the "%f" format
      directive applies to microseconds.

   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                           | range [0, 6]; Monday is 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" が
   送出されます。

time.time() -> float

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

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

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

   Clock:

   * On Windows, call "GetSystemTimePreciseAsFileTime()".

   * Call "clock_gettime(CLOCK_REALTIME)" if available.

   * Otherwise, call "gettimeofday()".

   Use "time_ns()" to avoid the precision loss caused by the "float"
   type.

バージョン 3.13 で変更: On Windows, calls
"GetSystemTimePreciseAsFileTime()" instead of
"GetSystemTimeAsFileTime()".

time.time_ns() -> int

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

   Added in version 3.7.

time.thread_time() -> float

   現在のスレッドのシステムおよびユーザー CPU 時間の値を (小数秒で) 返
   します。これはスリープ中の経過時間を含みません。これは定義上スレッ
   ド固有です。戻り値の基準点は定義されていないので、同一スレッドにお
   ける二回の呼び出しの結果の差だけが有効です。

   Use "thread_time_ns()" to avoid the precision loss caused by the
   "float" type.

   Availability: Linux, Unix, Windows.

   Unix systems supporting "CLOCK_THREAD_CPUTIME_ID".

   Added in version 3.7.

time.thread_time_ns() -> int

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

   Added in version 3.7.

time.tzset()

   Reset the time conversion rules used by the library routines. The
   environment variable "TZ" specifies how this is done. It will also
   set the variables "tzname" (from the "TZ" environment variable),
   "timezone" (non-DST seconds West of UTC), "altzone" (DST seconds
   west of UTC) and "daylight" (to 0 if this timezone does not have
   any daylight saving time rules, or to nonzero if there is a time,
   past, present or future when daylight saving time applies).

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


Clock ID Constants
==================

These constants are used as parameters for "clock_getres()" and
"clock_gettime()".

time.CLOCK_BOOTTIME

   Identical to "CLOCK_MONOTONIC", except it also includes any time
   that the system is suspended.

   This allows applications to get a suspend-aware monotonic  clock
   without having to deal with the complications of "CLOCK_REALTIME",
   which may have  discontinuities if the time is changed using
   "settimeofday()" or similar.

   Availability: Linux >= 2.6.39.

   Added in version 3.7.

time.CLOCK_HIGHRES

   Solaris OS は任意のハードウェアソースの使用を試み、ナノ秒レベルの分
   解能を提供する "CLOCK_HIGHRES" タイマーを具備しています。
   "CLOCK_HIGHRES" は変更不可で、高分解能のクロックです。

   Availability: Solaris.

   Added in version 3.3.

time.CLOCK_MONOTONIC

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

   Availability: Unix.

   Added in version 3.3.

time.CLOCK_MONOTONIC_RAW

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

   Availability: Linux >= 2.6.28, macOS >= 10.12.

   Added in version 3.3.

time.CLOCK_MONOTONIC_RAW_APPROX

   Similar to "CLOCK_MONOTONIC_RAW", but reads a value cached by the
   system at context switch and hence has less accuracy.

   Availability: macOS >= 10.12.

   Added in version 3.13.

time.CLOCK_PROCESS_CPUTIME_ID

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

   Availability: Unix.

   Added in version 3.3.

time.CLOCK_PROF

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

   Availability: FreeBSD, NetBSD >= 7, OpenBSD.

   Added in version 3.7.

time.CLOCK_TAI

   International Atomic Time

   The system must have a current leap second table in order for this
   to give the correct answer.  PTP or NTP software can maintain a
   leap second table.

   Availability: Linux.

   Added in version 3.9.

time.CLOCK_THREAD_CPUTIME_ID

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

   Availability: Unix.

   Added in version 3.3.

time.CLOCK_UPTIME

   Time whose absolute value is the time the system has been running
   and not suspended, providing accurate uptime measurement, both
   absolute and interval.

   Availability: FreeBSD, OpenBSD >= 5.5.

   Added in version 3.7.

time.CLOCK_UPTIME_RAW

   Clock that increments monotonically, tracking the time since an
   arbitrary point, unaffected by frequency or time adjustments and
   not incremented while the system is asleep.

   Availability: macOS >= 10.12.

   Added in version 3.8.

time.CLOCK_UPTIME_RAW_APPROX

   Like "CLOCK_UPTIME_RAW", but the value is cached by the system at
   context switches and therefore has less accuracy.

   Availability: macOS >= 10.12.

   Added in version 3.13.

The following constant is the only parameter that can be sent to
"clock_settime()".

time.CLOCK_REALTIME

   Real-time clock.  Setting this clock requires appropriate
   privileges. The clock is the same for all processes.

   Availability: Unix.

   Added in version 3.3.


Timezone Constants
==================

time.altzone

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

time.daylight

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

time.timezone

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

time.tzname

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

注釈:

  For the above Timezone constants ("altzone", "daylight", "timezone",
  and "tzname"), the value is determined by the timezone rules in
  effect at module load time or the last time "tzset()" is called and
  may be incorrect for times in the past.  It is recommended to use
  the "tm_gmtoff" and "tm_zone" results from "localtime()" to obtain
  timezone information.

参考:

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

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

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

-[ 脚注 ]-

[1] The use of "%Z" is now deprecated, but the "%z" escape that
    expands to the preferred hour/minute offset is not supported by
    all ANSI C libraries. Also, a strict reading of the original 1982
    **RFC 822** standard calls for a two-digit year ("%y" rather than
    "%Y"), but practice moved to 4-digit years long before the year
    2000.  After that, **RFC 822** became obsolete and the 4-digit
    year has been first recommended by **RFC 1123** and then mandated
    by **RFC 2822**, with **RFC 5322** continuing this requirement.
