% XXX what order should the types be discussed in?

\section{\module{datetime} ---
         基本的な日付型および時間型}

\declaremodule{builtin}{datetime}
\modulesynopsis{基本的な日付型および時間型。}
\moduleauthor{Tim Peters}{tim@zope.com}
\sectionauthor{Tim Peters}{tim@zope.com}
\sectionauthor{A.M. Kuchling}{amk@amk.ca}

\versionadded{2.3}


\module{datetime} モジュールでは、日付や時間データを簡単な方法と
複雑な方法の両方で操作するためのクラスを提供しています。
日付や時刻を対象にした四則演算がサポートされている一方で、
このモジュールの実装では出力の書式化や操作を目的とした
データメンバの効率的な取り出しに焦点を絞っています。

日付および時刻オブジェクトには、``naive'' および ``aware'' の
2種類があります。この区別はオブジェクトがタイムゾーン
や夏時間、あるいはその他のアルゴリズム的、政治的な理由に
よる時刻の修正に関する何らかの表記をもつかどうかによるものです。
特定の数字がメートルか、マイルか、質量を表すかといったことが
プログラムの問題であるように、
naive な \class{datetime} オブジェクトが標準世界時 (UTC: Coordinated
Universal time) を表現するか、ローカルの時刻を表現するか、
ありは他のいずれかのタイムゾーンにおける時刻を表現するかは
純粋にプログラムの問題となります。
naive な \class{datetime} オブジェクトは、
現実世界のいくつかの側面を無視するという犠牲のもとに、
理解しやすく、かつ利用しやすくなっています。

より多くの情報を必要とするアプリケーションのために、
\class{datetime} および \class{time} オブジェクトはオプションの
タイムゾーン情報メンバ、\member{tzinfo} を持っています。このメンバ
には抽象クラス \class{tzinfo} のサブクラスのインスタンスが入って
います。\class{tzinfo} オブジェクトは UTC 時刻からのオフセット、
タイムゾーン名、夏時間が有効になっているかどうか、といった情報
を記憶しています。
\module{datetime} モジュールでは具体的な \class{tsinfo} クラスを
提供していないので注意してください。必要な詳細仕様を備えた
タイムゾーン機能を提供するのはアプリケーションの責任です。
世界各国における時刻の修正に関する法則は合理的というよりも政治的な
ものであり、全てのアプリケーションに適した標準というものが
存在しないのです。

\module{datetime} モジュールでは以下の定数を公開しています:

\begin{datadesc}{MINYEAR}
\class{date} や \class{datetime} オブジェクトで許されている、
年を表現する最小の数字です。\constant{MINYEAR} は \code{1} です。
\end{datadesc}

\begin{datadesc}{MAXYEAR}
\class{date} や \class{datetime} オブジェクトで許されている、
年を表現する最大の数字です。\constant{MAXYEAR} は \code{9999} です。
\end{datadesc}

\begin{seealso}
  \seemodule{calendar}{汎用のカレンダー関連関数。}
  \seemodule{time}{時刻へのアクセスと変換。}
\end{seealso}

\subsection{利用可能なデータ型}

\begin{classdesc*}{date}
理想化された naive な日付表現で、実質的には、これまでもこれからも
現在のグレゴリオ暦 (Gregorian calender) であると仮定しています。
  属性: \member{year}、 \member{month}、および \member{day}。
\end{classdesc*}

\begin{classdesc*}{time}
理想化された時刻表現で、あらゆる特定の日における影響から独立
しており、毎日厳密に 24*60*60 秒であると仮定します
("うるう秒: leap seconds" の概念はありません)。
  属性: \member{hour}、 \member{minute}、\member{second}、
              \member{microsecond}、 および \member{tzinfo}。
\end{classdesc*}

\begin{classdesc*}{datetime}
日付と時刻を組み合わせたもの。
  属性: \member{year}、 \member{month}、 \member{day}、
              \member{hour}、 \member{minute}、 \member{second}、
              \member{microsecond}、および \member{tzinfo}。
\end{classdesc*}

\begin{classdesc*}{timedelta}
\class{date}、\class{time}、あるいは \class{datetime} クラスの
二つのインスタンス間の時間差をマイクロ秒精度で表す経過時間値です。
\end{classdesc*}

\begin{classdesc*}{tzinfo}
タイムゾーン情報オブジェクトの抽象基底クラスです。
\class{datetime} および \class{time} クラスで用いられ、
カスタマイズ可能な時刻修正の概念 (たとえばタイムゾーンや
夏時間の計算）を提供します。
\end{classdesc*}

これらの型のオブジェクトは変更不可能 (immutable) です。

\class{date} 型のオブジェクトは常に naive です。

\class{time} や \class{datetime} 型のオブジェクト \var{d} は
naive にも aware にもできます。\var{d} は \code{\var{d}.tzinfo}
が \code{None} でなく、かつ \code{\var{d}.tzinfo.utcoffset(\var{d})}
が \code{None} を返さない場合に aware となります。\code{\var{d}.tzinfo}
が \code{None} の場合や、\code{\var{d}.tzinfo} は \code{None} では
ないが \code{\var{d}.tzinfo.utcoffset(\var{d})} が \code{None} を
返す場合には、\var{d} は naive となります。

naive なオブジェクトと aware なオブジェクトの区別は
\class{timedelta} オブジェクトにはあてはまりません。

サブクラスの関係は以下のようになります:

\begin{verbatim}
object
    timedelta
    tzinfo
    time
    date
        datetime
\end{verbatim}

\subsection{\class{timedelta} オブジェクト \label{datetime-timedelta}}

\class{timedelta} オブジェクトは経過時間、すなわち二つの日付
や時刻間の差を表します。

\begin{classdesc}{timedelta}{\optional{days\optional{, seconds\optional{,
                             microseconds\optional{, milliseconds\optional{,
                             minutes\optional{, hours\optional{, weeks}}}}}}}}

全ての引数がオプションで、デフォルト値は\var{0}です。引数は整数、長整
数、浮動小数点数にすることができ、正でも負でもかまいません。

\var{days}、\var{seconds} および \var{microseconds} のみが
内部に記憶されます。引数は以下のようにして変換されます:

\begin{itemize}
  \item 1 ミリ秒は 1000 マイクロ秒に変換されます。
  \item 1 分は 60 秒に変換されます。
  \item 1 時間は 3600 秒に変換されます。
  \item 1 週間は 7 日に変換されます。
\end{itemize}

その後、日、秒、マイクロ秒は値が一意に表されるように、

\begin{itemize}
  \item \code{0 <= \var{microseconds} < 1000000}
  \item \code{0 <= \var{seconds} < 3600*24} (一日中の秒数)
  \item \code{-999999999 <= \var{days} <= 999999999}
\end{itemize}

で正規化されます。

引数のいずれかが浮動小数点であり、小数のマイクロ秒が存在する場合、
小数のマイクロ秒は全ての引数から一度取り置かれ、それらの和は
最も近いマイクロ秒に丸められます。浮動小数点の引数がない場合、
値の変換と正規化の過程は厳密な (失われる情報がない) ものとなります。

日の値を正規化した結果、指定された範囲の外側になった場合には、
\exception{OverflowError} が送出されます。

負の値を正規化すると、一見混乱するような値になります。
例えば、

\begin{verbatim}
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)
\end{verbatim}
\end{classdesc}

クラス属性を以下に示します:

\begin{memberdesc}{min}
最小の値を表す \class{timedelta} オブジェクトで、
\code{timedelta(-999999999)} です。
\end{memberdesc}

\begin{memberdesc}{max}
最大の値を表す \class{timedelta} オブジェクトで、
  \code{timedelta(days=999999999, hours=23, minutes=59, seconds=59,
                  microseconds=999999)} です。
\end{memberdesc}

\begin{memberdesc}{resolution}
\class{timedelta} オブジェクトが等しくならない最小の
時間差で、\code{timedelta(microseconds=1)} です。
\end{memberdesc}

正規化のために、\code{timedelta.max} \textgreater \code{-timedelta.min}
となるので注意してください。\code{-timedelta.max} は \class{timedelta} 
オブジェクトとして表現することができません。

以下に (読み出し専用の) インスタンス属性を示します:

