datetime --- 基本的な日付型および時間型

ソースコード: Lib/datetime.py


datetime モジュールは、日付や時刻を操作するためのクラスを提供しています。

日付や時刻に対する算術がサポートされている一方、実装では出力のフォーマットや操作のための効率的な属性の抽出に重点を置いています。

参考

calendar モジュール

汎用のカレンダー関連関数。

time モジュール

時刻へのアクセスと変換。

dateutil パッケージ

拡張タイムゾーンと構文解析サポートのあるサードパーティーライブラリ。

Aware オブジェクトと Naive オブジェクト

日時のオブジェクトは "aware" あるいは "naive" に分類されます。

タイムゾーンや夏時間の情報のような、アルゴリズム的で政治的な適用可能な時間調節に関する知識を持っているため、 aware オブジェクトは他の aware オブジェクトとの相対関係を特定できます。 aware オブジェクトは解釈の余地のない特定の実時刻を表現します。 1

naive オブジェクトには他の日付時刻オブジェクトとの相対関係を把握するのに足る情報が含まれません。あるプログラム内の数字がメートルを表わしているのか、マイルなのか、それとも質量なのかがプログラムによって異なるように、naive オブジェクトが協定世界時 (UTC) なのか、現地時間なのか、それとも他のタイムゾーンなのかはそのプログラムに依存します。Naive オブジェクトはいくつかの現実的な側面を無視してしまうというコストを無視すれば、簡単に理解でき、うまく利用することができます。

aware オブジェクトを必要とするアプリケーションのために、 datetimetime オブジェクトは追加のタイムゾーン情報の属性 tzinfo を持ちます。 tzinfo には抽象クラス tzinfo のサブクラスのインスタンスを設定できます。 これらの tzinfo オブジェクトは UTC 時間からのオフセットやタイムゾーンの名前、夏時間が実施されるかどうかの情報を保持しています。

ただ一つの具象 tzinfo クラスである timezone クラスが datetime モジュールで提供されています。 timezone クラスは単純な UTC からの固定オフセットだけを表わすUTC 自身や北アメリカの EST や EDT タイムゾーンのようなものも表現できます。より深く詳細までタイムゾーンをサポートするかはアプリケーションに依存します。世界中の時刻の調整を決めるルールは合理的というよりかは政治的なもので、頻繁に変わり、UTC を除くと都合のよい基準というものはありません。

定数

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

datetime.MINYEAR

datedatetime オブジェクトで許されている、年を表現する最小の数字です。 MINYEAR1 です。

datetime.MAXYEAR

datedatetime オブジェクトで許されている、年を表現する最大の数字です。 MAXYEAR9999 です。

利用可能なデータ型

class datetime.date

理想的な naive な日付で、これまでもこれからも現在のグレゴリオ暦 (Gregorian calender) が有効であることを仮定しています。 属性は year, month,および day です。

class datetime.time

理想的な時刻で、特定の日から独立しており、毎日が厳密に 24*60*60 秒であると仮定しています。("うるう秒: leap seconds" の概念はありません。) 属性は hour, minute, second, microsecond, および tzinfo です。

class datetime.datetime

日付と時刻を組み合わせたものです。 属性は year, month, day, hour, minute, second, microsecond, および tzinfo です。

class datetime.timedelta

date, time, あるいは datetime クラスの二つのインスタンス間の時間差をマイクロ秒精度で表す経過時間値です。

class datetime.tzinfo

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

class datetime.timezone

tzinfo 抽象基底クラスを UTC からの固定オフセットとして実装するクラスです。

バージョン 3.2 で追加.

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

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

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

共通の特徴

date 型、datetime 型、time 型、timezone 型には共通する特徴があります:

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

  • これらの型のオブジェクトはハッシュ可能であり、辞書のキーとして使えることになります。

  • これらの型のオブジェクトは pickle モジュールを利用して効率的な pickle 化をサポートしています。

オブジェクトが Aware なのか Naive なのかの判断

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

time 型あるいは datetime 型のオブジェクトは aware か naive のどちらかです。

次の条件を両方とも満たす場合、 datetime オブジェクト d は aware です:

  1. d.tzinfoNone でない

  2. d.tzinfo.utcoffset(d)None を返さない

どちらかを満たさない場合は、 d は naive です。

次の条件を両方とも満たす場合、 time オブジェクト t は aware です:

  1. t.tzinfoNone でない

  2. t.tzinfo.utcoffset(None)None を返さない

どちらかを満たさない場合は、 t は naive です。

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

timedelta オブジェクト

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

class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

全ての引数がオプションで、デフォルト値は 0 です。 引数は整数、浮動小数点数でもよく、正でも負でもかまいません。

days, seconds, microseconds だけが内部的に保持されます。 引数は以下のようにして変換されます:

  • 1 ミリ秒は 1000 マイクロ秒に変換されます。

  • 1 分は 60 秒に変換されます。

  • 1 時間は 3600 秒に変換されます。

  • 1 週間は 7 日に変換されます。

さらに、値が一意に表されるように days, seconds, microseconds が以下のように正規化されます

  • 0 <= microseconds < 1000000

  • 0 <= seconds < 3600*24 (一日中の秒数)

  • -999999999 <= days <= 999999999

次の例は、 days, seconds, microseconds に加えて任意の引数がどう "集約" され、最終的に3つの属性に正規化されるかの説明をしています:

>>> from datetime import timedelta
>>> delta = timedelta(
...     days=50,
...     seconds=27,
...     microseconds=10,
...     milliseconds=29000,
...     minutes=5,
...     hours=8,
...     weeks=2
... )
>>> # Only days, seconds, and microseconds remain
>>> delta
datetime.timedelta(days=64, seconds=29156, microseconds=10)

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

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

負の値を正規化すると、最初は混乱するような値になります。例えば:

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

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

timedelta.min

最小の値を表す timedelta オブジェクトで、 timedelta(-999999999) です。

timedelta.max

最大の値を表す timedelta オブジェクトで、 timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999) です。

timedelta.resolution

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

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

インスタンスの属性 (読み出しのみ):

属性

days

両端値を含む -999999999 から 999999999 の間

seconds

両端値を含む 0 から 86399 の間

microseconds

両端値を含む 0 から 999999 の間

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

演算

結果

t1 = t2 + t3

t2t3 の和。演算後、t1-t2 == t3 および t1-t3 == t2 は真になります。(1)

t1 = t2 - t3

t2t3 の差分です。演算後、 t1 == t2 - t3 および t2 == t1 + t3 は真になります。 (1)(6)

t1 = t2 * i または t1 = i * t2

時間差と整数の積。演算後、t1 // i == t2i != 0 であれば真となります。

一般的に、t1 * i == t1 * (i-1) + t1 は真となります。(1)

t1 = t2 * f または t1 = f * t2

時間差と浮動小数点の積。結果は最近接偶数への丸めを利用して最も近い timedelta.resolution の倍数に丸められます。

f = t2 / t3

t23 で除算 (3) したもの。float オブジェクトを返します。

t1 = t2 / f または t1 = t2 / i

時間差を浮動小数点や整数で除したもの。結果は最近接偶数への丸めを利用して最も近い timedelta.resolution の倍数に丸められます。

t1 = t2 // i または t1 = t2 // t3

floor が計算され、余りは (もしあれば) 捨てられます。後者の場合、整数が返されます。(3)

t1 = t2 % t3

剰余が timedelta オブジェクトとして計算されます。(3)

q, r = divmod(t1, t2)

商と剰余が計算されます: q = t1 // t2 (3) と r = t1 % t2 。q は整数で r は timedelta オブジェクトです。

+t1

同じ値を持つ timedelta オブジェクトを返します。(2)

-t1

timedelta(-t1.days, -t1.seconds, -t1.microseconds)、および t1* -1 と同じです。 (1)(4)

abs(t)

t.days >= 0 のときには +t, t.days < 0 のときには -t となります。(2)

str(t)

[D day[s], ][H]H:MM:SS[.UUUUUU] という形式の文字列を返します。t が負の値の場合は D は負の値となります。(5)

repr(t)

timedelta オブジェクトの文字列表現を返します。その文字列は、正規の属性値を持つコンストラクタ呼び出しのコードになっています。

