5.1.3 date オブジェクト

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

クラス date( year, month, day)
全ての引数が必要です。引数は整数でも長整数でもよく、以下の範囲に 入らなければなりません:

範囲を超えた引数を与えた場合、ValueError が送出 されます。

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

today( )
現在のローカルな日付を返します。 date.fromtimestamp(time.time()) と等価です。

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

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

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

min
表現できる最も古い日付で、date(MINYEAR, 1, 1) です。

max
表現できる最も新しい日付で、 date(MAXYEAR, 12, 31) です。

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

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

year
両端値を含む MINYEAR から MAXYEAR までの値です。

month
両端値を含む 1 から 12 までの値です。

day
1 から与えられた月と年における日数までの値です。

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

演算 結果
date2 = date1 + timedelta date2 はから date1 から timedelta.days 日 移動した日付です。 (1)
date2 = date1 - timedelta date2 + timedelta == date1 であるような日付 date2 を計算します。 (2)
timedelta = date1 - date2 (3)
date1 < date2 date1 が時刻として date2 よりも前を表す場合に、 date1date2 よりも小さいと見なされます。 (4)

注釈:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

__str__( )
date オブジェクト d において、 str(d)d.isoformat() と等価です。

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

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

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。