\begin{tableii}{c|l}{code}{属性}{値}
  \lineii{days}{両端値を含む -999999999 から 999999999 の間}
  \lineii{seconds}{両端値を含む 0 から 86399 の間}
  \lineii{microseconds}{両端値を含む 0 から 999999 の間}
\end{tableii}

サポートされている操作を以下に示します:

% XXX this table is too wide!
\begin{tableii}{c|l}{code}{演算}{結果}
  \lineii{\var{t1} = \var{t2} + \var{t3}}
    {\var{t2} と \var{t3} を加算します。演算後、 
\var{t1}-\var{t2} == \var{t3} および \var{t1}-\var{t3} == \var{t2} は
真になります。 (1)}
  \lineii{\var{t1} = \var{t2} - \var{t3}} 
    {\var{t2} と \var{t3} の差分です。演算後、 
\var{t1} == \var{t2} - \var{t3} および \var{t2} == \var{t1} + \var{t3} は
真になります。 (1)}
  \lineii{\var{t1} = \var{t2} * \var{i} or \var{t1} = \var{i} * \var{t2}}
          {整数や長整数による乗算です。演算後、 
\var{t1} // i == \var{t2} は \code{i != 0} であれば真となります。}
  \lineii{}{一般的に、 \var{t1} * i == \var{t1} * (i-1) + \var{t1} は真となります。(1)}
  \lineii{\var{t1} = \var{t2} // \var{i}}
          {端数を切り捨てて除算され、剰余 (がある場合) は捨てられます。(3)}
  \lineii{+\var{t1}}
          {同じ値を持つ\class{timedelta} オブジェクトを返します。(2)}
  \lineii{-\var{t1}}
          {\class{timedelta}(-\var{t1.days}, -\var{t1.seconds},
           -\var{t1.microseconds})、および \var{t1}* -1 と同じです。
          (1)(4)}
  \lineii{abs(\var{t})}
          {\code{t.days >= 0} のときには +\var{t} 、\code{t.days < 0} の
ときには -\var{t} となります。(2)}
\end{tableii}
\noindent
注釈:

\begin{description}
\item[(1)]
この操作は厳密ですが、オーバフローするかもしれません。

\item[(2)]
この操作は厳密であり、オーバフローしないはずです。

\item[(3)]
0 による除算は  \exception{ZeroDivisionError} を送出します。

\item[(4)]
  -\var{timedelta.max} は \class{timedelta} オブジェクトで表現することができません。
\end{description}

上に列挙した操作に加えて、\class{timedelta} オブジェクトは
\class{date} および \class{datetime} オブジェクトとの間で
加減算をサポートしています (下を参照してください)。

\class{timedelta} オブジェクト間の比較はサポートされており、 
より小さい経過時間を表す \class{timedelta} オブジェクトが
より小さい timedelta と見なされます。
型混合の比較がデフォルトのオブジェクトアドレス比較となってしまう
のを抑止するために、\class{timedelta} オブジェクトと異なる型の
オブジェクトが比較されると、比較演算子が \code{==} または \code{!=}
でないかぎり \exception{TypeError} が送出されます。
後者の場合、それぞれ \constant{False} または \constant{True}
を返します。

\class{timedelta} オブジェクトはハッシュ可能 (辞書のキーとして利用可能)
であり、効率的な pickle 化をサポートします、また、ブール演算コンテキスト
では、 \class{timedelta} オブジェクトは \code{timedelta(0)} に等しくない
場合かつそのときに限り真となります。


\subsection{\class{date} オブジェクト \label{datetime-date}}

\class{date} オブジェクトは日付 (年、月、および日) を表します。
日付は理想的なカレンダー、すなわち現在のグレゴリオ暦を過去と未来の
両方向に無限に延長したもので表されます。1 年の 1 月 1 日は日番号 1、
1 年 1 月 2 日は日番号 2、となっていきます。この暦法は、
全ての計算における基本カレンダーである、
Dershowitz と Reingold の書籍 \citetitle{Calendrical Calculations}
における "予期的グレゴリオ (proleptic Gregorian)" 暦の定義に一致します。

\begin{classdesc}{date}{year, month, day}
全ての引数が必要です。引数は整数でも長整数でもよく、以下の範囲に
入らなければなりません:

  \begin{itemize}
    \item \code{MINYEAR <= \var{year} <= MAXYEAR}
    \item \code{1 <= \var{month} <= 12}
    \item \code{1 <= \var{day} <= 指定された月と年における日数}
  \end{itemize}

範囲を超えた引数を与えた場合、\exception{ValueError} が送出
されます。
\end{classdesc}

他のコンストラクタ、および全てのクラスメソッドを以下に示します:

\begin{methoddesc}{today}{}
現在のローカルな日付を返します。
\code{date.fromtimestamp(time.time())} と等価です。
\end{methoddesc}

\begin{methoddesc}{fromtimestamp}{timestamp}
\function{time.time()} が返すような POSIX タイムスタンプ
に対応する、ローカルな日付を返します。
タイムスタンプがプラットフォームにおける C 関数 \cfunction{localtime()}
でサポートされている範囲を超えている場合には \exception{ValueError}
を送出することがあります。
この値はよく 1970 年から 2038 年に制限されていることがあります。
うるう秒がタイムスタンプの概念に含まれている非 POSIX システム
では、\method{fromtimestamp()} はうるう秒を無視します。
\end{methoddesc}

\begin{methoddesc}{fromordinal}{ordinal}
予期的グレゴリオ暦順序に対応する日付を表し、1 年 1 月 1 日が序数 1 
となります。\code{1 <= \var{ordinal} <= date.max.toordinal()}
でない場合、\exception{ValueError} が送出されます。
任意の日付 \var{d} に対し、
\code{date.fromordinal(\var{d}.toordinal()) ==  \var{d}}
となります。
\end{methoddesc}

以下にクラス属性を示します:

\begin{memberdesc}{min}
表現できる最も古い日付で、\code{date(MINYEAR, 1, 1)} です。
\end{memberdesc}

\begin{memberdesc}{max}
表現できる最も新しい日付で、 \code{date(MAXYEAR, 12, 31)} です。
\end{memberdesc}

\begin{memberdesc}{resolution}
等しくない日付オブジェクト間の最小の差で、 \code{timedelta(days=1)}
です。
\end{memberdesc}

以下に (読み出し専用の) インスタンス属性を示します:

\begin{memberdesc}{year}
両端値を含む \constant{MINYEAR} から \constant{MAXYEAR} までの値です。
\end{memberdesc}

\begin{memberdesc}{month}
両端値を含む 1 から 12 までの値です。
\end{memberdesc}

\begin{memberdesc}{day}
1 から与えられた月と年における日数までの値です。
\end{memberdesc}

サポートされている操作を以下に示します:

\begin{tableii}{c|l}{code}{演算}{結果}
  \lineii{\var{date2} = \var{date1} + \var{timedelta}}
    {\var{date2} はから \var{date1} から \code{\var{timedelta}.days} 日
移動した日付です。 (1)}


  \lineii{\var{date2} = \var{date1} - \var{timedelta}}
   {\code{\var{date2} + \var{timedelta}
   == \var{date1}} であるような日付 \var{date2} を計算します。 (2)}

  \lineii{\var{timedelta} = \var{date1} - \var{date2}}
   {(3)}

  \lineii{\var{date1} < \var{date2}}
   {\var{date1} が時刻として \var{date2} よりも前を表す場合に、
\var{date1} は\var{date2} よりも小さいと見なされます。
 (4)}

\end{tableii}

注釈:
\begin{description}

\item[(1)]
\var{date2} は \code{\var{timedelta}.days > 0} の場合進む方向に、
\code{\var{timedelta}.days < 0} の場合戻る方向に移動します。
演算後は、\code{\var{date2} - \var{date1} == \var{timedelta}.days}
となります。
\code{\var{timedelta}.seconds} および
\code{\var{timedelta}.microseconds} は無視されます。
\code{\var{date2}.year} が \constant{MINYEAR} になってしまったり、
\constant{MAXYEAR} より大きくなってしまう場合には
\exception{OverflowError} が送出されます。

\item[(2)]
この操作は date1 + (-timedelta) と等価ではありません。なぜならば、
date1 - timedeltaがオーバフローしない場合でも、-timedelta 単体が
オーバフローする可能性があるからです。
\code{\var{timedelta}.seconds} および
\code{\var{timedelta}.microseconds} は無視されます。

\item[(3)]
この演算は厳密で、オーバフローしません。timedelta.seconds
および timedelta.microseconds は 0 で、演算後には
date2 + timedelta == date1 となります。

\item[(4)]
別の言い方をすると、\code{\var{date1}.toordinal() < \var{date2}.toordinal()}
であり、かつそのときに限り \code{date1 < date2} となります。
型混合の比較がデフォルトのオブジェクトアドレス比較となってしまう
のを抑止するために、\class{timedelta} オブジェクトと異なる型の
オブジェクトが比較されると \exception{TypeError} が送出されます。
しかしながら、被比較演算子のもう一方が \method{timetuple} 属性を
持つ場合には \code{NotImplemented} が返されます。
このフックにより、他種の日付オブジェクトに型混合比較を実装する
チャンスを与えています。
そうでない場合、\class{timedelta} オブジェクトと異なる型の
オブジェクトが比較されると、比較演算子が \code{==} または \code{!=}
でないかぎり \exception{TypeError} が送出されます。
後者の場合、それぞれ \constant{False} または \constant{True}
を返します。

\end{description}

\class{date} オブジェクトは辞書のキーとして用いることができます。
ブール演算コンテキストでは、全ての \class{date} オブジェクトは
真であるとみなされます。

以下にインスタンスメソッドを示します:

\begin{methoddesc}{replace}{year, month, day}
キーワード引数で指定されたデータメンバが置き換えられることを
除き、同じ値を持つ \class{date} オブジェクトを返します。
例えば、\code{d == date(2002, 12, 31)} とすると、
  \code{d.replace(day=26) == date(2002, 12, 26)} となります。
\end{methoddesc}

\begin{methoddesc}{timetuple}{}
\function{time.localtime()} が返す形式の\class{time.struct_time} を返します。
時間、分、および秒は 0 で、DST フラグは -1 になります。
  \code{\var{d}.timetuple()} は
      \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day,
             0, 0, 0, 
             \var{d}.weekday(), 
             \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
            -1))}