注釈:

  1. この演算は正確ですが、オーバフローするかもしれません。

  2. この演算は正確であり、オーバフローし得ません。

  3. 0 による除算は ZeroDivisionError を送出します。

  4. -timedelta.maxtimedelta オブジェクトで表現することができません。

  5. timedelta オブジェクトの文字列表現は内部表現に類似した形に正規化されます。そのため負の timedelta は少し変な結果になります。例えば:

    >>> timedelta(hours=-5)
    datetime.timedelta(days=-1, seconds=68400)
    >>> print(_)
    -1 day, 19:00:00
    
  6. t3 が timedelta.max のときを除けば、式 t2 - t3 は常に、式 t2 + (-t3) と同等です。t3 が timedelta.max の場合、前者の式は結果の値が出ますが、後者はオーバーフローを起こします。

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

バージョン 3.2 で変更: timedelta オブジェクトの別の timedelta オブジェクトによる、切り捨ての割り算と真の値の割り算、および剰余演算子と divmod() 関数がサポートされるようになりました。 timedelta オブジェクトと float オブジェクトの真の値の割り算と掛け算がサポートされるようになりました。

timedelta オブジェクトどうしの比較が、注意書き付きでサポートされました。

== および != の比較は、比較されているオブジェクトの型が何であれ、 常に bool を返します:

>>> from datetime import timedelta
>>> delta1 = timedelta(seconds=57)
>>> delta2 = timedelta(hours=25, seconds=2)
>>> delta2 != delta1
True
>>> delta2 == 5
False

(< and > などの) それ以外の全ての比較で、 timedelta オブジェクトを異なる型のオブジェクトと比較したときは TypeError が送出されます:

>>> delta2 > delta1
True
>>> delta2 > 5
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '>' not supported between instances of 'datetime.timedelta' and 'int'

ブール演算コンテキストでは、 timedelta オブジェクトは timedelta(0) に等しくない場合かつそのときに限り真となります。

インスタンスメソッド:

timedelta.total_seconds()

この期間に含まれるトータルの秒数を返します。td / timedelta(seconds=1) と等価です。 秒以外の期間の単位では、直接に除算する形式 (例えば td / timedelta(microseconds=1)) が使われます。

非常に長い期間 (多くのプラットフォームでは270年以上) については、このメソッドはマイクロ秒の精度を失うことがあることに注意してください。

バージョン 3.2 で追加.

使用例: timedelta

正規化の追加の例です:

>>> # Components of another_year add up to exactly 365 days
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0

timedelta の計算の例です:

>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> ten_years = 10 * year
>>> ten_years
datetime.timedelta(days=3650)
>>> ten_years.days // 365
10
>>> nine_years = ten_years - year
>>> nine_years
datetime.timedelta(days=3285)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)

date オブジェクト

date オブジェクトは、両方向に無期限に拡張された現在のグレゴリオ暦という理想化された暦の日付 (年月日) を表します。

1 年 1 月 1 日は日番号 1、1 年 1 月 2 日は日番号 2 と呼ばれ、他も同様です。 2

class datetime.date(year, month, day)

全ての引数が必須です。 引数は整数で、次の範囲に収まっていなければなりません:

  • MINYEAR <= year <= MAXYEAR

  • 1 <= month <= 12

  • 1 <= day <= 指定された月と年における日数

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

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

classmethod date.today()

現在のローカルな日付を返します。

date.fromtimestamp(time.time()) と等価です。

classmethod date.fromtimestamp(timestamp)

time.time() で返されるような POSIX タイムスタンプに対応するローカルな日付を返します。

timestamp がプラットフォームの C 関数 localtime() がサポートする値の範囲から外れていた場合、 OverflowError を送出するかもしれません。また localtime() 呼び出しが失敗した場合には OSError を送出するかもしれません。この範囲は通常は 1970 年から 2038 年までに制限されています。タイムスタンプの表記にうるう秒を含める非 POSIX なシステムでは、うるう秒は fromtimestamp() では無視されます。

バージョン 3.3 で変更: timestamp がプラットフォームの C 関数 localtime() のサポートする値の範囲から外れていた場合、 ValueError ではなく OverflowError を送出するようになりました。 localtime() の呼び出し失敗で ValueError ではなく OSError を送出するようになりました。

classmethod date.fromordinal(ordinal)

先発グレゴリオ暦による序数に対応する日付を返します。 1 年 1 月 1 日が序数 1 となります。

1 <= ordinal <= date.max.toordinal() でない場合、 ValueError が送出されます。 任意の日付 d に対し、 date.fromordinal(d.toordinal()) == d となります。

classmethod date.fromisoformat(date_string)

YYYY-MM-DD という形式で与えられた date_string に対応する date を返します

>>> from datetime import date
>>> date.fromisoformat('2019-12-04')
datetime.date(2019, 12, 4)

この関数は date.isoformat() の逆関数です。 YYYY-MM-DD という形式のみをサポートしています。

バージョン 3.7 で追加.

classmethod date.fromisocalendar(year, week, day)

年月日で指定された ISO 暦の日付に対応する date を返します。 この関数は date.isocalendar() 関数の逆関数です。

バージョン 3.8 で追加.

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

date.min

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

date.max

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

date.resolution

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

インスタンスの属性 (読み出しのみ):

date.year

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

date.month

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

date.day

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

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

演算

結果

date2 = date1 + timedelta

date2date1 から timedelta.days 日だけ移動した日付です。(1)

date2 = date1 - timedelta

date2 + timedelta == date1 であるような日付 date2 を計算します。(2)

timedelta = date1 - date2

(3)

date1 < date2

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

注釈:

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

  2. timedelta.secondstimedelta.microseconds は無視されます。

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

  4. 言い換えると、 date1 < date2date1.toordinal() < date2.toordinal() と同等です。 日付の比較は、比較相手が date オブジェクトでない場合には、 TypeError を送出します。 ただし、 比較相手に timetuple() 属性がある場合は、 NotImplemented が代わりに送出されます。 このフックによって、他の種類の日付オブジェクトに、違う型どうしの比較処理を実装できる可能性が生まれます。 相手が timetuple() 属性を持っていない場合に date と違う型のオブジェクトと比較すると、 == または != の比較でない限り TypeError が送出されます。 後者の場合では、それぞれ False および True が返されます。

ブール演算コンテキストでは、全ての time オブジェクトは真とみなされます。

インスタンスメソッド:

date.replace(year=self.year, month=self.month, day=self.day)

キーワード引数で指定されたパラメータが置き換えられることを除き、同じ値を持つ date オブジェクトを返します。

以下はプログラム例です:

>>> from datetime import date
>>> d = date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)
date.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(), yday, -1))

ここで、 yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 は本年の 1 月 1 日を 1 としたときの日付番号です。

date.toordinal()

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

date.weekday()

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

date.isoweekday()

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

date.isocalendar()

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

ISO 暦はグレゴリオ暦の変種として広く用いられています。 3

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

例えば、2004 年は木曜日から始まるため、ISO 年の最初の週は 2003 年 12 月 29 日、月曜日から始まり、2004 年 1 月 4 日、日曜日に終わります

>>> from datetime import date
>>> date(2003, 12, 29).isocalendar()
(2004, 1, 1)
>>> date(2004, 1, 4).isocalendar()
(2004, 1, 7)
date.isoformat()

日付を ISO 8601 形式の YYYY-MM-DD で表した文字列を返します:

>>> from datetime import date
>>> date(2002, 12, 4).isoformat()
'2002-12-04'

この関数は date.fromisoformat() の逆関数です。

date.__str__()

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

date.ctime()

日付を表す文字列を返します:

>>> from datetime import date
>>> 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()))

と等価です。

date.strftime(format)

明示的な書式文字列で制御された、日付を表現する文字列を返します。 時間、分、秒を表す書式化コードは値 0 になります。完全な書式化ディレクティブのリストについては strftime() と strptime() の振る舞い を参照してください。

date.__format__(format)

date.strftime() と等価です。これにより、 str.format() の使用時に date の書式文字列を指定できます。書式化コードの完全なリストについては strftime() と strptime() の振る舞い を参照してください。

使用例: date

イベントまでの日数を数える例を示します:

>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == date.fromtimestamp(time.time())
True
>>> my_birthday = date(today.year, 6, 24)
>>> if my_birthday < today:
...     my_birthday = my_birthday.replace(year=today.year + 1)
>>> my_birthday
datetime.date(2008, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
202

さらなる date を使う例:

>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)

