##
6.9.3 `date` オブジェクト

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

class `date`( | year, month, day)

  全ての引数が必要です。引数は整数でも長整数でもよく、以下の範囲に 入らなければなりません:

  - `MINYEAR <= year <= MAXYEAR`
  - `1 <= month <= 12`
  - `1 <= 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 よりも前を表す場合に、 date1 はdate2 よりも小さいと見なされます。 (4)

注釈:

(1)
  date2 は `timedelta.days > 0` の場合進む方向に、 `timedelta.days < 0` の場合戻る方向に移動します。 演算後は、`date2 - date1 == timedelta.days` となります。 `timedelta.seconds` および `timedelta.microseconds` は無視されます。 `date2.year` が `MINYEAR` になってしまったり、 `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(2000, 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()` のふるまいについてのセクションを参照して ください。