と等価です。
\end{methoddesc}

\begin{methoddesc}{toordinal}{}
予測的グレゴリオ暦における日付序数を返します。 1 年の 1 月 1 日が
序数 1 となります。任意の \class{date} オブジェクト \var{d} に
ついて、
\code{date.fromordinal(\var{d}.toordinal()) == \var{d}}
となります。
\end{methoddesc}

\begin{methoddesc}{weekday}{}
月曜日を 0、日曜日を 6 として、曜日を整数で返します。
例えば、 \code{date(2002, 12, 4).weekday() == 2}
であり、水曜日を示します。
 \method{isoweekday()} も参照してください。
\end{methoddesc}

\begin{methoddesc}{isoweekday}{}
月曜日を 1、日曜日を 7 として、曜日を整数で返します。
例えば、 \code{date(2002, 12, 4).weekday() == 3}
であり、水曜日を示します。
\method{weekday()}、\method{isocalendar()} も参照してください。
\end{methoddesc}

\begin{methoddesc}{isocalendar}{}
3 要素のタプル (ISO 年、ISO 週番号、ISO 曜日) を返します。

ISO カレンダーはグレゴリオ暦の変種として広く用いられています。
細かい説明については
\url{http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm}
を参照してください。

ISO 年は完全な週が 52 または 53 週あり、週は月曜から始まって日曜に
終わります。ISO 年でのある年における最初の週は、その年の木曜日を含む
最初の (グレゴリオ暦での) 週となります。この週は週番号 1 と呼ばれ、
この木曜日での ISO 年はグレゴリオ暦における年と等しくなります。

例えば、2004 年は木曜日から始まるため、ISO 年の最初の週は
2003 年 12 月 29 日、月曜日から始まり、2004 年 1 月 4 日、日曜日に
終わります。従って、
  \code{date(2003, 12, 29).isocalendar() == (2004, 1, 1)}
であり、かつ
  \code{date(2004, 1, 4).isocalendar() == (2004, 1, 7)}
となります。
\end{methoddesc}

\begin{methoddesc}{isoformat}{}
ISO 8601 形式、'YYYY-MM-DD' の日付を表す文字列を返します。
例えば、
  \code{date(2002, 12, 4).isoformat() == '2002-12-04'}
となります。
\end{methoddesc}

\begin{methoddesc}{__str__}{}
\class{date} オブジェクト \var{d} において、
\code{str(\var{d})} は \code{\var{d}.isoformat()} と等価です。
\end{methoddesc}

\begin{methoddesc}{ctime}{}
日付を表す文字列を、例えば
  date(2002, 12, 4).ctime() == 'Wed Dec  4 00:00:00 2002'
のようにして返します。
ネイティブの C 関数 \cfunction{ctime()} 
(\function{time.ctime()} はこの関数を呼び出しますが、
\method{date.ctime()} は呼び出しません) が C 標準に準拠
しているプラットフォームでは、
  \code{\var{d}.ctime()} は
  \code{time.ctime(time.mktime(\var{d}.timetuple()))}
と等価です。
\end{methoddesc}

\begin{methoddesc}{strftime}{format}
明示的な書式化文字列で制御された、日付を表現する文字列を返します。
時間、分、秒を表す書式化コードは値 0 になります。
\method{strftime()} のふるまいについてのセクション~\ref{strftime-behavior}を参照して
ください。
\end{methoddesc}


\subsection{\class{datetime} オブジェクト \label{datetime-datetime}}

\class{datetime} オブジェクトは \class{date} オブジェクトおよび
\class{time} オブジェクトの全ての情報が入っている単一のオブジェクト
です。\class{date} オブジェクトと同様に、\class{datetime} は
現在のグレゴリオ暦が両方向に延長されているものと仮定します;
また、\class{time} オブジェクトと同様に、\class{datetime} は
毎日が厳密に 3600*24 秒であると仮定します。

以下にコンストラクタを示します:

\begin{classdesc}{datetime}{year, month, day\optional{,
                            hour\optional{, minute\optional{,
                            second\optional{, microsecond\optional{,
                            tzinfo}}}}}}
年、月、および日の引数は必須です。\var{tzinfo} は
\code{None} または \class{tzinfo} クラスのサブクラスのインスタンス
にすることができます。残りの引数は整数または長整数で、
以下のような範囲に入ります:

  \begin{itemize}
    \item \code{MINYEAR <= \var{year} <= MAXYEAR}
    \item \code{1 <= \var{month} <= 12}
    \item \code{1 <= \var{day} <= 与えられた年と月における日数}
    \item \code{0 <= \var{hour} < 24}
    \item \code{0 <= \var{minute} < 60}
    \item \code{0 <= \var{second} < 60}
    \item \code{0 <= \var{microsecond} < 1000000}
  \end{itemize}

引数がこれらの範囲外にある場合、
  \exception{ValueError} が送出されます。
\end{classdesc}

その他のコンストラクタ、およびクラスメソッドを以下に示します:

\begin{methoddesc}{today}{}
現在のローカルな \class{datetime} を \member{tzinfo} が \code{None}
であるものとして返します。
これは
  \code{datetime.fromtimestamp(time.time())} と等価です。
\method{now()}、 \method{fromtimestamp()} も参照してください。
\end{methoddesc}

\begin{methoddesc}{now}{\optional{tz}}
現在のローカルな日付および時刻を返します。オプションの引数
\var{tz} が \code{None} であるか指定されていない場合、この
メソッドは \method{today()} と同様ですが、可能ならば
\function{time.time()} タイムスタンプを通じて得ることができる
より高い精度で時刻を提供します  (例えば、プラットフォームが C 
関数 \cfunction{gettimeofday()} をサポートする場合には可能なことがあります)。

そうでない場合、\var{tz} はクラス \class{tzinfo} のサブクラスの
インスタンスでなければならず、現在の日付および時刻は
\var{tz} のタイムゾーンに変換されます。この場合、結果は
  \code{\var{tz}.fromutc(datetime.utcnow().replace(tzinfo=\var{tz}))}
と等価になります。
\method{today()}, \method{utcnow()} も参照してください。
\end{methoddesc}

\begin{methoddesc}{utcnow}{}
現在の UTC における日付と時刻を、 \member{tzinfo} が \code{None} で
あるものとして返します。このメソッドは \method{now()} に似ていますが、
現在の UTC における日付と時刻を naive な \class{datetime} オブジェクト
として返します。\method{now()} も参照してください。
\end{methoddesc}