>>> # Methods related to formatting string output
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> d.ctime()
'Mon Mar 11 00:00:00 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'

>>> # Methods for to extracting 'components' under different calendars
>>> t = d.timetuple()
>>> for i in t:     
...     print(i)
2002                # year
3                   # month
11                  # day
0
0
0
0                   # weekday (0 = Monday)
70                  # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic:    
...     print(i)
2002                # ISO year
11                  # ISO week number
1                   # ISO day number ( 1 = Monday )

>>> # A date object is immutable; all operations produce a new object
>>> d.replace(year=2005)
datetime.date(2005, 3, 11)

datetime オブジェクト

datetime オブジェクトは date オブジェクトおよび time オブジェクトの全ての情報が入っている単一のオブジェクトです。

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

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

class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

year, month, day 引数は必須です。 tzinfoNone または tzinfo サブクラスのインスタンスです。 残りの引数は次の範囲の整数でなければなりません:

  • MINYEAR <= year <= MAXYEAR,

  • 1 <= month <= 12,

  • 1 <= day <= 指定された月と年における日数,

  • 0 <= hour < 24,

  • 0 <= minute < 60,

  • 0 <= second < 60,

  • 0 <= microsecond < 1000000,

  • fold in [0, 1].

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

バージョン 3.6 で追加: fold 引数が追加されました。

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

classmethod datetime.today()

tzinfoNone にして、現在のローカルな日時を返します。

次と等価です:

datetime.fromtimestamp(time.time())

now(), fromtimestamp() も参照してください。

このメソッドの機能は now() と等価ですが、 tz 引数はありません。

classmethod datetime.now(tz=None)

現在のローカルな日時を返します。

If optional argument tz is None or not specified, this is like today(), but, if possible, supplies more precision than can be gotten from going through a time.time() timestamp (for example, this may be possible on platforms supplying the C gettimeofday() function).

If tz is not None, it must be an instance of a tzinfo subclass, and the current date and time are converted to tz’s time zone.

This function is preferred over today() and utcnow().

classmethod datetime.utcnow()

Return the current UTC date and time, with tzinfo None.

This is like now(), but returns the current UTC date and time, as a naive datetime object. An aware current UTC datetime can be obtained by calling datetime.now(timezone.utc). See also now().

警告

Because naive datetime objects are treated by many datetime methods as local times, it is preferred to use aware datetimes to represent times in UTC. As such, the recommended way to create an object representing the current time in UTC by calling datetime.now(timezone.utc).

classmethod datetime.fromtimestamp(timestamp, tz=None)

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

If tz is not None, it must be an instance of a tzinfo subclass, and the timestamp is converted to tz’s time zone.

fromtimestamp() may raise OverflowError, if the timestamp is out of the range of values supported by the platform C localtime() or gmtime() functions, and OSError on localtime() or gmtime() failure. It's common for this to be restricted to years in 1970 through 2038. Note that on non-POSIX systems that include leap seconds in their notion of a timestamp, leap seconds are ignored by fromtimestamp(), and then it's possible to have two timestamps differing by a second that yield identical datetime objects. This method is preferred over utcfromtimestamp().

バージョン 3.3 で変更: timestamp がプラットフォームの C 関数 localtime() もしくは gmtime() のサポートする値の範囲から外れていた場合、 ValueError ではなく OverflowError を送出するようになりました。 localtime() もしくは gmtime() の呼び出し失敗で ValueError ではなく OSError を送出するようになりました。

バージョン 3.6 で変更: fromtimestamp()fold を1にしてインスタンスを返します。

classmethod datetime.utcfromtimestamp(timestamp)

Return the UTC datetime corresponding to the POSIX timestamp, with tzinfo None. (The resulting object is naive.)

This may raise OverflowError, if the timestamp is out of the range of values supported by the platform C gmtime() function, and OSError on gmtime() failure. It's common for this to be restricted to years in 1970 through 2038.

aware な datetime オブジェクトを得るには fromtimestamp() を呼んでください:

datetime.fromtimestamp(timestamp, timezone.utc)

POSIX 互換プラットフォームでは、これは以下の表現と等価です:

datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)

後者を除き、式は常に年の全範囲 (MINYEAR から MAXYEAR を含みます) をサポートします。

警告

Because naive datetime objects are treated by many datetime methods as local times, it is preferred to use aware datetimes to represent times in UTC. As such, the recommended way to create an object representing a specific timestamp in UTC by calling datetime.fromtimestamp(timestamp, tz=timezone.utc).

バージョン 3.3 で変更: timestamp がプラットフォームの C 関数 gmtime() のサポートする値の範囲から外れていた場合、 ValueError ではなく OverflowError を送出するようになりました。 gmtime() の呼び出し失敗で ValueError ではなく OSError を送出するようになりました。

classmethod datetime.fromordinal(ordinal)

Return the datetime corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1. ValueError is raised unless 1 <= ordinal <= datetime.max.toordinal(). The hour, minute, second and microsecond of the result are all 0, and tzinfo is None.

classmethod datetime.combine(date, time, tzinfo=self.tzinfo)

Return a new datetime object whose date components are equal to the given date object's, and whose time components are equal to the given time object's. If the tzinfo argument is provided, its value is used to set the tzinfo attribute of the result, otherwise the tzinfo attribute of the time argument is used.

For any datetime object d, d == datetime.combine(d.date(), d.time(), d.tzinfo). If date is a datetime object, its time components and tzinfo attributes are ignored.

バージョン 3.6 で変更: tzinfo 引数が追加されました。

classmethod datetime.fromisoformat(date_string)

Return a datetime corresponding to a date_string in one of the formats emitted by date.isoformat() and datetime.isoformat().

Specifically, this function supports strings in the format:

YYYY-MM-DD[*HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]]

where * can match any single character.

ご用心

This does not support parsing arbitrary ISO 8601 strings - it is only intended as the inverse operation of datetime.isoformat(). A more full-featured ISO 8601 parser, dateutil.parser.isoparse is available in the third-party package dateutil. This does not support parsing arbitrary ISO 8601 strings - it is only intended as the inverse operation of datetime.isoformat().

例:

