\section{\module{time} --- 時刻データへのアクセスと変換}

\declaremodule{builtin}{time}
\modulesynopsis{時刻データへのアクセスと変換}

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


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

\begin{itemize}

\item
\dfn{エポック}(\dfn{epoch})\index{epoch} は、
時刻の計測がはじまった時点のことです。その年の 1 月 1 日の午前 0 時に
``エポックからの経過時間'' が 0 になるように設定されます。\UNIX では
エポックは 1970 年です。エポックがどうなっているかを知るには、
\code{gmtime(0)} の値を見るとよいでしょう。

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

\item
\strong{2000年問題 (Y2K)}:\index{Year 2000}\index{Y2K}
Python はプラットフォームの C ライブラリに依存して
います。C ライブラリは日付および時刻をエポックからの経過秒で表現する
ので、一般的に 2000 年問題を持ちません。
時刻を表現する\class{struct_time}（下記を参照してください）を入力として受け取る関数
は一般的に 4 桁表記の西暦年を要求します。以前のバージョンとの互換性の
ために、モジュール変数 \code{accept2dyear} がゼロでない整数の場合、
2 桁の西暦年をサポートします。この変数の初期値は環境変数
\envvar{PYTHONY2K} が空文字列のとき \code{1} に設定されます。空文字列
でない文字列が設定されている場合、\code{0} に設定されます。こうして、
\envvar{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 を足します。

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

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

\item
多くの現時刻を返す関数 (real-time functions) の精度は、値や引数を表現
するのに使う単位から想像されるよりも低いかも知れません。
例えば、ほとんどの \UNIX{} システムで、クロックの一刹那 (ticks) の
精度は 1 秒 の 50 から 100 分の 1 に過ぎません。また、Mac では時刻は
秒きっかりのとき以外正確ではありません。

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

\item
\function{gmtime()}、\function{localtime()}、\function{strptime()}
が返す時刻値、 および \function{asctime()}、\function{mktime()}、
\function{strftime()} に与える時刻値はどちらも 9 つの整数からなる
シーケンスです。

\begin{tableiii}{c|l|l}{textrm}{Index}{Attribute}{Values}
  \lineiii{0}{\member{tm_year}}{(例えば 1993)}
  \lineiii{1}{\member{tm_mon}}{[1,12] の間の数}
  \lineiii{2}{\member{tm_mday}}{[1,31] の間の数}
  \lineiii{3}{\member{tm_hour}}{[0,23] の間の数}
  \lineiii{4}{\member{tm_min}}{[0,59] の間の数}
  \lineiii{5}{\member{tm_sec}}{[0,61] の間の数 \function{strftime()} の説明にある \strong{(1)} を読んで下さい}
  \lineiii{6}{\member{tm_wday}}{[0,6] の間の数、月曜が 0 になります}
  \lineiii{7}{\member{tm_yday}}{[1,366] の間の数}
  \lineiii{8}{\member{tm_isdst}}{0, 1 または -1; 以下を参照してください}
\end{tableiii}

C の構造体と違って、月の値が 0-11 でなく 1-12 であることに注意してくだ
さい。西暦年の値は上の ''2000年問題 (Y2K) '' で述べたように扱われます。
夏時間フラグを \code{-1} にして \function{mktime()} に渡すと、たいてい
は正確な夏時間の状態を実現します。

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

\versionchanged[時刻値の配列はタプルから\class{struct_time}に変更され、
それぞれのフィールドに属性名がつけられました。]{2.2}
\end{itemize}

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

\begin{datadesc}{accept2dyear}
2 桁の西暦年を使えるかを指定するブール型の値です。標準では真ですが、
環境変数 \envvar{PYTHONY2K} が空文字列でない値に設定されている場合には
偽になります。実行時に変更することもできます。
\end{datadesc}

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

\begin{funcdesc}{asctime}{\optional{t}}
\function{gmtime()} や \function{localtime()} が返す時刻を表現する
タプル又は \class{struct_time}を、\code{'Sun Jun 20 23:21:05 1993'} 
といった書式の 24 文字
の文字列に変換します。\var{t} が与えられていない場合には、
\function{localtime()} が返す現在の時刻が使われます。
\function{asctime()} はロケール情報を使いません。
\note{同名の C の関数と違って、末尾には改行文字はありません。}
\versionchanged[\var{tuple} を省略できるようになりました。]{2.1}
\end{funcdesc}

\begin{funcdesc}{clock}{}
\UNIX では、現在のプロセッサ時間秒を浮動小数点数で返します。
時刻の精度および ``プロセッサ時間 (processor time)'' \index{CPU time}
\index{processor time} の定義そのものは同じ
名前の C 関数に依存します。いずれにせよ、この関数は Python の
ベンチマーク\index{benchmarking} や
計時アルゴリズムに使われています。

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

\begin{funcdesc}{ctime}{\optional{secs}}
エポックからの経過秒数で表現された時刻を、ローカルの時刻を表現
する文字列に変換します。\var{secs} を指定しない、または
\code{None} を指定した場合、\function{time()} が返す値を現在の時刻
として使います。
\code{ctime(\var{secs})} は \code{asctime(localtime(\var{secs}))}
と同じです。\function{ctime()} はロケール情報を使いません。
\versionchanged[\var{secs} を省略できるようになりました]{2.1}
\versionchanged[\var{secs} が\constant{None} の場合に現在時刻を
  使うようになりました]{2.4}
\end{funcdesc}

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

\begin{funcdesc}{gmtime}{\optional{secs}}
エポックからの経過時間で表現された時刻を、UTC における\class{struct_time}
に変換します。このとき dst フラグは常にゼロとして扱われます。
\var{secs} を指定しない、または\code{None} を指定した場合、
\function{time()} が返す値を現在の時刻として使います。
秒の端数は無視されます。\class{struct_time}
のレイアウトについては上を参照してください。
\versionchanged[\var{secs} を省略できるようになりました]{2.1}
\versionchanged[\var{secs} が\constant{None} の場合に現在時刻を
  使うようになりました]{2.4}
\end{funcdesc}

\begin{funcdesc}{localtime}{\optional{secs}}
\function{gmtime()} に似ていますが、ローカルタイムに変換します。
\var{secs} を指定しない、または\code{None} を指定した場合、
\function{time()} が返す値を現在の時刻として使います。
現在の時刻に DST が適用される場合、 dst フラグは \code{1} に設定
されます。
\versionchanged[\var{secs} を省略できるようになりました。]{2.1}
\versionchanged[\var{secs} が\constant{None} の場合に現在時刻を
  使うようになりました]{2.4}
\end{funcdesc}

\begin{funcdesc}{mktime}{t}
\function{localtime()} の逆を行う関数です。引数は \class{struct_time}か
完全な 9 つの要素
全てに値の入ったタプル (dst フラグも必要です; 現在の時刻に DST が
適用されるか不明の場合には \code{-1} を使ってください) で、
UTC ではなく \emph{ローカルの} 時刻を指定します。
\function{time()} との互換性のために浮動小数点数の値を返します。
入力の値が正しい時刻で表現できない場合、例外\exception{OverflowError}
または \exception{ValueError} が送出されます (どちらが送出されるかは
Python および その下にある C ライブラリのどちらにとって無効な値が
入力されたかで決まります) 。この関数で生成できる最も昔の時刻値は
プラットフォームに依存します。
\end{funcdesc}

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

\begin{funcdesc}{strftime}{format\optional{, t}}
\function{gmtime()} や \function{localtime()} が返す時刻値タプル
又は\class{struct_time}を、
\var{format} で指定した文字列形式に変換します。
\var{t} が与えられていない場合、\function{localtime()} が返す
現在の時刻が使われます。\var{format} は文字列でなくてはなりません。
\var{t} のいずれかのフィールドが許容範囲外の数値であった場合、
\exception{ValueError} を送出します。
\versionchanged[\var{t} を省略できるようになりました。]{2.1}
\versionchanged[\var{t} のフィールド値が許容範囲外の値の場合に
  \exception{ValueError} を送出するようになりました]{2.4}
\versionchanged[0 は時刻値タプルのどこでも使用可能になりました。
もし不正な値の場合には正常な値に修正されます。]{2.5}



\var{format} 文字列には以下の指示語 (directive) を埋め込むことが
できます。これらはフィールド長や精度のオプションを付けずに表され、
\function{strftime()} の結果の対応する文字列と入れ替えられます:

\begin{tableiii}{c|p{24em}|c}{code}{Directive}{Meaning}{Notes}
  \lineiii{\%a}{ロケールにおける省略形の曜日名。}{}
  \lineiii{\%A}{ロケールにおける省略なしの曜日名。}{}
  \lineiii{\%b}{ロケールにおける省略形の月名。}{}
  \lineiii{\%B}{ロケールにおける省略なしの月名。}{}
  \lineiii{\%c}{ロケールにおける適切な日付および時刻表現。}{}
  \lineiii{\%d}{月の始めから何日目かを表す 10 進数 [01,31]。}{}
  \lineiii{\%H}{(24 時間計での) 時を表す 10 進数 [00,23]。}{}
  \lineiii{\%I}{(12 時間計での) 時を表す 10 進数 [01,12]。}{}
  \lineiii{\%j}{年の初めから何日目かを表す 10 進数 [001,366]。}{}
  \lineiii{\%m}{月を表す 10 進数 [01,12]。}{}
  \lineiii{\%M}{分を表す 10 進数 [00,59]。}{}
  \lineiii{\%p}{ロケールにおける AM または PM に対応する文字列。}{(1)}
  \lineiii{\%S}{秒を表す 10 進数 [00,61]。}{(2)}
  \lineiii{\%U}{年の初めから何週目か (日曜を週の始まりとします)を表す
        10 進数 [00,53]。年が明けてから最初の日曜日までの全ての
        曜日は 0 週目に属すると見なされます。}{(3)}
  \lineiii{\%w}{曜日を表す 10 進数 [0(日曜日),6]。}{}
  \lineiii{\%W}{年の初めから何週目か (日曜を週の始まりとします)を表す
        10 進数 [00,53]。年が明けてから最初の月曜日までの全ての
        曜日は 0 週目に属すると見なされます。}{(3)}
  \lineiii{\%x}{ロケールにおける適切な日付の表現。}{}
  \lineiii{\%X}{ロケールにおける適切な時刻の表現。}{}
  \lineiii{\%y}{上 2 桁なしの西暦年を表す 10 進数 [00,99]。}{}
  \lineiii{\%Y}{上 2 桁付きの西暦年を表す 10 進数。}{}
  \lineiii{\%Z}{タイムゾーンの名前 (タイムゾーンがない場合には空文字列)。}{}
  \lineiii{\%\%}{文字 \character{\%} 自体の表現。}{}
\end{tableiii}

\noindent
注意:

\begin{description}
  \item[(1)]
    \function{strptime()} 関数で使う場合、\code{\%p} ディレクティブが
    出力結果の時刻フィールドに影響を及ぼすのは、時刻を解釈するために
    \code{\%I} を使ったときのみです。
  \item[(2)]
    値の幅は間違いなく \code{0} to \code{61} です; これはうるう秒と、
	（ごく稀ですが）2 重のうるう秒のためのものです。
  \item[(3)]
    \function{strptime()} 関数で使う場合、\code{\%U} および \code{\%W}
    を計算に使うのは曜日と年を指定したときだけです。
\end{description}

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

\begin{verbatim}
>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'
\end{verbatim}

いくつかのプラットフォームではさらにいくつかの指示語がサポートされて
いますが、標準 ANSI C で意味のある値はここで列挙したものだけです。

いくつかのプラットフォームでは、フィールドの幅や精度を指定する
オプションが以下のように指示語の先頭の文字 \character{\%} の直後に
付けられるようになっていました; この機能も移植性はありません。
フィールドの幅は通常 2 ですが、\code{\%j} は例外で 3 です。
\end{funcdesc}

\begin{funcdesc}{strptime}{string\optional{, format}}
時刻を表現する文字列をフォーマットに従って解釈します。返される値は
\function{gmtime()} や \function{localtime()} が返すような\class{struct_time}
です。\var{format} パラメタは \function{strftime()} で使うものと
同じ指示語を使います; このパラメタの値はデフォルトでは
\code{"\%a \%b \%d \%H:\%M:\%S \%Y"} で、\function{ctime()} が
返すフォーマットに一致します。 
\var{string} が \var{format} に従って解釈できなかった場合、
例外 \exception{ValueError} が送出されます。
解析しようとする文字列が解析後に余分なデータを持っていた場合、
\exception{ValueError} が送出されます。欠落したデータについて、適切な値を推測できない
場合はデフォルトの値で埋められ、その値は \code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)} です。