\begin{methoddesc}{fromtimestamp}{timestamp\optional{, tz}}
\function{time.time()} が返すような、\POSIX{} タイムスタンプに
対応するローカルな日付と時刻を返します。
オプションの引数 \var{tz} が \code{None} であるか、指定されて
いない場合、タイムスタンプはプラットフォームのローカルな日付および
時刻に変換され、返される \class{datetime} オブジェクトは naive 
なものになります。

そうでない場合、 \var{tz} はクラス \class{tzinfo} のサブクラスの
インスタンスでなければならず、現在の日付および時刻は
\var{tz} のタイムゾーンに変換されます。この場合、結果は
  \code{\var{tz}.fromutc(datetime.utcfromtimestamp(\var{timestamp}).replace(tzinfo=\var{tz}))}
と等価になります。

タイムスタンプがプラットフォームの C 関数 \cfunction{localtime()} や
\cfunction{gmtime()} でサポートされている範囲を超えた場合、
\method{fromtimestamp()} は \exception{ValueError} を送出する
ことがあります。この範囲はよく 1970 年から 2038 年に制限されて
います。
うるう秒がタイムスタンプの概念に含まれている非 POSIX システム
では、\method{fromtimestamp()} はうるう秒を無視します。
このため、秒の異なる二つのタイムスタンプが同一の \class{datetime}
オブジェクトとなることが起こり得ます。
\method{utcfromtimestamp()} も参照してください。
\end{methoddesc}

\begin{methoddesc}{utcfromtimestamp}{timestamp}
\function{time.time()} が返すような POSIX タイムスタンプ
に対応する、UTC での \class{datetime} オブジェクトを返します。
タイムスタンプがプラットフォームにおける C 関数 \cfunction{localtime()}
でサポートされている範囲を超えている場合には \exception{ValueError}
を送出することがあります。
この値はよく 1970 年から 2038 年に制限されていることがあります。
\method{fromtimestamp()} も参照してください。
\end{methoddesc}

\begin{methoddesc}{fromordinal}{ordinal}
1 年 1 月 1 日を序数 1 とする予測的グレゴリオ暦序数に対応する
\class{datetime} オブジェクトを返します。
\code{1 <= ordinal <=  datetime.max.toordinal()} でないかぎり
\exception{ValueError} が送出されます。結果として返される
オブジェクトの時間、分、秒、およびマイクロ秒はすべて 0 となり、
\member{tzinfo} は \code{None} となります。
\end{methoddesc}

\begin{methoddesc}{combine}{date, time}
与えられた \class{date} オブジェクトと同じデータメンバを持ち、
時刻と \member{tzinfo} メンバが与えられた \class{time} オブジェクト
と等しい、新たな \class{datetime} オブジェクトを返します。
任意の \class{datetime} オブジェクト \var{d} について、
\code{\var{d} == datetime.combine(\var{d}.date(), \var{d}.timetz())}
となります。\var{date} が \class{datetime} オブジェクトの場合、
その時刻と \member{tzinfo} は無視されます。
\end{methoddesc}

\begin{methoddesc}{strptime}{date_string, format}
  \var{date_string} に対応した\class{datetime} をかえします。
  \var{format}にしたがって構文解析されます。これは、
  \code{datetime(*(time.strptime(date_string, format)[0:6]))} と等価です。
  date_stringとformatが\function{time.strptime()}で構文解析できない場合
  や、この関数が 時刻タプルを返してこない場合には\exception{ValueError}
  がおこります。

  \versionadded{2.5}
\end{methoddesc}



以下にクラス属性を示します:

\begin{memberdesc}{min}
表現できる最も古い \class{datetime} で、
  \code{datetime(MINYEAR, 1, 1, tzinfo=None)} です。
\end{memberdesc}

\begin{memberdesc}{max}
表現できる最も新しい \class{datetime} で、
  \code{datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)} です。
\end{memberdesc}

\begin{memberdesc}{resolution}
等しくない \class{datetime} オブジェクト間の最小の差で、 
\code{timedelta(microseconds=1)}
です。
\end{memberdesc}

以下に (読み出し専用の) インスタンス属性を示します:

\begin{memberdesc}{year}
両端値を含む \constant{MINYEAR} から \constant{MAXYEAR} までの値です。
\end{memberdesc}

\begin{memberdesc}{month}
両端値を含む 1 から 12 までの値です。
\end{memberdesc}

\begin{memberdesc}{day}
1 から与えられた月と年における日数までの値です。
\end{memberdesc}

\begin{memberdesc}{hour}
\code{range(24)} 内の値です。
\end{memberdesc}

\begin{memberdesc}{minute}
\code{range(60)} 内の値です。
\end{memberdesc}

\begin{memberdesc}{second}
\code{range(60)} 内の値です。
\end{memberdesc}

\begin{memberdesc}{microsecond}
\code{range(1000000)} 内の値です。
\end{memberdesc}

\begin{memberdesc}{tzinfo}
\class{datetime} コンストラクタに \var{tzinfo} 引数として
与えられたオブジェクトになり、何も渡されなかった場合には \code{None}
になります。
\end{memberdesc}

以下にサポートされている演算を示します:

\begin{tableii}{c|l}{code}{演算}{結果}
  \lineii{\var{datetime2} = \var{datetime1} + \var{timedelta}}{(1)}

  \lineii{\var{datetime2} = \var{datetime1} - \var{timedelta}}{(2)}

  \lineii{\var{timedelta} = \var{datetime1} - \var{datetime2}}{(3)}

  \lineii{\var{datetime1} < \var{datetime2}}
   { \class{datetime} を \class{datetime} と比較します。 
    (4)}

\end{tableii}

\begin{description}

\item[(1)]

datetime2 は datetime1 から時間 timedelta 移動したもので、
\code{\var{timedelta}.days > 0} の場合進む方向に、
\code{\var{timedelta}.days < 0} の場合戻る方向に移動します。
結果は入力の datetime と同じ \member{tzinfo} を持ち、
演算後には datetime2 - datetime1 == timedelta となります。
datetime2.year が \constant{MINYEAR} よりも小さいか、
\constant{MAXYEAR} より大きい場合には \exception{OverflowError} 
が送出されます。
入力が aware なオブジェクトの場合でもタイムゾーン修正は全く行われ
ません。

\item[(2)]
datetime2 + timedelta == datetime1 となるような datetime2 を
計算します。ちなみに、結果は入力の datetime と同じ \member{tzinfo}
メンバを持ち、入力が aware でもタイムゾーン修正は全く行われ
ません。
この操作は date1 + (-timedelta) と等価ではありません。なぜならば、
date1 - timedeltaがオーバフローしない場合でも、-timedelta 単体が
オーバフローする可能性があるからです。

\item[(3)]
\class{datetime} から \class{datetime} の減算は両方の被演算子が
naive であるか、両方とも aware である場合にのみ定義されています
片方が aware でもう一方が naive の場合、 \exception{TypeError} 
が送出されます。

両方とも naive か、両方とも aware で同じ \member{tzinfo} メンバ
を持つ場合、\member{tzinfo} メンバは無視され、結果は
\code{\var{datetime2} + \var{t} == \var{datetime1}} であるような
\class{timedelta} オブジェクト \var{t} となります。
この場合タイムゾーン修正は全く行われません。

両方が aware で異なる \member{tzinfo} メンバを持つ場合、
\code{a-b} は \var{a} および \var{b} をまず naive な UTC datetime
オブジェクトに変換したかのようにして行います。演算結果は
決してオーバフローを起こさないことを除き、
    \code{(\var{a}.replace(tzinfo=None) - \var{a}.utcoffset()) -
          (\var{b}.replace(tzinfo=None) - \var{b}.utcoffset())}
と同じになります。

\item[(4)]
\var{datetime1} が時刻として \var{datetime2} よりも前を表す場合に、
\var{datetime1} は\var{datetime2} よりも小さいと見なされます。