>>> from datetime import datetime
>>> datetime.fromisoformat('2011-11-04')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('2011-11-04T00:05:23')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')   
datetime.datetime(2011, 11, 4, 0, 5, 23,
    tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

バージョン 3.7 で追加.

classmethod datetime.fromisocalendar(year, week, day)

Return a datetime corresponding to the ISO calendar date specified by year, week and day. The non-date components of the datetime are populated with their normal default values. This is the inverse of the function datetime.isocalendar().

バージョン 3.8 で追加.

classmethod datetime.strptime(date_string, format)

Return a datetime corresponding to date_string, parsed according to format.

これは次と等価です:

datetime(*(time.strptime(date_string, format)[0:6]))

ValueError is raised if the date_string and format can't be parsed by time.strptime() or if it returns a value which isn't a time tuple. For a complete list of formatting directives, see strftime() と strptime() の振る舞い.

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

datetime.min

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

datetime.max

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

datetime.resolution

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

インスタンスの属性 (読み出しのみ):

datetime.year

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

datetime.month

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

datetime.day

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

datetime.hour

in range(24) を満たします。。

datetime.minute

in range(60) を満たします。

datetime.second

in range(60) を満たします。

datetime.microsecond

in range(1000000) を満たします。

datetime.tzinfo

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

datetime.fold

In [0, 1]. Used to disambiguate wall times during a repeated interval. (A repeated interval occurs when clocks are rolled back at the end of daylight saving time or when the UTC offset for the current zone is decreased for political reasons.) The value 0 (1) represents the earlier (later) of the two moments with the same wall time representation.

バージョン 3.6 で追加.

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

演算

結果

datetime2 = datetime1 + timedelta

(1)

datetime2 = datetime1 - timedelta

(2)

timedelta = datetime1 - datetime2

(3)

datetime1 < datetime2

datetimedatetime と比較します。 (4)

  1. datetime2 is a duration of timedelta removed from datetime1, moving forward in time if timedelta.days > 0, or backward if timedelta.days < 0. The result has the same tzinfo attribute as the input datetime, and datetime2 - datetime1 == timedelta after. OverflowError is raised if datetime2.year would be smaller than MINYEAR or larger than MAXYEAR. Note that no time zone adjustments are done even if the input is an aware object.

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

  3. Subtraction of a datetime from a datetime is defined only if both operands are naive, or if both are aware. If one is aware and the other is naive, TypeError is raised.

    If both are naive, or both are aware and have the same tzinfo attribute, the tzinfo attributes are ignored, and the result is a timedelta object t such that datetime2 + t == datetime1. No time zone adjustments are done in this case.

    If both are aware and have different tzinfo attributes, a-b acts as if a and b were first converted to naive UTC datetimes first. The result is (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()) except that the implementation never overflows.

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

    If one comparand is naive and the other is aware, TypeError is raised if an order comparison is attempted. For equality comparisons, naive instances are never equal to aware instances.

    If both comparands are aware, and have the same tzinfo attribute, the common tzinfo attribute is ignored and the base datetimes are compared. If both comparands are aware and have different tzinfo attributes, the comparands are first adjusted by subtracting their UTC offsets (obtained from self.utcoffset()).

    バージョン 3.3 で変更: Equality comparisons between aware and naive datetime instances don't raise TypeError.

    注釈

    In order to stop comparison from falling back to the default scheme of comparing object addresses, datetime comparison normally raises TypeError if the other comparand isn't also a datetime object. However, NotImplemented is returned instead if the other comparand has a timetuple() attribute. This hook gives other kinds of date objects a chance at implementing mixed-type comparison. If not, when a datetime object is compared to an object of a different type, TypeError is raised unless the comparison is == or !=. The latter cases return False or True, respectively.

インスタンスメソッド:

datetime.date()

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

datetime.time()

Return time object with same hour, minute, second, microsecond and fold. tzinfo is None. See also method timetz().

バージョン 3.6 で変更: 値 foldは返される time オブジェクトにコピーされます。

datetime.timetz()

Return time object with same hour, minute, second, microsecond, fold, and tzinfo attributes. See also method time().

バージョン 3.6 で変更: 値 foldは返される time オブジェクトにコピーされます。

datetime.replace(year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, * fold=0)

Return a datetime with the same attributes, except for those attributes given new values by whichever keyword arguments are specified. Note that tzinfo=None can be specified to create a naive datetime from an aware datetime with no conversion of date and time data.

バージョン 3.6 で追加: fold 引数が追加されました。

datetime.astimezone(tz=None)

tz を新たに tzinfo 属性 として持つ datetime オブジェクトを返します。 日付および時刻データを調整して、返り値が self と同じ UTC 時刻を持ち、 tz におけるローカルな時刻を表すようにします。

If provided, tz must be an instance of a tzinfo subclass, and its utcoffset() and dst() methods must not return None. If self is naive, it is presumed to represent time in the system timezone.

If called without arguments (or with tz=None) the system local timezone is assumed for the target timezone. The .tzinfo attribute of the converted datetime instance will be set to an instance of timezone with the zone name and offset obtained from the OS.

self.tzinfotz の場合、 self.astimezone(tz)self に等しくなります。つまり、date および time に対する調整は行われません。そうでない場合、結果はタイムゾーン tz におけるローカル時刻で、 self と同じ UTC 時刻を表すようになります。これは、astz = dt.astimezone(tz) とした後、 astz - astz.utcoffset() は通常 dt - dt.utcoffset() と同じ date および time を持つことを示します。

If you merely want to attach a time zone object tz to a datetime dt without adjustment of date and time data, use dt.replace(tzinfo=tz). If you merely want to remove the time zone object from an aware datetime dt without conversion of date and time data, use 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)

バージョン 3.3 で変更: tz が省略可能になりました。

バージョン 3.6 で変更: datetime.datetime.astimezone() メソッドを naive なインスタンスに対して呼び出せるようになりました。これは、システムのローカルな時間を表現していると想定されます。

datetime.utcoffset()

If tzinfo is None, returns None, else returns self.tzinfo.utcoffset(self), and raises an exception if the latter doesn't return None or a timedelta object with magnitude less than one day.

バージョン 3.7 で変更: The UTC offset is not restricted to a whole number of minutes.

datetime.dst()

If tzinfo is None, returns None, else returns self.tzinfo.dst(self), and raises an exception if the latter doesn't return None or a timedelta object with magnitude less than one day.

バージョン 3.7 で変更: The DST offset is not restricted to a whole number of minutes.

datetime.tzname()

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

datetime.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(), yday, dst))

where yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 is the day number within the current year starting with 1 for January 1st. The tm_isdst flag of the result is set according to the dst() method: tzinfo is None or dst() returns None, tm_isdst is set to -1; else if dst() returns a non-zero value, tm_isdst is set to 1; else tm_isdst is set to 0.

datetime.utctimetuple()

If datetime instance d is naive, this is the same as d.timetuple() except that tm_isdst is forced to 0 regardless of what d.dst() returns. DST is never in effect for a UTC time.

If d is aware, d is normalized to UTC time, by subtracting d.utcoffset(), and a time.struct_time for the normalized time is returned. tm_isdst is forced to 0. Note that an OverflowError may be raised if d.year was MINYEAR or MAXYEAR and UTC adjustment spills over a year boundary.

警告

Because naive datetime objects are treated by many datetime methods as local times, it is preferred to use aware datetimes to represent times in UTC; as a result, using utcfromtimetuple may give misleading results. If you have a naive datetime representing UTC, use datetime.replace(tzinfo=timezone.utc) to make it aware, at which point you can use datetime.timetuple().

datetime.toordinal()

Return the proleptic Gregorian ordinal of the date. The same as self.date().toordinal().

datetime.timestamp()

Return POSIX timestamp corresponding to the datetime instance. The return value is a float similar to that returned by time.time().

Naive datetime instances are assumed to represent local time and this method relies on the platform C mktime() function to perform the conversion. Since datetime supports wider range of values than mktime() on many platforms, this method may raise OverflowError for times far in the past or far in the future.

aware な datetime インスタンスに対しては以下のように返り値が計算されます:

(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()

バージョン 3.3 で追加.

バージョン 3.6 で変更: The timestamp() method uses the fold attribute to disambiguate the times during a repeated interval.

注釈

There is no method to obtain the POSIX timestamp directly from a naive datetime instance representing UTC time. If your application uses this convention and your system timezone is not set to UTC, you can obtain the POSIX timestamp by supplying tzinfo=timezone.utc:

timestamp = dt.replace(tzinfo=timezone.utc).timestamp()

もしくは直接タイムスタンプを計算することもできます:

timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)
datetime.weekday()

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

datetime.isoweekday()

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

datetime.isocalendar()

Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The same as self.date().isocalendar().

datetime.isoformat(sep='T', timespec='auto')

Return a string representing the date and time in ISO 8601 format:

If utcoffset() does not return None, a string is appended, giving the UTC offset:

  • YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], if microsecond is not 0

  • YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]], if microsecond is 0

例:

>>> from datetime import datetime, timezone
>>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
'2019-05-18T15:17:08.132263'
>>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()
'2019-05-18T15:17:00+00:00'

The optional argument sep (default 'T') is a one-character separator, placed between the date and time portions of the result. For example:

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     """A time zone with an arbitrary, constant -06:39 offset."""
...     def utcoffset(self, dt):
...         return timedelta(hours=-6, minutes=-39)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
>>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
'2009-11-27T00:00:00.000100-06:39'

オプション引数 timespec は、含める追加の時間の要素の数を指定します(デフォルトでは 'auto' です)。以下の内一つを指定してください。

  • 'auto': microsecond が0である場合 'seconds' と等しく、そうでない場合は 'microseconds' と等しくなります。

  • 'hours': Include the hour in the two-digit HH format.

  • 'minutes': Include hour and minute in HH:MM format.

  • 'seconds': Include hour, minute, and second in HH:MM:SS format.

  • 'milliseconds': Include full time, but truncate fractional second part to milliseconds. HH:MM:SS.sss format.

  • 'microseconds': Include full time in HH:MM:SS.ffffff format.

注釈

除外された要素は丸め込みではなく、切り捨てされます。

ValueError will be raised on an invalid timespec argument:

>>> from datetime import datetime
>>> datetime.now().isoformat(timespec='minutes')   
'2002-12-25T00:00'
>>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)
>>> dt.isoformat(timespec='microseconds')
'2015-01-01T12:30:59.000000'