\code{\%Z} 指示語へのサポートは \code{tzname} に収められている値と
\code{daylight} が真かどうかで決められます。このため、常に既知の
(かつ夏時間でないと考えられている) UTC や GMT を認識する時以外は
プラットフォーム固有の動作になります。
\end{funcdesc}

\begin{datadesc}{struct_time}
\function{gmtime()}、\function{localtime()} および \function{strptime()}
が返す時刻値シーケンスのタイプです。
\versionadded{2.2}
\end{datadesc}

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

\begin{datadesc}{timezone}
(DST でない) ローカルタイムゾーンの UTC からの時刻オフセットで、西に
行くほど増加する秒で表した値です (ほとんどの西ヨーロッパでは負になり、
アメリカでは正、イギリスではゼロになります) 。
\end{datadesc}

\begin{datadesc}{tzname}
二つの文字列からなるタプルです。最初の要素は DST でないローカルの
タイムゾーン名です。ふたつめの要素は DST のタイムゾーンです。
DST のタイムゾーンが定義されていない場合。二つ目の文字列を使うべきでは
ありません。
\end{datadesc}

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

利用できるシステム: \UNIX 。

\begin{notice}
多くの場合、環境変数 \envvar{TZ} を変更すると、\function{tzset} を
呼ばない限り \function{localtime} のような関数の出力に影響を
及ぼすため、値が信頼できなくなってしまいます。