被演算子の片方が naive でもう一方が aware の場合、
\exception{TypeError} が送出されます。両方の被演算子が aware で、
同じ \member{tzinfo} メンバを持つ場合、共通の \member{tzinfo}
メンバは無視され、基本の datetime 間の比較が行われます。
両方の被演算子が aware で異なる \member{tzinfo} メンバを持つ
場合、被演算子はまず (\code{self.utcoffset()} で得られる) UTC 
オフセット で修正されます。
\note{型混合の比較がデフォルトのオブジェクトアドレス比較となってしまう
のを抑止するために、被演算子のもう一方が \class{datatime} オブジェクトと
異なる型のオブジェクトの場合には \exception{TypeError} が送出されます。
しかしながら、被比較演算子のもう一方が \method{timetuple} 属性を
持つ場合には \code{NotImplemented} が返されます。
このフックにより、他種の日付オブジェクトに型混合比較を実装する
チャンスを与えています。
そうでない場合、\class{datetime} オブジェクトと異なる型の
オブジェクトが比較されると、比較演算子が \code{==} または \code{!=}
でないかぎり \exception{TypeError} が送出されます。
後者の場合、それぞれ \constant{False} または \constant{True}
を返します。}

\end{description}

\class{datetime} オブジェクトは辞書のキーとして用いることができます。
ブール演算コンテキストでは、全ての \class{datetime} オブジェクトは
真であるとみなされます。


インスタンスメソッドを以下に示します:

\begin{methoddesc}{date}{}
同じ年、月、日の \class{date} オブジェクトを返します。
\end{methoddesc}

\begin{methoddesc}{time}{}
同じ時、分、秒、マイクロ秒を持つ \class{time} オブジェクトを返します。
\member{tzinfo} は \code{None} です。\method{timetz()} も参照
してください。
\end{methoddesc}

\begin{methoddesc}{timetz}{}
同じ時、分、秒、マイクロ秒、および tzinfo メンバを持つ
\class{time} オブジェクトを返します。
\method{time()} メソッドも参照してください。
\end{methoddesc}

\begin{methoddesc}{replace}{\optional{year\optional{, month\optional{,
                            day\optional{, hour\optional{, minute\optional{,
                            second\optional{, microsecond\optional{,
                            tzinfo}}}}}}}}}
キーワード引数で指定したメンバの値を除き、同じ値をもつ datetime 
オブジェクトを返します。
メンバに対する変換を行わずに aware な datetime オブジェクトから 
naive な datetime オブジェクトを生成するために、
\code{tzinfo=None} を指定することもできます。
\end{methoddesc}

\begin{methoddesc}{astimezone}{tz}
\class{datetime} オブジェクトを返します。返されるオブジェクトは
新たな \member{tzinfo} メンバ \var{tz} を持ちます。\var{tz}
は日付および時刻を調整して、オブジェクトが \var{self} と同じ
UTC 時刻を持つが、\var{tz} におけるローカルな時刻を表すようにします。

\var{tz} は \class{tzinfo} のサブクラスのインスタンスでなければ
ならず、インスタンスの \method{utcoffset()} および \method{dst()} 
メソッドは \code{None} を返してはなりません。\var{self} は
aware でなくてはなりません (\code{\var{self}.tzinfo} が \code{None}
であってはならず、かつ \code{\var{self}.utcoffset()} は \code{None}
を返してはなりません)。

\code{\var{self}.tzinfo} が \var{tz} の場合、
\code{\var{self}.astimezone(\var{tz})} は \var{self} に等しくなります: 
日付および時刻データメンバに対する調整は行われません。
そうでない場合、結果はタイムゾーン \var{tz} におけるローカル時刻で、
\var{self} と同じ UTC 時刻を表すようになります:
\code{\var{astz} = \var{dt}.astimezone(\var{tz})} とした後、
  \code{\var{astz} - \var{astz}.utcoffset()} 
は通常 \code{\var{dt} - \var{dt}.utcoffset()} と同じ日付および時刻
データメンバを持ちます。
\class{tzinfo} クラスに関する議論では、夏時間 (Daylight Saving time)
の遷移境界では上の等価性が成り立たないことを説明しています
(\var{tz} が標準時と夏時間の両方をモデル化している場合のみの問題です)。

単にタイムゾーンオブジェクト \var{tz} を \class{datetime} オブジェクト
\var{dt} に追加したいだけで、日付や時刻データメンバへの調整
を行わないのなら、\code{\var{dt}.replace(tzinfo=\var{tz})} を使って
ください。
単に aware な \class{datetime} オブジェクト \var{dt} からタイムゾーン
オブジェクトを除去したいだけで、日付や時刻データメンバの変換を
行わないのなら、\code{\var{dt}.replace(tzinfo=None)} を使ってください。

デフォルトの \method{tzinfo.fromutc()} メソッドを \class{tzinfo}
のサブクラスで上書きして、\method{astimezone()} が返す結果に
影響を及ぼすことができます。エラーの場合を無視すると、
\method{astimezone()} は以下のように動作します:

  \begin{verbatim}
  def astimezone(self, tz):
      if self.tzinfo is tz:
          return self
      # Convert self to UTC, and attach the new time zone object.
      utc = (self - self.utcoffset()).replace(tzinfo=tz)
      # Convert from UTC to tz's local time.
      return tz.fromutc(utc)
  \end{verbatim}
\end{methoddesc}

\begin{methoddesc}{utcoffset}{}
\member{tzinfo} が \code{None} の場合、\code{None} を返し、
そうでない場合には \code{\var{self}.tzinfo.utcoffset(\var{self})}
を返します。後者の式が \code{None} か、1 日以下の大きさを持つ
経過時間を表す \class{timedelta} オブジェクトのいずれかを返さない
場合には例外を送出します。
\end{methoddesc}

\begin{methoddesc}{dst}{}
\member{tzinfo} が \code{None} の場合、\code{None} を返し、
そうでない場合には \code{\var{self}.tzinfo.dst(\var{self})}
を返します。後者の式が \code{None} か、1 日以下の大きさを持つ
経過時間を表す \class{timedelta} オブジェクトのいずれかを返さない
場合には例外を送出します。
\end{methoddesc}

\begin{methoddesc}{tzname}{}
\member{tzinfo} が \code{None} の場合、\code{None} を返し、
そうでない場合には \code{\var{self}.tzinfo.tzname(\var{self})}
を返します。後者の式が \code{None} か文字列オブジェクトのいずれか
を返さない場合には例外を送出します。
\end{methoddesc}

\begin{methoddesc}{timetuple}{}
\function{time.localtime()} が返す形式の
\class{time.struct_time} を返します。
  \code{\var{d}.timetuple()} は
  \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day,
         \var{d}.hour, \var{d}.minute, \var{d}.second,
         \var{d}.weekday(),
         \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
         dst))}
と等価です。
返されるタプルの \member{tm_isdst} フラグは \method{dst()} メソッドに
従って設定されます:  \member{tzinfo} が \code{None} か
  \method{dst()} が \code{None} を返す場合、
  \member{tm_isdst} は \code{-1} に設定されます; そうでない場合、
\method{dst()} がゼロでない値を返すと、\member{tm_isdst} は \code{1}
となります; それ以外の場合には \code{tm_isdst} は\code{0} に設定
されます。
\end{methoddesc}

\begin{methoddesc}{utctimetuple}{}
\class{datetime} インスタンス \var{d} が naive の場合、このメソッドは
\code{\var{d}.timetuple()} と同じであり、\code{d.dst()} の返す内容に
かかわらず \member{tm_isdst} が 0 に強制される点だけが異なります。
DST が UTC 時刻に影響を及ぼすことは決してありません。

\var{d} が aware の場合、\var{d} から \code{\var{d}.utcoffset()} が差し
引かれて UTC 時刻に正規化され、正規化された時刻の \class{time.struct_time}
を返します。\member{tm_isdst} は 0 に強制されます。
\var{d}.year が \code{MINYEAR} や \code{MAXUEAR} で、UTC への修正の結果
表現可能な年の境界を越えた場合には、戻り値の \member{tm_year} メンバは
\constant{MINYEAR}-1 または \constant{MAXYEAR}+1 になることがあります。
\end{methoddesc}

\begin{methoddesc}{toordinal}{}
予測的グレゴリオ暦における日付序数を返します。
  \code{self.date().toordinal()} と同じです。
\end{methoddesc}

\begin{methoddesc}{weekday}{}
月曜日を 0、日曜日を 6 として、曜日を整数で返します。
\code{self.date().weekday()} と同じです。
\method{isoweekday()} も参照してください。
\end{methoddesc}