バージョン 3.6 で追加: timespec 引数が追加されました。

datetime.__str__()

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

datetime.ctime()

Return a string representing the date and time:

>>> from datetime import datetime
>>> datetime(2002, 12, 4, 20, 30, 40).ctime()
'Wed Dec  4 20:30:40 2002'

The output string will not include time zone information, regardless of whether the input is aware or naive.

ネイティブの C 関数 ctime() (time.ctime() はこの関数を呼び出しますが、 date.ctime() は呼び出しません) が C 標準に準拠しているプラットフォームでは、 d.ctime()

time.ctime(time.mktime(d.timetuple()))

on platforms where the native C ctime() function (which time.ctime() invokes, but which datetime.ctime() does not invoke) conforms to the C standard.

datetime.strftime(format)

Return a string representing the date and time, controlled by an explicit format string. For a complete list of formatting directives, see strftime() と strptime() の振る舞い.

datetime.__format__(format)

Same as datetime.strftime(). This makes it possible to specify a format string for a datetime object in formatted string literals and when using str.format(). For a complete list of formatting directives, see strftime() と strptime() の振る舞い.

Examples of Usage: datetime

Examples of working with datetime objects:

>>> from datetime import datetime, date, time, timezone

>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)

>>> # Using datetime.now()
>>> datetime.now()   
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> datetime.now(timezone.utc)   
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)

>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)

>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt:   
...     print(it)
...
2006    # year
11      # month
21      # day
16      # hour
30      # minute
0       # second
1       # weekday (0 = Monday)
325     # number of days since 1st January
-1      # dst - method tzinfo.dst() returned None

>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic:   
...     print(it)
...
2006    # ISO year
47      # ISO week
2       # ISO weekday

>>> # Formatting a datetime
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 04:30PM'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'

The example below defines a tzinfo subclass capturing time zone information for Kabul, Afghanistan, which used +4 UTC until 1945 and then +4:30 UTC thereafter:

from datetime import timedelta, datetime, tzinfo, timezone

class KabulTz(tzinfo):
    # Kabul used +4 until 1945, when they moved to +4:30
    UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)

    def utcoffset(self, dt):
        if dt.year < 1945:
            return timedelta(hours=4)
        elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
            # An ambiguous ("imaginary") half-hour range representing
            # a 'fold' in time due to the shift from +4 to +4:30.
            # If dt falls in the imaginary range, use fold to decide how
            # to resolve. See PEP495.
            return timedelta(hours=4, minutes=(30 if dt.fold else 0))
        else:
            return timedelta(hours=4, minutes=30)

    def fromutc(self, dt):
        # Follow same validations as in datetime.tzinfo
        if not isinstance(dt, datetime):
            raise TypeError("fromutc() requires a datetime argument")
        if dt.tzinfo is not self:
            raise ValueError("dt.tzinfo is not self")

        # A custom implementation is required for fromutc as
        # the input to this function is a datetime with utc values
        # but with a tzinfo set to self.
        # See datetime.astimezone or fromtimestamp.
        if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
            return dt + timedelta(hours=4, minutes=30)
        else:
            return dt + timedelta(hours=4)

    def dst(self, dt):
        # Kabul does not observe daylight saving time.
        return timedelta(0)

    def tzname(self, dt):
        if dt >= self.UTC_MOVE_DATE:
            return "+04:30"
        return "+04"

Usage of KabulTz from above:

>>> tz1 = KabulTz()

>>> # Datetime before the change
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00

>>> # Datetime after the change
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00

>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2 == dt3
True

time オブジェクト

A time object represents a (local) time of day, independent of any particular day, and subject to adjustment via a tzinfo object.

class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

All arguments are optional. tzinfo may be None, or an instance of a tzinfo subclass. The remaining arguments must be integers in the following ranges:

  • 0 <= hour < 24,

  • 0 <= minute < 60,

  • 0 <= second < 60,

  • 0 <= microsecond < 1000000,

  • fold in [0, 1].

If an argument outside those ranges is given, ValueError is raised. All default to 0 except tzinfo, which defaults to None.

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

time.min

表現できる最も古い time で、 time(0, 0, 0, 0) です。

time.max

表現できる最も新しい time で、 time(23, 59, 59, 999999) です。

time.resolution

等しくない time オブジェクト間の最小の差で、 timedelta(microseconds=1) ですが, time オブジェクト間の四則演算はサポートされていないので注意してください。

インスタンスの属性 (読み出しのみ):

time.hour

in range(24) を満たします。。

time.minute

in range(60) を満たします。

time.second

in range(60) を満たします。

time.microsecond

in range(1000000) を満たします。

time.tzinfo

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

time.fold

In [0, 1]. Used to disambiguate wall times during a repeated interval. (A repeated interval occurs when clocks are rolled back at the end of daylight saving time or when the UTC offset for the current zone is decreased for political reasons.) The value 0 (1) represents the earlier (later) of the two moments with the same wall time representation.

バージョン 3.6 で追加.

time objects support comparison of time to time, where a is considered less than b when a precedes b in time. If one comparand is naive and the other is aware, TypeError is raised if an order comparison is attempted. For equality comparisons, naive instances are never equal to aware instances.

If both comparands are aware, and have the same tzinfo attribute, the common tzinfo attribute is ignored and the base times are compared. If both comparands are aware and have different tzinfo attributes, the comparands are first adjusted by subtracting their UTC offsets (obtained from self.utcoffset()). In order to stop mixed-type comparisons from falling back to the default comparison by object address, when a time object is compared to an object of a different type, TypeError is raised unless the comparison is == or !=. The latter cases return False or True, respectively.

バージョン 3.3 で変更: Equality comparisons between aware and naive time instances don't raise TypeError.

In Boolean contexts, a time object is always considered to be true.

バージョン 3.5 で変更: Before Python 3.5, a time object was considered to be false if it represented midnight in UTC. This behavior was considered obscure and error-prone and has been removed in Python 3.5. See bpo-13936 for full details.

Other constructor:

classmethod time.fromisoformat(time_string)

Return a time corresponding to a time_string in one of the formats emitted by time.isoformat(). Specifically, this function supports strings in the format:

HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]

ご用心

This does not support parsing arbitrary ISO 8601 strings. It is only intended as the inverse operation of time.isoformat().

例:

>>> from datetime import time
>>> time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('04:23:01.000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01+04:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

バージョン 3.7 で追加.

インスタンスメソッド:

time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, * fold=0)

Return a time with the same value, except for those attributes given new values by whichever keyword arguments are specified. Note that tzinfo=None can be specified to create a naive time from an aware time, without conversion of the time data.

バージョン 3.6 で追加: fold 引数が追加されました。

time.isoformat(timespec='auto')

Return a string representing the time in ISO 8601 format, one of:

オプション引数 timespec は、含める追加の時間の要素の数を指定します(デフォルトでは 'auto' です)。以下の内一つを指定してください。

  • 'auto': microsecond が0である場合 'seconds' と等しく、そうでない場合は 'microseconds' と等しくなります。

  • 'hours': Include the hour in the two-digit HH format.

  • 'minutes': Include hour and minute in HH:MM format.

  • 'seconds': Include hour, minute, and second in HH:MM:SS format.

  • 'milliseconds': Include full time, but truncate fractional second part to milliseconds. HH:MM:SS.sss format.

  • 'microseconds': Include full time in HH:MM:SS.ffffff format.

注釈

除外された要素は丸め込みではなく、切り捨てされます。

不正な timespec 引数には ValueError があげられます。

以下はプログラム例です:

>>> from datetime import time
>>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
'12:34'
>>> dt = time(hour=12, minute=34, second=56, microsecond=0)
>>> dt.isoformat(timespec='microseconds')
'12:34:56.000000'
>>> dt.isoformat(timespec='auto')
'12:34:56'

バージョン 3.6 で追加: timespec 引数が追加されました。

time.__str__()

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

time.strftime(format)

Return a string representing the time, controlled by an explicit format string. For a complete list of formatting directives, see strftime() と strptime() の振る舞い.

time.__format__(format)

Same as time.strftime(). This makes it possible to specify a format string for a time object in formatted string literals and when using str.format(). For a complete list of formatting directives, see strftime() と strptime() の振る舞い.

