##
6.9.4 `datetime` オブジェクト

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

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

class `datetime`( | year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None)

  年、月、および日の引数は必須です。tzinfo は `None` または `tzinfo` クラスのサブクラスのインスタンス にすることができます。残りの引数は整数または長整数で、 以下のような範囲に入ります:

  - `MINYEAR <= year <= MAXYEAR`
  - `1 <= month <= 12`
  - `1 <= day <= 与えられた年と月における日数`
  - `0 <= hour < 24`
  - `0 <= minute < 60`
  - `0 <= second < 60`
  - `0 <= microsecond < 1000000`

  引数がこれらの範囲外にある場合、 `ValueError` が送出されます。

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

`today`( | )

  現在のローカルな `datetime` を `tzinfo` が `None` であるものとして返します。 これは `datetime.fromtimestamp(time.time())` と等価です。 `now()`、 `fromtimestamp()` も参照してください。

`now(tz=None)`( | )

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

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

`utcnow`( | )

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

`fromtimestamp`( | timestamp, tz=None)

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

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

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

`utcfromtimestamp`( | timestamp)

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

`fromordinal`( | ordinal)

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

`combine`( | date, time)

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

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

`min`
  表現できる最も古い `datetime` で、 `datetime(MINYEAR, 1, 1, tzinfo=None)` です。

`max`
  表現できる最も新しい `datetime` で、 `datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)` です。

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

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

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

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

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

`hour`
  `range(24)` 内の値です。

`minute`
  `range(60)` 内の値です。

`second`
  `range(60)` 内の値です。

`microsecond`
  `range(1000000)` 内の値です。

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

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

演算 | 結果
--- | ---
`datetime2 = datetime1 + timedelta` | (1)

`datetime2 = datetime1 - timedelta` | (2)

`timedelta = datetime1 - datetime2` | (3)

`datetime1 < datetime2` | `datetime` を `datetime` と比較します。 (4)

(1)

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

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

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

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

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

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

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

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

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

`date`( | )

  同じ年、月、日の `date` オブジェクトを返します。

`time`( | )

  同じ時、分、秒、マイクロ秒を持つ `time` オブジェクトを返します。 `tzinfo` は `None` です。`timetz()` も参照 してください。

`timetz`( | )

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

`replace`( | year=, month=, day=, hour=, minute=, second=, microsecond=, tzinfo=)

  キーワード引数で指定したメンバの値を除き、同じ値をもつ datetime オブジェクトを返します。 メンバに対する変換を行わずに aware な datetime オブジェクトから naive な datetime オブジェクトを生成するために、 `tzinfo=None` を指定することもできます。

`astimezone`( | tz)

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

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

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

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

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

        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)

`utcoffset`( | )

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

`dst`( | )

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

`tzname`( | )

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

`timetuple`( | )

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

`utctimetuple`( | )

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

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

`toordinal`( | )

  予測的グレゴリ暦における日付序数を返します。 `self.date().toordinal()` と同じです。

`weekday`( | )

  月曜日を 0、日曜日を 6 として、曜日を整数で返します。 `self.date().weekday()` と同じです。 `isoweekday()` も参照してください。

`isoweekday`( | )

  月曜日を 1、日曜日を 7 として、曜日を整数で返します。 `self.date().isoweekday()` と等価です。 `weekday()`、 `isocalendar()` も参照してください。

`isocalendar`( | )

  3 要素のタプル (ISO 年、ISO 週番号、ISO 曜日) を返します。 `self.date().isocalendar()` と等価です。

`isoformat`( | sep='T')

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

      >>> 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'

  となります。

`__str__`( | )

  `datetime` オブジェクト d において、 `str(d)` は `d.isoformat(' ')` と等価です。

`ctime`( | )

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

`strftime`( | format)

  明示的な書式化文字列で制御された、日付を表現する文字列を返します。 `strftime()` のふるまいについてのセクションを参照して ください。