\begin{methoddesc}{isoweekday}{}
月曜日を 1、日曜日を 7 として、曜日を整数で返します。
\code{self.date().isoweekday()} と等価です。
\method{weekday()}、 \method{isocalendar()} も参照してください。
\end{methoddesc}

\begin{methoddesc}{isocalendar}{}
3 要素のタプル (ISO 年、ISO 週番号、ISO 曜日) を返します。
\code{self.date().isocalendar()} と等価です。
\end{methoddesc}

\begin{methoddesc}{isoformat}{\optional{sep}}
日付と時刻を ISO 8601 形式、すなわち
      YYYY-MM-DDTHH:MM:SS.mmmmmm
か、
 \member{microsecond} が 0 の場合には
      YYYY-MM-DDTHH:MM:SS
で表した文字列を返します。
\method{utcoffset()} が \code{None} を返さない場合、
UTC からのオフセットを時間と分を表した (符号付きの) 6 文字からなる 
文字列が追加されます: すなわち、
      YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM
となるか、 \member{microsecond} が ゼロの場合には
      YYYY-MM-DDTHH:MM:SS+HH:MM
となります。
オプションの引数 \var{sep} (デフォルトでは \code{'T'} です) 
は 1 文字のセパレータで、結果の文字列の日付と時刻の間に置かれます。
例えば、

\begin{verbatim}
>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     def utcoffset(self, dt): return timedelta(minutes=-399)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
\end{verbatim}
となります。
\end{methoddesc}

\begin{methoddesc}{__str__}{}
\class{datetime} オブジェクト \var{d} において、
\code{str(\var{d})} は \code{\var{d}.isoformat(' ')} と等価です。
\end{methoddesc}

\begin{methoddesc}{ctime}{}
日付を表す文字列を、例えば
  \code{datetime(2002, 12, 4, 20, 30, 40).ctime() ==
   'Wed Dec  4 20:30:40 2002'}
のようにして返します。
ネイティブの C 関数 \cfunction{ctime()} 
(\function{time.ctime()} はこの関数を呼び出しますが、
\method{datetime.ctime()} は呼び出しません) が C 標準に準拠
しているプラットフォームでは、
  \code{\var{d}.ctime()} は
  \code{time.ctime(time.mktime(d.timetuple()))}
と等価です。
\end{methoddesc}

\begin{methoddesc}{strftime}{format}
明示的な書式化文字列で制御された、日付を表現する文字列を返します。
\method{strftime()} のふるまいについてのセクション~\ref{strftime-behavior}を参照して
ください。
\end{methoddesc}


\subsection{\class{time} オブジェクト \label{datetime-time}}

\class{time} オブジェクトは (ローカルの) 日中時刻を表現します。
この時刻表現は特定の日の影響を受けず、\class{tzinfo} オブジェクト
を介した修正の対象となります。

\begin{classdesc}{time}{hour\optional{, minute\optional{, second\optional{,
                        microsecond\optional{, tzinfo}}}}}
全ての引数はオプションです。\var{tzinfo} は
\code{None} または \class{tzinfo} クラスのサブクラスのインスタンス
にすることができます。残りの引数は整数または長整数で、
以下のような範囲に入ります:

  \begin{itemize}
    \item \code{0 <= \var{hour} < 24}
    \item \code{0 <= \var{minute} < 60}
    \item \code{0 <= \var{second} < 60}
    \item \code{0 <= \var{microsecond} < 1000000}.
  \end{itemize}

引数がこれらの範囲外にある場合、
  \exception{ValueError} が送出されます。 \var{tzinfo}のデフォルト値が
  \constant{None}である以外のデフォルト値は\var{0}です。
\end{classdesc}

以下にクラス属性を示します:

\begin{memberdesc}{min}
表現できる最も古い \class{datetime} で、
  \code{time(0, 0, 0, 0)} です。
  The earliest representable \class{time}, \code{time(0, 0, 0, 0)}.
\end{memberdesc}

\begin{memberdesc}{max}
表現できる最も新しい \class{datetime} で、
  \code{time(23, 59, 59, 999999, tzinfo=None)} です。
\end{memberdesc}

\begin{memberdesc}{resolution}
等しくない \class{datetime} オブジェクト間の最小の差で、 
\code{timedelta(microseconds=1)}
ですが、\class{time} オブジェクト間の四則演算はサポートされて
いないので注意してください。
\end{memberdesc}

以下に (読み出し専用の) インスタンス属性を示します:

\begin{memberdesc}{hour}
\code{range(24)} 内の値です。
\end{memberdesc}

\begin{memberdesc}{minute}
\code{range(60)} 内の値です。
\end{memberdesc}

\begin{memberdesc}{second}
\code{range(60)} 内の値です。
\end{memberdesc}

\begin{memberdesc}{microsecond}
\code{range(1000000)} 内の値です。
\end{memberdesc}

\begin{memberdesc}{tzinfo}
\class{time} コンストラクタに \var{tzinfo} 引数として
与えられたオブジェクトになり、何も渡されなかった場合には \code{None}
になります。
\end{memberdesc}

以下にサポートされている操作を示します:

\begin{itemize}
  \item
    \class{time} と \class{time} の比較では、\var{a} が時刻として
\var{b} よりも前を表す場合に \var{a} は \var{b} よりも小さいと見なされます。
被演算子の片方が naive でもう一方が aware の場合、
\exception{TypeError} が送出されます。両方の被演算子が aware で、
同じ \member{tzinfo} メンバを持つ場合、共通の \member{tzinfo}
メンバは無視され、基本の datetime 間の比較が行われます。
両方の被演算子が aware で異なる \member{tzinfo} メンバを持つ
場合、被演算子はまず (\code{self.utcoffset()} で得られる) UTC 
オフセット で修正されます。
型混合の比較がデフォルトのオブジェクトアドレス比較となってしまう
のを抑止するために、\class{time} オブジェクトが他の型のオブジェクトと
比較された場合、比較演算子が \code{==} または \code{!=}
でないかぎり \exception{TypeError} が送出されます。
後者の場合、それぞれ \constant{False} または \constant{True}
を返します。

  \item
    ハッシュ化、辞書のキーとしての利用

  \item
    効率的な pickle 化

  \item
    ブール演算コンテキストでは、\class{time} オブジェクトは、
分に変換し、\method{utfoffset()} (\code{None} を返した場合には
\code{0}) を差し引いて変換した後の結果がゼロでない場合、かつその
ときに限って真とみなされます。
\end{itemize}

以下にインスタンスメソッドを示します:

\begin{methoddesc}{replace}{\optional{hour\optional{, minute\optional{,
                            second\optional{, microsecond\optional{,
                            tzinfo}}}}}}
キーワード引数で指定したメンバの値を除き、同じ値をもつ \class{time}
オブジェクトを返します。
メンバに対する変換を行わずに aware な datetime オブジェクトから 
naive な \class{time} オブジェクトを生成するために、
\code{tzinfo=None} を指定することもできます。
\end{methoddesc}

\begin{methoddesc}{isoformat}{}
日付と時刻を ISO 8601 形式、すなわち
      HH:MM:SS.mmmmmm
か、
 \member{microsecond} が 0 の場合には
      HH:MM:SS
で表した文字列を返します。
\method{utcoffset()} が \code{None} を返さない場合、
UTC からのオフセットを時間と分を表した (符号付きの) 6 文字からなる 
文字列が追加されます: すなわち、
      HH:MM:SS.mmmmmm+HH:MM
となるか、 \member{microsecond} が 0 の場合には
      HH:MM:SS+HH:MM
となります。
\end{methoddesc}

\begin{methoddesc}{__str__}{}
\class{time} オブジェクト \var{t} において、
\code{str(\var{t})} は \code{\var{t}.isoformat()} と等価です。
\end{methoddesc}

\begin{methoddesc}{strftime}{format}
明示的な書式化文字列で制御された、日付を表現する文字列を返します。
\method{strftime()} のふるまいについてのセクション~\ref{strftime-behavior}を参照して
ください。
\end{methoddesc}

\begin{methoddesc}{utcoffset}{}
\member{tzinfo} が \code{None} の場合、\code{None} を返し、
そうでない場合には \code{\var{self}.tzinfo.utcoffset(None)}
を返します。後者の式が \code{None} か、1 日以下の大きさを持つ
経過時間を表す \class{timedelta} オブジェクトのいずれかを返さない
場合には例外を送出します。
\end{methoddesc}