time.utcoffset()

If tzinfo is None, returns None, else returns self.tzinfo.utcoffset(None), and raises an exception if the latter doesn't return None or a timedelta object with magnitude less than one day.

バージョン 3.7 で変更: The UTC offset is not restricted to a whole number of minutes.

time.dst()

If tzinfo is None, returns None, else returns self.tzinfo.dst(None), and raises an exception if the latter doesn't return None, or a timedelta object with magnitude less than one day.

バージョン 3.7 で変更: The DST offset is not restricted to a whole number of minutes.

time.tzname()

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

Examples of Usage: time

Examples of working with a time object:

>>> from datetime import time, tzinfo, timedelta
>>> class TZ1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1)
...     def dst(self, dt):
...         return timedelta(0)
...     def tzname(self,dt):
...         return "+01:00"
...     def  __repr__(self):
...         return f"{self.__class__.__name__}()"
...
>>> t = time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'+01:00'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 +01:00'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'

tzinfo オブジェクト

class datetime.tzinfo

This is an abstract base class, meaning that this class should not be instantiated directly. Define a subclass of tzinfo to capture information about a particular time zone.

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

You need to derive a concrete subclass, and (at least) supply implementations of the standard tzinfo methods needed by the datetime methods you use. The datetime module provides timezone, a simple concrete subclass of tzinfo which can represent timezones with fixed offset from UTC such as UTC itself or North American EST and EDT.

Special requirement for pickling: A tzinfo subclass must have an __init__() method that can be called with no arguments, otherwise it can be pickled but possibly not unpickled again. This is a technical requirement that may be relaxed in the future.

A concrete subclass of tzinfo may need to implement the following methods. Exactly which methods are needed depends on the uses made of aware datetime objects. If in doubt, simply implement all of them.

tzinfo.utcoffset(dt)

Return offset of local time from UTC, as a timedelta object that is positive east of UTC. If local time is west of UTC, this should be negative.

This represents the total offset from UTC; for example, if a tzinfo object represents both time zone and DST adjustments, utcoffset() should return their sum. If the UTC offset isn't known, return None. Else the value returned must be a timedelta object strictly between -timedelta(hours=24) and timedelta(hours=24) (the magnitude of the offset must be less than one day). Most implementations of utcoffset() will probably look like one of these two:

return CONSTANT                 # fixed-offset class
return CONSTANT + self.dst(dt)  # daylight-aware class

utcoffset()None を返さない場合、 dst()None を返してはなりません。

utcoffset() のデフォルトの実装は NotImplementedError を送出します。

バージョン 3.7 で変更: The UTC offset is not restricted to a whole number of minutes.

tzinfo.dst(dt)

Return the daylight saving time (DST) adjustment, as a timedelta object or None if DST information isn't known.

Return timedelta(0) if DST is not in effect. If DST is in effect, return the offset as a timedelta object (see utcoffset() for details). Note that DST offset, if applicable, has already been added to the UTC offset returned by utcoffset(), so there's no need to consult dst() unless you're interested in obtaining DST info separately. For example, datetime.timetuple() calls its tzinfo attribute's dst() method to determine how the tm_isdst flag should be set, and tzinfo.fromutc() calls dst() to account for DST changes when crossing time zones.

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

tz.utcoffset(dt) - tz.dst(dt)

must return the same result for every datetime dt with dt.tzinfo == tz For sane tzinfo subclasses, this expression yields the time zone's "standard offset", which should not depend on the date or the time, but only on geographic location. The implementation of datetime.astimezone() relies on this, but cannot detect violations; it's the programmer's responsibility to ensure it. If a tzinfo subclass cannot guarantee this, it may be able to override the default implementation of tzinfo.fromutc() to work correctly with astimezone() regardless.

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

def dst(self, dt):
    # a fixed-offset class:  doesn't account for DST
    return timedelta(0)

もしくは:

def dst(self, dt):
    # 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.

    if dston <= dt.replace(tzinfo=None) < dstoff:
        return timedelta(hours=1)
    else:
        return timedelta(0)

デフォルトの dst() 実装は NotImplementedError を送出します。

バージョン 3.7 で変更: The DST offset is not restricted to a whole number of minutes.

tzinfo.tzname(dt)

Return the time zone name corresponding to the datetime object dt, as a string. Nothing about string names is defined by the datetime module, and there's no requirement that it mean anything in particular. For example, "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all valid replies. Return None if a string name isn't known. Note that this is a method rather than a fixed string primarily because some tzinfo subclasses will wish to return different names depending on the specific value of dt passed, especially if the tzinfo class is accounting for daylight time.

デフォルトの tzname() 実装は NotImplementedError を送出します。

These methods are called by a datetime or time object, in response to their methods of the same names. A datetime object passes itself as the argument, and a time object passes None as the argument. A tzinfo subclass's methods should therefore be prepared to accept a dt argument of None, or of class datetime.

When None is passed, it's up to the class designer to decide the best response. For example, returning None is appropriate if the class wishes to say that time objects don't participate in the tzinfo protocols. It may be more useful for utcoffset(None) to return the standard UTC offset, as there is no other convention for discovering the standard offset.

When a datetime object is passed in response to a datetime method, dt.tzinfo is the same object as self. tzinfo methods can rely on this, unless user code calls tzinfo methods directly. The intent is that the tzinfo methods interpret dt as being in local time, and not need worry about objects in other timezones.

サブクラスでオーバーライドすると良い、もう 1 つの tzinfo のメソッドがあります:

tzinfo.fromutc(dt)

This is called from the default datetime.astimezone() implementation. When called from that, dt.tzinfo is self, and dt's date and time data are to be viewed as expressing a UTC time. The purpose of fromutc() is to adjust the date and time data, returning an equivalent datetime in self's local time.

Most tzinfo subclasses should be able to inherit the default fromutc() implementation without problems. It's strong enough to handle fixed-offset time zones, and time zones accounting for both standard and daylight time, and the latter even if the DST transition times differ in different years. An example of a time zone the default fromutc() implementation may not handle correctly in all cases is one where the standard offset (from UTC) depends on the specific date and time passed, which can happen for political reasons. The default implementations of astimezone() and fromutc() may not produce the result you want if the result is one of the hours straddling the moment the standard offset changes.

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

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

In the following tzinfo_examples.py file there are some examples of tzinfo classes:

from datetime import tzinfo, timedelta, datetime

ZERO = timedelta(0)
HOUR = timedelta(hours=1)
SECOND = timedelta(seconds=1)

# A class capturing the platform's idea of local time.
# (May result in wrong values on historical times in
#  timezones where UTC offset and/or the DST rules had
#  changed in the past.)
import time as _time

STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
    DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
    DSTOFFSET = STDOFFSET

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

    def fromutc(self, dt):
        assert dt.tzinfo is self
        stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
        args = _time.localtime(stamp)[:6]
        dst_diff = DSTDIFF // SECOND
        # Detect fold
        fold = (args == _time.localtime(stamp - dst_diff))
        return datetime(*args, microsecond=dt.microsecond,
                        tzinfo=self, fold=fold)

    def utcoffset(self, dt):
        if self._isdst(dt):
            return DSTOFFSET
        else:
            return STDOFFSET

    def dst(self, dt):
        if self._isdst(dt):
            return DSTDIFF
        else:
            return ZERO

    def tzname(self, dt):
        return _time.tzname[self._isdst(dt)]

    def _isdst(self, dt):
        tt = (dt.year, dt.month, dt.day,
              dt.hour, dt.minute, dt.second,
              dt.weekday(), 0, 0)
        stamp = _time.mktime(tt)
        tt = _time.localtime(stamp)
        return tt.tm_isdst > 0

Local = LocalTimezone()


# A complete implementation of current DST rules for major US time zones.

def first_sunday_on_or_after(dt):
    days_to_go = 6 - dt.weekday()
    if days_to_go:
        dt += timedelta(days_to_go)
    return dt


# US DST Rules
#
# This is a simplified (i.e., wrong for a few cases) set of rules for US
# DST start and end times. For a complete and up-to-date set of DST rules
# and timezone definitions, visit the Olson Database (or try pytz):
# http://www.twinsun.com/tz/tz-link.htm
# http://sourceforge.net/projects/pytz/ (might not be up-to-date)
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006

