5.1.4 datetime オブジェクト

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

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

クラス datetime( year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])
年、月、および日の引数は必須です。tzinfoNone または tzinfo クラスのサブクラスのインスタンス にすることができます。残りの引数は整数または長整数で、 以下のような範囲に入ります:

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

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

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

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

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

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

fromtimestamp( timestamp[, tz])
time.time() が返すような、POSIX タイムスタンプに 対応するローカルな日付と時刻を返します。 オプションの引数 tzNone であるか、指定されて いない場合、タイムスタンプはプラットフォームのローカルな日付および 時刻に変換され、返される 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 となり、 tzinfoNone となります。

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

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

バージョン 2.5 で 新たに追加 された仕様です。

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

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 datetimedatetime と比較します。 (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-ba および b をまず naive な UTC datetime オブジェクトに変換したかのようにして行います。演算結果は 決してオーバフローを起こさないことを除き、 (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()) と同じになります。

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

被演算子の片方が 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 オブジェクトを返します。 tzinfoNone です。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 におけるローカルな時刻を表すようにします。

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

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

単にタイムゾーンオブジェクト tzdatetime オブジェクト 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( )
tzinfoNone の場合、None を返し、 そうでない場合には self.tzinfo.utcoffset(self) を返します。後者の式が None か、1 日以下の大きさを持つ 経過時間を表す timedelta オブジェクトのいずれかを返さない 場合には例外を送出します。

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

tzname( )
tzinfoNone の場合、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() メソッドに 従って設定されます: tzinfoNonedst()None を返す場合、 tm_isdst-1 に設定されます; そうでない場合、 dst() がゼロでない値を返すと、tm_isdst1 となります; それ以外の場合には tm_isdst0 に設定 されます。

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 が MINYEARMAXUEAR で、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])
日付と時刻を 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() のふるまいについてのセクション 5.1.7を参照して ください。

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