\envvar{TZ} 環境変数には空白文字を含めてはなりません。
\end{notice}

環境変数 \envvar{TZ} の標準的な書式は以下です:
(分かりやすいように空白を入れています)
\begin{itemize}
    \item[std offset [dst [offset] [,start[/time], end[/time]]]]
\end{itemize}

各値は以下のようになっています:

\begin{itemize}
  \item[std と dst]
三文字またはそれ以上の英数字で、タイムゾーンの略称を与えます。
この値は time.tzname になります。

  \item[offset]
オフセットは形式: \plusminus{} hh[:mm[:ss]] をとります。
この表現は、UTC 時刻にするためにローカルな時間に加算する必要の
ある時間値を示します。'-' が先頭につく場合、そのタイムゾーンは
本子午線 (Prime Meridian) より東側にあります; それ以外の場合は
本子午線の西側です。オフセットが dst の後ろに続かない場合、
夏時間は標準時より一時間先行しているものと仮定します。

  \item[start[/time],end[/time]]
いつ DST に移動し、DST から戻ってくるかを示します。開始および終了
日時の形式は以下のいずれかです:

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

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

      \item[M\var{m}.\var{n}.\var{d}]
\var{m} 月の第 \var{n} 週における \var{d} 番目の日
(0 <= \var{d} <= 6, 1 <= \var{n} <= 5,  1 <= \var{m} <= 12)
を表します。週 5 は月における最終週の \var{d} 番目の日を表し、
第 4 週か第 5 週のどちらかになります。週 1 は日 \var{d} が最初に
現れる日を指します。日 0 は日曜日です。
    \end{itemize}