def us_dst_range(year):
    # Find start and end times for US DST. For years before 1967, return
    # start = end for no DST.
    if 2006 < year:
        dststart, dstend = DSTSTART_2007, DSTEND_2007
    elif 1986 < year < 2007:
        dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
    elif 1966 < year < 1987:
        dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
    else:
        return (datetime(year, 1, 1), ) * 2

    start = first_sunday_on_or_after(dststart.replace(year=year))
    end = first_sunday_on_or_after(dstend.replace(year=year))
    return start, end


class USTimeZone(tzinfo):

    def __init__(self, hours, reprname, stdname, dstname):
        self.stdoffset = timedelta(hours=hours)
        self.reprname = reprname
        self.stdname = stdname
        self.dstname = dstname

    def __repr__(self):
        return self.reprname

    def tzname(self, dt):
        if self.dst(dt):
            return self.dstname
        else:
            return self.stdname

    def utcoffset(self, dt):
        return self.stdoffset + self.dst(dt)

    def dst(self, dt):
        if dt is None or dt.tzinfo is None:
            # An exception may be sensible here, in one or both cases.
            # It depends on how you want to treat them.  The default
            # fromutc() implementation (called by the default astimezone()
            # implementation) passes a datetime with dt.tzinfo is self.
            return ZERO
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        # Can't compare naive to aware objects, so strip the timezone from
        # dt first.
        dt = dt.replace(tzinfo=None)
        if start + HOUR <= dt < end - HOUR:
            # DST is in effect.
            return HOUR
        if end - HOUR <= dt < end:
            # Fold (an ambiguous hour): use dt.fold to disambiguate.
            return ZERO if dt.fold else HOUR
        if start <= dt < start + HOUR:
            # Gap (a non-existent hour): reverse the fold rule.
            return HOUR if dt.fold else ZERO
        # DST is off.
        return ZERO

    def fromutc(self, dt):
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        start = start.replace(tzinfo=self)
        end = end.replace(tzinfo=self)
        std_time = dt + self.stdoffset
        dst_time = std_time + HOUR
        if end <= dst_time < end + HOUR:
            # Repeated hour
            return std_time.replace(fold=1)
        if std_time < start or dst_time >= end:
            # Standard time
            return std_time
        if start <= std_time < end - HOUR:
            # Daylight saving time
            return dst_time


Eastern  = USTimeZone(-5, "Eastern",  "EST", "EDT")
Central  = USTimeZone(-6, "Central",  "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific  = USTimeZone(-8, "Pacific",  "PST", "PDT")

Note that there are unavoidable subtleties twice per year in a tzinfo subclass accounting for both standard and daylight time, at the DST transition points. For concreteness, consider US Eastern (UTC -0500), where EDT begins the minute after 1:59 (EST) on the second Sunday in March, and ends the minute after 1:59 (EDT) on the first Sunday in November:

  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

When DST starts (the "start" line), the local wall clock leaps from 1:59 to 3:00. A wall time of the form 2:MM doesn't really make sense on that day, so astimezone(Eastern) won't deliver a result with hour == 2 on the day DST begins. For example, at the Spring forward transition of 2016, we get:

>>> from datetime import datetime, timezone
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname())
...
05:00:00 UTC = 00:00:00 EST
06:00:00 UTC = 01:00:00 EST
07:00:00 UTC = 03:00:00 EDT
08:00:00 UTC = 04:00:00 EDT

When DST ends (the "end" line), there's a potentially worse problem: there's an hour that can't be spelled unambiguously in local wall time: the last hour of daylight time. In Eastern, that's times of the form 5:MM UTC on the day daylight time ends. The local wall clock leaps from 1:59 (daylight time) back to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous. astimezone() mimics the local clock's behavior by mapping two adjacent UTC hours into the same local hour then. In the Eastern example, UTC times of the form 5:MM and 6:MM both map to 1:MM when converted to Eastern, but earlier times have the fold attribute set to 0 and the later times have it set to 1. For example, at the Fall back transition of 2016, we get:

>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0

Note that the datetime instances that differ only by the value of the fold attribute are considered equal in comparisons.

壁時間に関する曖昧さは、明示的に fold 属性を検証するか、 timezone が使用されたハイブリッドな tzinfo サブクラスか、そのほかの絶対時間差を示す tzinfo サブクラス(EST (-5 時間の絶対時間差) のみを表すクラスや、 EDT (-4 時間の絶対時間差) のみを表すクラス)を使用すると回避できます。 このような曖昧さを許容できないアプリケーションは、このような手法によって回避すべきです。

参考

dateutil.tz

The datetime module has a basic timezone class (for handling arbitrary fixed offsets from UTC) and its timezone.utc attribute (a UTC timezone instance).

dateutil.tz library brings the IANA timezone database (also known as the Olson database) to Python, and its usage is recommended.

IANA タイムゾーンデータベース

(しばしば tz、tzdata や zoneinfo と呼ばれる) タイムゾーンデータベースはコードとデータを保持しており、それらは地球全体にわたる多くの代表的な場所のローカル時刻の履歴を表しています。政治団体によるタイムゾーンの境界、UTC オフセット、夏時間のルールの変更を反映するため、定期的にデータベースが更新されます。

timezone オブジェクト

The timezone class is a subclass of tzinfo, each instance of which represents a timezone defined by a fixed offset from UTC.

Objects of this class cannot be used to represent timezone information in the locations where different offsets are used in different days of the year or where historical changes have been made to civil time.

class datetime.timezone(offset, name=None)

The offset argument must be specified as a timedelta object representing the difference between the local time and UTC. It must be strictly between -timedelta(hours=24) and timedelta(hours=24), otherwise ValueError is raised.

The name argument is optional. If specified it must be a string that will be used as the value returned by the datetime.tzname() method.

バージョン 3.2 で追加.

バージョン 3.7 で変更: The UTC offset is not restricted to a whole number of minutes.

timezone.utcoffset(dt)

Return the fixed value specified when the timezone instance is constructed.

The dt argument is ignored. The return value is a timedelta instance equal to the difference between the local time and UTC.

バージョン 3.7 で変更: The UTC offset is not restricted to a whole number of minutes.

timezone.tzname(dt)

Return the fixed value specified when the timezone instance is constructed.

If name is not provided in the constructor, the name returned by tzname(dt) is generated from the value of the offset as follows. If offset is timedelta(0), the name is "UTC", otherwise it is a string in the format UTC±HH:MM, where ± is the sign of offset, HH and MM are two digits of offset.hours and offset.minutes respectively.

バージョン 3.6 で変更: Name generated from offset=timedelta(0) is now plain 'UTC', not 'UTC+00:00'.

timezone.dst(dt)

常に None を返します。

timezone.fromutc(dt)

Return dt + offset. The dt argument must be an aware datetime instance, with tzinfo set to self.

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

timezone.utc

UTC タイムゾーン timezone(timedelta(0)) です。

strftime()strptime() の振る舞い

date, datetime, and time objects all support a strftime(format) method, to create a string representing the time under the control of an explicit format string.

Conversely, the datetime.strptime() class method creates a datetime object from a string representing a date and time and a corresponding format string.

The table below provides a high-level comparison of strftime() versus strptime():

strftime

strptime

使用法

Convert object to a string according to a given format

Parse a string into a datetime object given a corresponding format

Type of method

Instance method

Class method

Method of

date; datetime; time

datetime

Signature

strftime(format)

strptime(date_string, format)

strftime() and strptime() Format Codes

The following is a list of all the format codes that the 1989 C standard requires, and these work on all platforms with a standard C implementation.

ディレクティブ

意味

使用例

注釈

%a

ロケールの曜日名を短縮形で表示します。

Sun, Mon, ..., Sat (en_US);
So, Mo, ..., Sa (de_DE)

(1)

%A

ロケールの曜日名を表示します。

Sunday, Monday, ..., Saturday (en_US);
Sonntag, Montag, ..., Samstag (de_DE)

(1)

%w

曜日を10進表記した文字列を表示します。0 が日曜日で、6 が土曜日を表します。

0, 1, ..., 6

%d

0埋めした10進数で表記した月中の日にち。

01, 02, ..., 31

(9)

%b

ロケールの月名を短縮形で表示します。

Jan, Feb, ..., Dec (en_US);
Jan, Feb, ..., Dez (de_DE)