\begin{methoddesc}{dst}{}
\member{tzinfo} が \code{None} の場合、\code{None} を返し、
そうでない場合には \code{\var{self}.tzinfo.dst(None)}
を返します。後者の式が \code{None} か、1 日以下の大きさを持つ
経過時間を表す \class{timedelta} オブジェクトのいずれかを返さない
場合には例外を送出します。
\end{methoddesc}

\begin{methoddesc}{tzname}{}
\member{tzinfo} が \code{None} の場合、\code{None} を返し、
そうでない場合には \code{\var{self}.tzinfo.tzname(None)}
を返します。後者の式が \code{None} か文字列オブジェクトのいずれか
を返さない場合には例外を送出します。
\end{methoddesc}


\subsection{\class{tzinfo} オブジェクト \label{datetime-tzinfo}}

\class{tzinfo} は抽象基底クラスです。つまり、このクラスは直接
インスタンス化して利用しません。具体的なサブクラスを導出し、
(少なくとも) 利用したい \class{datetime} のメソッドが必要と
する \class{tzinfo} の標準メソッドを実装してやる必要があります。
\module{datetime} モジュールでは、\class{tzinfo} の具体的な
サブクラスは何ら提供していません。

\class{tzinfo} (の具体的なサブクラス) のインスタンスは
\class{datetime} および \class{time} オブジェクトのコンストラクタに
渡すことができます。
後者のオブジェクトでは、データメンバをローカル時刻におけるものとして
見ており、\class{tzinfo} オブジェクトはローカル時刻の UTC からの
オフセット、タイムゾーンの名前、DST オフセットを、渡された
日付および時刻オブジェクトからの相対で示すためのメソッドを
提供します。

pickle 化についての特殊な要求事項: \class{tzinfo} のサブクラスは
引数なしで呼び出すことのできる \method{__init__} メソッドを持たねば
なりません。そうでなければ、pickle 化することはできますがおそらく
 unpickle 化することはできないでしょう。これは技術的な側面からの
要求であり、将来緩和されるかもしれません。

\class{tzinfo} の具体的なサブクラスでは、以下のメソッドを
実装する必要があります。厳密にどのメソッドが必要なのかは、
aware な \module{datetime} オブジェクトがこのサブクラスの
インスタンスをどのように使うかに依存します。不確かならば、
単に全てを実装してください。

\begin{methoddesc}[tzinfo]{utcoffset}{self, dt}
ローカル時間の UTC からのオフセットを、UTC から東向きを正とした分で
返します。ローカル時間が UTC の西側にある場合、この値は負になります。
このメソッドは UTC からのオフセットの総計を返すように意図されている
ので注意してください; 例えば、 \class{tzinfo} オブジェクトが
タイムゾーンと DST 修正の両方を表現する場合、\method{utcoffset()}
はそれらの合計を返さなければなりません。UTC オフセットが未知である
場合、\code{None} を返してください。そうでない場合には、
返される値は -1439 から 1439 の両端を含む値 (1440 = 24*60 ; 
つまり、オフセットの大きさは 1 日より短くなくてはなりません)
が分で指定された \class{timedelta} オブジェクトでなければなりません。
ほとんどの \method{utcoffset()} 実装は、おそらく以下の二つのうちの一つに
似たものになるでしょう:

\begin{verbatim}
    return CONSTANT                 # fixed-offset class
    return CONSTANT + self.dst(dt)  # daylight-aware class
\end{verbatim}

\method{utcoffset()} が \code{None} を返さない場合、
\method{dst()} も \code{None} を返してはなりません。

\method{utcoffset()} のデフォルトの実装は
 \exception{NotImplementedError} を送出します。
\end{methoddesc}

\begin{methoddesc}[tzinfo]{dst}{self, dt}
夏時間 (DST) 修正を、UTC から東向きを正とした分で
返します。DST 情報が未知の場合、\code{None} が返されます。
DST が有効でない場合には \code{timedelta(0)} を返します。
DST が有効の場合、オフセットは \class{timedelta} オブジェクト
で返します (詳細は\method{utcoffset()} を参照してください)。
DST オフセットが利用可能な場合、この値は \method{utcoffset()} 
が返すUTC からのオフセットには既に加算されているため、
DST を個別に取得する必要がない限り \method{dst()} を使って
問い合わせる必要はないので注意してください。
例えば、\method{datetime.timetuple()} は \member{tzinfo} メンバ
の \method{dst()} メソッドを呼んで \member{tm_isdst} フラグが
セットされているかどうか判断し、\method{tzinfo.fromutc()} 
は \method{dst()} タイムゾーンを移動する際に DST による変更
があるかどうかを調べます。

標準および夏時間の両方をモデル化している \class{tzinfo} サブクラスの
インスタンス \var{tz} は以下の式:

      \code{\var{tz}.utcoffset(\var{dt}) - \var{tz}.dst(\var{dt})}

が、\code{\var{dt}.tzinfo == \var{tz}} 全ての \class{datetime} オブジェクト
\var{dt} について常に同じ結果を返さなければならないという点で、
一貫性を持っていなければなりません。
正常に実装された \class{tzinfo} のサブクラスでは、この式は
タイムゾーンにおける "標準オフセット (standard offset)" を表し、
特定の日や時刻の事情ではなく地理的な位置にのみ依存していなくては
なりません。\method{datetime.astimezone()} の実装はこの事実に
依存していますが、違反を検出することができません;
正しく実装するのはプログラマの責任です。\class{tzinfo} の
サブクラスでこれを保証することができない場合、\method{tzinfo.fromutc()} 
の実装をオーバライドして、\method{astimezone()} に関わらず
正しく動作するようにしてもかまいません。

ほとんどの \method{dst()} 実装は、おそらく以下の二つのうちの一つに
似たものになるでしょう:

\begin{verbatim}
    def dst(self):
        # a fixed-offset class:  doesn't account for DST
        return timedelta(0)
\end{verbatim}

  or

\begin{verbatim}
    def dst(self):
        # Code to set dston and dstoff to the time zone's DST
        # transition times based on the input dt.year, and expressed
        # in standard local time.  Then

        if dston <= dt.replace(tzinfo=None) < dstoff:
            return timedelta(hours=1)
        else:
            return timedelta(0)
\end{verbatim}

デフォルトの \method{dst()} 実装は \exception{NotImplementedError}
を送出します。
\end{methoddesc}

\begin{methoddesc}[tzinfo]{tzname}{self, dt}
\class{datetime} オブジェクト \var{dt} に対応するタイムゾーン名
を文字列で返します。
\module{datetime} モジュールでは文字列名について何も定義しておらず、
特に何かを意味するといった要求仕様もまったくありません。
例えば、"GMT"、"UTC"、 "-500"、 "-5:00"、  "EDT"、 "US/Eastern"、
 "America/New York" は全て有効な応答となります。
文字列名が未知の場合には \code{None} を返してください。
\class{tzinfo} のサブクラスでは、
特に、\class{tzinfo}
クラスが夏時間について記述している場合のように、
渡された \var{dt} の特定の値によって異なった名前を返したい
場合があるため、文字列値ではなくメソッドとなっていることに注意してください。

デフォルトの \method{tzname()} 実装は \exception{NotImplementedError}
を送出します。
\end{methoddesc}

以下のメソッドは \class{datetime} や \class{time} オブジェクトにおいて、
同名のメソッドが呼び出された際に応じて呼び出されます。\class{datetime}
オブジェクトは自身を引数としてメソッドに渡し、\class{time} オブジェクトは
引数として \code{None} をメソッドに渡します。従って、\class{tzinfo} の
サブクラスにおけるメソッドは引数 \var{dt} が \code{None} の場合と、
\class{datetime} の場合を受理するように用意しなければなりません。

\code{None} が渡された場合、最良の応答方法を決めるのはクラス設計者次第
です。例えば、このクラスが \class{tzinfo} プロトコルと関係をもたない
ということを表明させたければ、\code{None} が適切です。
標準時のオフセットを見つける他の手段がない場合には、
標準 UTC オフセットを返すために \code{utcoffset(None)}
を使うともっと便利かもしれません。