時間はオフセットと同じで、先頭に符号 ('-' や '+') を付けてはいけない
ところが違います。時刻が指定されていなければ、デフォルトの値
 02:00:00 になります。
\end{itemize}


\begin{verbatim}
>>> 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'
\end{verbatim}

多くの \UNIX{} システム (*BSD, Linux, Solaris, および Darwin を含む)
では、システムの zoneinfo  (\manpage{tzfile}{5}) データベース
を使ったほうが、タイムゾーンごとの規則を指定する上で便利です。
これを行うには、必要なタイムゾーンデータファイルへのパスを
システムの 'zoneinfo' タイムゾーンデータベースからの相対で表した値
を環境変数 \envvar{TZ} に設定します。システムの 'zoneinfo' は
通常\file{/usr/share/zoneinfo} にあります。例えば、
\code{'US/Eastern'}、 \code{'Australia/Melbourne'}、 \code{'Egypt'} 
ないし \code{'Europe/Amsterdam'} と指定します。

\begin{verbatim}
>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')
\end{verbatim}

\end{funcdesc}


\begin{seealso}
  \seemodule{datetime}{日付と時刻に対する、
    よりオブジェクト指向のインタフェースです。}
  \seemodule{locale}{国際化サービス。ロケールの設定は \module{time} 
	モジュールのいくつかの関数が返す値に影響をおよぼすことがあります。}
  \seemodule{calendar}{一般的なカレンダー関連の関数。  
                       \function{timegm()} はこのモジュールの
                       \function{gmtime()} の逆の操作を行います。}
\end{seealso}