(1)

%B

ロケールの月名を表示します。

January, February, ..., December (en_US);
Januar, Februar, ..., Dezember (de_DE)

(1)

%m

0埋めした10進数で表記した月。

01, 02, ..., 12

(9)

%y

0埋めした10進数で表記した世紀無しの年。

00, 01, ..., 99

(9)

%Y

西暦 (4桁) の 10 進表記を表します。

0001, 0002, ..., 2013, 2014, ..., 9998, 9999

(2)

%H

0埋めした10進数で表記した時 (24時間表記)。

00, 01, ..., 23

(9)

%I

0埋めした10進数で表記した時 (12時間表記)。

01, 02, ..., 12

(9)

%p

ロケールの AM もしくは PM と等価な文字列になります。

AM, PM (en_US);
am, pm (de_DE)

(1), (3)

%M

0埋めした10進数で表記した分。

00, 01, ..., 59

(9)

%S

0埋めした10進数で表記した秒。

00, 01, ..., 59

(4), (9)

%f

10進数で表記したマイクロ秒 (左側から0埋めされます)。

000000, 000001, ..., 999999

(5)

%z

UTC offset in the form ±HHMM[SS[.ffffff]] (empty string if the object is naive).

(empty), +0000, -0400, +1030, +063415, -030712.345216

(6)

%Z

タイムゾーンの名前を表示します (オブジェクトがnaiveであれば空文字列)。

(空文字列), UTC, EST, CST

%j

0埋めした10進数で表記した年中の日にち。

001, 002, ..., 366

(9)

%U

0埋めした10進数で表記した年中の週番号 (週の始まりは日曜日とする)。新年の最初の日曜日に先立つ日は 0週に属するとします。

00, 01, ..., 53

(7), (9)

%W

0埋めした10進数で表記した年中の週番号 (週の始まりは月曜日とする)。新年の最初の月曜日に先立つ日は 0週に属するとします。

00, 01, ..., 53

(7), (9)

%c

ロケールの日時を適切な形式で表します。

Tue Aug 16 21:30:00 1988 (en_US);
Di 16 Aug 21:30:00 1988 (de_DE)

(1)

%x

ロケールの日付を適切な形式で表します。

08/16/88 (None);
08/16/1988 (en_US);
16.08.1988 (de_DE)

(1)

%X

ロケールの時間を適切な形式で表します。

21:30:00 (en_US);
21:30:00 (de_DE)

(1)

%%

文字 '%' を表します。

%

Several additional directives not required by the C89 standard are included for convenience. These parameters all correspond to ISO 8601 date values.

ディレクティブ

意味

使用例

注釈

%G

ISO week(%V)の内過半数を含む西暦表記の ISO 8601 year です。

0001, 0002, ..., 2013, 2014, ..., 9998, 9999

(8)

%u

1 を月曜日を表す 10進数表記の ISO 8601 weekday です。

1, 2, ..., 7

%V

週で最初の月曜日を始めとする ISO 8601 week です。Week 01 は 1月4日を含みます。

01, 02, ..., 53

(8), (9)

These may not be available on all platforms when used with the strftime() method. The ISO 8601 year and ISO 8601 week directives are not interchangeable with the year and week number directives above. Calling strptime() with incomplete or ambiguous ISO 8601 directives will raise a ValueError.

The full set of format codes supported varies across platforms, because Python calls the platform C library's strftime() function, and platform variations are common. To see the full set of format codes supported on your platform, consult the strftime(3) documentation.

バージョン 3.6 で追加: %G, %u および %V が追加されました。

Technical Detail

Broadly speaking, d.strftime(fmt) acts like the time module's time.strftime(fmt, d.timetuple()) although not all objects support a timetuple() method.

For the datetime.strptime() class method, the default value is 1900-01-01T00:00:00.000: any components not specified in the format string will be pulled from the default value. 4

Using datetime.strptime(date_string, format) is equivalent to:

datetime(*(time.strptime(date_string, format)[0:6]))

except when the format includes sub-second components or timezone offset information, which are supported in datetime.strptime but are discarded by time.strptime.

For time objects, the format codes for year, month, and day should not be used, as time objects have no such values. If they're used anyway, 1900 is substituted for the year, and 1 for the month and day.

For date objects, the format codes for hours, minutes, seconds, and microseconds should not be used, as date objects have no such values. If they're used anyway, 0 is substituted for them.

For the same reason, handling of format strings containing Unicode code points that can't be represented in the charset of the current locale is also platform-dependent. On some platforms such code points are preserved intact in the output, while on others strftime may raise UnicodeError or return an empty string instead.

注釈:

  1. フォーマットは現在のロケールに依存するので、出力値について何か仮定するときは注意すべきです。フィールドの順序は様々で (例えば、"月/日/年" と "日/月/年") 、出力はロケールのデフォルトエンコーディングでエンコードされた Unicode 文字列を含むかもしれません (例えば、現在のロケールが ja_JP だった場合、デフォルトエンコーディングは eucJPSJISutf-8 のいずれかになりえます。 locale.getlocale() を使って現在のロケールのエンコーディングを確認します) 。

  2. strptime() メソッドは [1, 9999] の範囲の年数全てを構文解析できますが、 year < 1000 の範囲の年数は 0 埋めされた 4 桁の数字でなければなりません。

    バージョン 3.2 で変更: 以前のバージョンでは、 strftime() メソッドは years >= 1900 の範囲の年数しか扱えませんでした。

    バージョン 3.3 で変更: バージョン 3.2 では、 strftime() メソッドは years >= 1000 の範囲の年数しか扱えませんでした。

  3. strptime() メソッドと共に使われた場合、 %p 指定子は出力の時間フィールドのみに影響し、 %I 指定子が使われたかのように振る舞います。

  4. time モジュールと違い、 datetime モジュールはうるう秒をサポートしていません。

  5. When used with the strptime() method, the %f directive accepts from one to six digits and zero pads on the right. %f is an extension to the set of format characters in the C standard (but implemented separately in datetime objects, and therefore always available).

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

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

    %z

    utcoffset() is transformed into a string of the form ±HHMM[SS[.ffffff]], where HH is a 2-digit string giving the number of UTC offset hours, MM is a 2-digit string giving the number of UTC offset minutes, SS is a 2-digit string giving the number of UTC offset seconds and ffffff is a 6-digit string giving the number of UTC offset microseconds. The ffffff part is omitted when the offset is a whole number of seconds and both the ffffff and the SS part is omitted when the offset is a whole number of minutes. For example, if utcoffset() returns timedelta(hours=-3, minutes=-30), %z is replaced with the string '-0330'.

    バージョン 3.7 で変更: The UTC offset is not restricted to a whole number of minutes.

    バージョン 3.7 で変更: When the %z directive is provided to the strptime() method, the UTC offsets can have a colon as a separator between hours, minutes and seconds. For example, '+01:00:00' will be parsed as an offset of one hour. In addition, providing 'Z' is identical to '+00:00'.

    %Z

    If tzname() returns None, %Z is replaced by an empty string. Otherwise %Z is replaced by the returned value, which must be a string.

    バージョン 3.2 で変更: When the %z directive is provided to the strptime() method, an aware datetime object will be produced. The tzinfo of the result will be set to a timezone instance.

  7. strptime() メソッドと共に使われた場合、 %U%W 指定子は、曜日と年(%Y)が指定された場合の計算でのみ使われます。

  8. %U%W と同様です。 %V は曜日と ISO year (%G)が strptime() 書式内で指定された場合に計算でのみ使われます。 %G%Y は互いに完全な互換性を持たないことにも注意してください。

  9. When used with the strptime() method, the leading zero is optional for formats %d, %m, %H, %I, %M, %S, %J, %U, %W, and %V. Format %y does require a leading zero.

脚注

1

もし相対性理論の効果を無視するならば、ですが

2

This matches the definition of the "proleptic Gregorian" calendar in Dershowitz and Reingold's book Calendrical Calculations, where it's the base calendar for all computations. See the book for algorithms for converting between proleptic Gregorian ordinals and many other calendar systems.

3

See R. H. van Gent's guide to the mathematics of the ISO 8601 calendar for a good explanation.

4

Passing datetime.strptime('Feb 29', '%b %d') will fail since 1900 is not a leap year.