\class{datetime} オブジェクトが \method{datetime} メソッド
の応答として返された場合、\code{dt.tzinfo} は \var{self}
と同じオブジェクトになります。ユーザが直接 \class{tzinfo} メソッド
を呼び出さないかぎり、\class{tzinfo} メソッドは \code{dt.tzinfo}
と \var{self} が同じであることに依存します。
その結果 \class{tzinfo} メソッドは \var{dt} がローカル時間であると
解釈するので、他のタイムゾーンでのオブジェクトの振る舞いについて
心配する必要がありません。


\begin{methoddesc}[tzinfo]{fromutc}{self, dt}
デフォルトの \class{datetime.astimezone()} 実装で呼び出されます。
\class{datetime.astimezone()} から呼ばれた場合、\code{\var{dt}.tzinfo}
は \var{self} であり、 \var{dt} の日付および時刻データメンバは
UTC 時刻を表しているものとして見えます。\method{fromutc()} 
の目的は、\var{self} のローカル時刻に等しい \class{datetime} オブジェクト
を返すことにより日付と時刻データメンバを修正することにあります。

ほとんどの \class{tzinfo} サブクラスではデフォルトの \method{fromutc()}
実装を問題なく継承できます。デフォルトの実装は、固定オフセットのタイムゾーン
や、標準時と夏時間の両方について記述しているタイムゾーン、そして
DST 移行時刻が年によって異なる場合でさえ、扱えるくらい強力なものです。
デフォルトの \method{fromutc()} 実装が全ての場合に対して正しく
扱うことができないような例は、標準時の (UTCからの) オフセットが
引数として渡された特定の日や時刻に依存するもので、これは政治的な理由に
よって起きることがあります。
デフォルトの \method{astimezone()} や \method{fromutc()} の実装は、
結果が標準時オフセットの変化にまたがる何時間かの中にある場合、
期待通りの結果を生成しないかもしれません。

エラーの場合のためのコードを除き、デフォルトの \method{fromutc()} の
実装は以下のように動作します:

  \begin{verbatim}
  def fromutc(self, dt):
      # raise ValueError error if dt.tzinfo is not self
      dtoff = dt.utcoffset()
      dtdst = dt.dst()
      # raise ValueError if dtoff is None or dtdst is None
      delta = dtoff - dtdst  # this is self's standard offset
      if delta:
          dt += delta   # convert to standard local time
          dtdst = dt.dst()
          # raise ValueError if dtdst is None
      if dtdst:
          return dt + dtdst
      else:
          return dt
  \end{verbatim}
\end{methoddesc}

以下に \class{tzinfo} クラスの使用例を示します:

\verbatiminput{tzinfo-examples.py}

標準時間 (standard time) および夏時間 (daylight time) の両方を
記述している \class{tzinfo} のサブクラスでは、回避不能の難解な問題が年に
2 度あるので注意してください。具体的な例として、東部アメリカ時刻
 (US Eastern, UTC -5000)  を考えます。EDT は 4 月の最初の日曜日
の 1:59 (EST) 以後に開始し、10 月の最後の日曜日の 1:59 (EDT) に
終了します:

\begin{verbatim}
    UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
    EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
    EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM

  start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM

    end  23:MM  0:MM  1:MM  1:MM  2:MM  3:MM
\end{verbatim}

DST の開始の際 ("start" の並び) ローカルの壁時計は 1:59 から
3:00 に飛びます。この日は 2:MM の形式をとる時刻は実際には無意味と
なります。従って、\code{astimezone(Eastern)} は DST が開始する
日には \code{hour == 2} となる結果を返すことはありません。
\method{astimezone()} がこのことを保証するようにするには、
\method{tzinfo.dst()} メソッドは "失われた時間" (東部時刻における
2:MM) が夏時間に存在することを考えなければなりません。

DST が終了する際 ("end" の並び) では、問題はさらに悪化します:
1 時間の間、ローカルの壁時計ではっきりと時刻をいえなくなります:
それは夏時間の最後の 1 時間です。東部時刻では、その日の UTC
での 5:MM に夏時間は終了します。ローカルの壁時計は 1:59 (夏時間)
から 1:00 (標準時) に再び巻き戻されます。ローカルの時刻に
おける 1:MM はあいまいになります。\method{astimezone()}
は二つの UTC 時刻を同じローカルの時刻に対応付けることで
ローカルの時計の振る舞いをまねます。
東部時刻の例では、5:MM および 6:MM の形式をとる UTC 時刻は
両方とも、東部時刻に変換された際に 1:MM に対応づけられます。
\method{astimezone()} がこのことを保証するようにするには、
\method{tzinfo.dst()} は "繰り返された時間" が標準時に存在する
ことを考慮しなければなりません。このことは、例えばタイムゾーンの標準の
ローカルな時刻に DST への切り替え時刻を表現することで簡単に設定する
ことができます。

このようなあいまいさを許容できないアプリケーションは、
ハイブリッドな \class{tzinfo} サブクラスを使って問題を回避しなければ
なりません; UTC や、他のオフセットが固定された \class{tzinfo} の
サブクラス (EST (-5 時間の固定オフセット) のみを表すクラスや、
EDT (-4 時間の固定オフセット) のみを表すクラス) を使う限り、あいまいさは
発生しません。


\subsection{\method{strftime()} の振る舞い\label{strftime-behavior}}

\class{date}、 \class{datetime}、および \class{time}
オブジェクトは全て、明示的な書式化文字列でコントロールして
時刻表現文字列を生成するための \code{strftime(\var{format})} メソッドを
サポートしています。大雑把にいうと、\code{d.strftime(fmt)}
は \refmodule{time} モジュールの \code{time.strftime(fmt, d.timetuple())}
のように動作します。ただし全てのオブジェクトが \method{timetuple()} 
メソッドをサポートしているわけではありません。

\class{time} オブジェクトでは、年、月、日の値がないため、それらの
書式化コードを使うことができません。無理矢理使った場合、
年は \code{1900} に置き換えられ、月と日は \code{0} に置き換え
られます。

\class{date} オブジェクトでは、時、分、秒の値がないため、
それらの書式化コードを使うことができません。無理矢理使った場合、
これらの値は \code{0} に置き換えられます。

naive オブジェクトでは、書式化コード \code{\%z} および \code{\%Z} 
は空文字列に置き換えられます。

aware オブジェクトでは以下のようになります:

\begin{itemize}
\item[\code{\%z}]
\method{utcoffset()} は +HHMM あるいは -HHMM の形式をもった
5 文字の文字列に変換されます。HH は UTC オフセット時間を与える 
2 桁の文字列で、MM は UTC オフセット分を与える 2 桁の文字列です。
例えば、\method{utcoffset()} が \code{timedelta(hours=-3, minutes=-30)}
を返した場合、\code{\%z} は文字列 \code{'-0330'} に置き換わります。

\item[\code{\%Z}]
\method{tzname()} が \code{None} を返した場合、\code{\%Z} は
空文字列に置き換わります。そうでない場合、\code{\%Z} は返された
値に置き換わりますが、これは文字列でなければなりません。
\end{itemize}

Python はプラットフォームの C ライブラリから \function{strftime()}
関数を呼び出し、プラットフォーム間のバリエーションはよくあることなので、
サポートされている書式化コードの全セットはプラットフォーム間で異なります。
Python の \refmodule{time} モジュールのドキュメントでは、C 標準 
(1989 年版) が要求する書式化コードをリストしており、これらのコードは
標準 C 準拠の実装がなされたプラットフォームでは全て動作します。
1999 年版の C 標準では書式化コードが追加されているので注意してください。

\method{strftime()} が正しく動作する年の厳密な範囲はプラットフォーム
間で異なります。プラットフォームに関わらず、1900 年以前の年は
使うことができません。



\subsection{使用例}

\subsubsection{ Datetime オブジェクトをフォーマットされた文字列から生成する}

\class{datetime}クラスは直接フォーマットされた時刻文字列の構文解析をサ
ポートしていません。\function{time.strptime} を使うことによって構文解
析をし、返されるタプルから\class{datetime}オブジェクトを生成することができます。

\begin{verbatim}
>>> s = "2005-12-06T12:13:14"
>>> from datetime import datetime
>>> from time import strptime
>>> datetime(*strptime(s, "%Y-%m-%dT%H:%M:%S")[0:6])
datetime.datetime(2005, 12, 6, 12, 13, 14)
\end{verbatim}

