これは既にサポートされていない古いバージョンの Python のドキュメントです。 是非 Python をアップグレードし、このドキュメントを読みましょう: 現在の安定板リリースの Python ドキュメント.

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

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

`datetime` モジュールでは、日付や時間データを簡単な方法と複雑な方法の両方で操作するためのクラスを提供しています。日付や時刻を対象にした四則演算がサポートされている一方で、このモジュールの実装では出力の書式化や操作を目的とした属性の効率的な取り出しに焦点を絞っています。機能については、 `time` および `calendar` も参照してください。

"naive" と "aware" の2種類の日付と時刻オブジェクトがあります。

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

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

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

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

`datetime.``MINYEAR`

  `date` や `datetime` オブジェクトで許されている、年を表現する最小の数字です。 `MINYEAR` は `1` です。

`datetime.``MAXYEAR`

  `date` や `datetime` オブジェクトで許されている、年を表現する最大の数字です。 `MAXYEAR` は `9999` です。

参考

`calendar` モジュール

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

`time` モジュール

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

## 利用可能なデータ型

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) です。

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

`time` や `datetime` 型のオブジェクトは naive か aware のどちらかになります。 `datetime` オブジェクト d は `d.tzinfo` が `None` でなく `d.tzinfo.utcoffset(d)` が `None` を返さない場合、aware です。`d.tzinfo` が `None` であるか `d.tzinfo` が `None` でないが `d.tzinfo.utcoffset(d)` が `None` を返す場合、 d は naive です。 `time` のオブジェクト t は `t.tzinfo` が `None` でなく `t.tzinfo.utcoffset(None)` が `None` を返さない場合に aware になって、それ以外の場合には t は naive になります。

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

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

    object
        timedelta
        tzinfo
            timezone
        time
        date
            datetime

## `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`

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

  日の値を正規化した結果、指定された範囲の外側になった場合には、 `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.max` は `timedelta` オブジェクトとして表現することができません。

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

属性 | 値
--- | ---
`days` | 両端値を含む -999999999 から 999999999 の間
`seconds` | 両端値を含む 0 から 86399 の間
`microseconds` | 両端値を含む 0 から 999999 の間

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

演算 | 結果
--- | ---
`t1 = t2 + t3` | t2 と t3 の和。演算後、t1-t2 == t3 および t1-t3 == t2 は真になります。(1)
`t1 = t2 - t3` | t2 と t3 の差分です。演算後、 t1 == t2 - t3 および t2 == t1 + t3 は真になります。 (1)(6)
`t1 = t2 * i または t1 = i * t2` | 時間差と整数の積。演算後、t1 // i == t2 は `i != 0` であれば真となります。
| 一般的に、t1 * i == t1 * (i-1) + t1 は真となります。(1)
`t1 = t2 * f` または `t1 = f * t2` | 時間差と浮動小数点の積。結果は最近接偶数への丸めを利用して最も近い timedelta.resolution の倍数に丸められます。
`f = t2 / t3` | t2 を 3 で除算 (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.max は `timedelta` オブジェクトで表現することができません。

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` オブジェクト間の比較はサポートされており、より小さい経過時間を表す `timedelta` オブジェクトがより小さい timedelta と見なされます。型混合の比較がデフォルトのオブジェクトアドレス比較となってしまうのを抑止するために、 `timedelta` オブジェクトと異なる型のオブジェクトが比較されると、比較演算子が `==` または `!=` でないかぎり `TypeError` が送出されます。後者の場合、それぞれ `False` または `True` を返します。

`timedelta` オブジェクトは hashable (ハッシュ可能、つまり、辞書のキーとして利用可能) であり、効率的な pickle 化をサポートします。また、ブール演算コンテキストでは、 `timedelta` オブジェクトは `timedelta(0)` に等しくない場合かつそのときに限り真となります。

インスタンスメソッド:

`timedelta.``total_seconds`()

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

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

  バージョン 3.2 で追加.

使用例:

    >>> from datetime import timedelta
    >>> year = timedelta(days=365)
    >>> another_year = timedelta(weeks=40, days=84, hours=23,
    ...                          minutes=50, seconds=600)  # adds up to 365 days
    >>> year.total_seconds()
    31536000.0
    >>> year == another_year
    True
    >>> ten_years = 10 * year
    >>> ten_years, ten_years.days // 365
    (datetime.timedelta(days=3650), 10)
    >>> nine_years = ten_years - year
    >>> nine_years, nine_years.days // 365
    (datetime.timedelta(days=3285), 9)
    >>> three_years = nine_years // 3
    >>> three_years, three_years.days // 365
    (datetime.timedelta(days=1095), 3)
    >>> abs(three_years - ten_years) == 2 * three_years + year
    True

## `date` オブジェクト

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

class `datetime.``date`(year, month, day)

  All arguments are required. Arguments must be integers in the following ranges:

  - `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)

  `date.isoformat()` から出力される形式の date_string に対応する `date` を返します。 具体的には、この関数は `YYYY-MM-DD` という形式の文字列をサポートしています。

  ご用心

  この関数は、任意の ISO 8601 文字列の構文解析をサポートしているわけではありません - これは `date.isoformat()` の逆演算を意図して実装されています。

  バージョン 3.7 で追加.

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

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

注釈:

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

2. `timedelta.seconds` と `timedelta.microseconds` は無視されます。

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

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

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

インスタンスメソッド:

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

  キーワード引数で指定されたパラメタが置き換えられることを除き、同じ値を持つ `date` オブジェクトを返します。例えば、`d == date(2002, 12, 31)` とすると、`d.replace(day=26) == 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 カレンダーはグレゴリオ暦の変種として広く用いられています。 細かい説明については https://www.staff.science.uu.nl/~gent0113/calendar/isocalendar.htm を参照してください。

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

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

`date.``isoformat`()

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

`date.``__str__`()

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

`date.``ctime`()

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

`date.``strftime`(format)

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

`date.``__format__`(format)

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

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

    >>> 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)
    >>> 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 )
    >>> d.isoformat()
    '2002-03-11'
    >>> d.strftime("%d/%m/%y")
    '11/03/02'
    >>> d.strftime("%A %d. %B %Y")
    'Monday 11. March 2002'
    >>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
    'The day is 11, the month is March.'

## `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)

  The year, month and day arguments are required. tzinfo may be `None`, or an instance of a `tzinfo` subclass. The remaining arguments must be integers in the following ranges:

  - `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`()

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

classmethod `datetime.``now`(tz=None)

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

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

classmethod `datetime.``utcnow`()

  `tzinfo` が `None` である現在の UTC の日付および時刻を返します。 これは `now()` と似ていますが、 naive な `datetime` オブジェクトとして現在の UTC 日付および時刻を返します。 aware な現在の UTC datetime は `datetime.now(timezone.utc)` を呼び出すことで取得できます。 `now()` も参照してください。

classmethod `datetime.``fromtimestamp`(timestamp, tz=None)

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

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

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

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

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

classmethod `datetime.``utcfromtimestamp`(timestamp)

  与えられた POSIX タイムスタンプに対応する UTC の `datetime` で、 `tzinfo` が `None` に設定されたものを返します。 タイムスタンプがプラットフォームの C 関数 `gmtime()` でサポートされている範囲を超えている場合には `OverflowError` を、 `gmtime()` が失敗した場合には `OSError` を送出します。 サポートされている範囲は 1970 年から 2038 年に制限されていることが多いです。

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

      datetime.fromtimestamp(timestamp, timezone.utc)

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

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

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

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

classmethod `datetime.``fromordinal`(ordinal)

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

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

  日付部分と与えられた `date` オブジェクトとが等しく、時刻部分と与えられた `time` オブジェクトとが等しい、新しい `datetime` オブジェクトを返します。 tzinfo 引数が与えられた場合、その値は返り値の `tzinfo` 属性に設定するのに使われます。そうでない場合、 time 引数の `tzinfo` 属性が使われます。

  任意の `datetime` オブジェクト d で `d == datetime.combine(d.date(), d.timetz())` が成立します。 date が `datetime` オブジェクトだった場合、その `datetime` オブジェクトの時刻部分と `tzinfo` 属性は無視されます。

  バージョン 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(s) `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.

  バージョン 3.7 で追加.

classmethod `datetime.``strptime`(date_string, format)

  date_string に対応した `datetime` を返します。 format にしたがって構文解析されます。これは、 `datetime(*(time.strptime(date_string, format)[0:6]))` と等価です。 date_stringとformatが `time.strptime()` で構文解析できない場合や、この関数が時刻タプルを返してこない場合には `ValueError` を送出します。完全な書式化ディレクティブのリストについては 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` | `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 だとしてもタイムゾーン修正は全く行われません。

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` が送出されます。等価比較では、 naive インスタンスと aware インスタンスは等価になることはありません。

   比較対象が両方とも aware で、同じ `tzinfo` 属性を持つ場合、 `tzinfo` は無視され datetime だけで比較が行われます。 比較対象が両方とも aware であり、異なる `tzinfo` 属性を持つ場合、まず最初に (`self.utcoffset()` で取得できる) それぞれの UTC オフセットを引いて調整します。

   バージョン 3.3 で変更: naive な `datetime` インスタンスと aware な `datetime` インスタンスの等価比較では `TypeError` は送出されません。

   注釈

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

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

インスタンスメソッド:

`datetime.``date`()

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

`datetime.``time`()

  同じhour、minute、second、microsecond 及び foldを持つ `time` オブジェクトを返します。 `tzinfo` は `None` です。 `timetz()` も参照してください。

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

`datetime.``timetz`()

  同じhour、minute、second、microsecond、fold および tzinfo 属性を持つ `time` オブジェクトを返します。 `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)

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

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

`datetime.``astimezone`(tz=None)

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

  もし与えられた場合、 tz は `tzinfo` のサブクラスのインスタンスでなければならず、 インスタンスの `utcoffset()` および `dst()` メソッドは `None` を返してはなりません。もし self が naive ならば、おそらくシステムのタイムゾーンで時間を表現します。

  引数無し (もしくは `tz=None``の形 ) で呼び出された場合、変更先のタイムゾーンはシステムのローカルなタイムゾーンだと想定されます。 変換後の datetime インスタンスの ``.tzinfo` 属性には、 OS から取得したゾーン名とオフセットを持つ `timezone` インスタンスが設定されます。

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

  単にタイムゾーンオブジェクト 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)

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

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

`datetime.``utcoffset`()

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

  バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。

`datetime.``dst`()

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

  バージョン 3.7 で変更: DST オフセットが分単位でなければならない制限が無くなりました。

`datetime.``tzname`()

  `tzinfo` が `None` の場合 `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))` と等価です。 ここで `yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1` はその年の1月1日を `1` としたときのその日の位置です。 返されるタプルの `tm_isdst` フラグは `dst()` メソッドに従って設定されます: `tzinfo` が `None` か `dst()` が `None` を返す場合、 `tm_isdst` は `-1` に設定されます; そうでない場合、 `dst()` がゼロでない値を返すと `tm_isdst` は `1` となります; それ以外の場合には `tm_isdst` は `0` に設定されます。

`datetime.``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` もしくは `MAXYEAR` であり、 UTC 時刻への調整により適切な年の範囲を越えた場合、 `OverflowError` が送出される可能性があることに注意してください。

`datetime.``toordinal`()

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

`datetime.``timestamp`()

  `datetime` インスタンスに対応する POSIX タイムスタンプを返します。 返り値は `time.time()` で返される値に近い `float` です。

  このメソッドでは naive な `datetime` インスタンスはローカル時刻とし、プラットフォームの C 関数 `mktime()` に頼って変換を行います。 `datetime` は多くのプラットフォームの `mktime()` より広い範囲の値をサポートしているので、遥か過去の時刻や遥か未来の時刻に対し、このメソッドは `OverflowError` を送出するかもしれません。

  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.

  注釈

  UTC 時刻を表す naive な `datetime` インスタンスから直接 POSIX タイムスタンプを取得するメソッドはありません。 アプリケーションがその変換を使っており、システムのタイムゾーンが UTC に設定されていなかった場合、 `tzinfo=timezone.utc` を引数に与えることで POSIX タイムスタンプを取得できます:

      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`()

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

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

  Return a string representing the date and time in ISO 8601 format, YYYY-MM-DDTHH:MM:SS.ffffff or, if `microsecond` is 0, YYYY-MM-DDTHH:MM:SS

  If `utcoffset()` does not return `None`, a string is appended, giving the UTC offset: YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]] or, if `microsecond` is 0 YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]].

  オプションの引数 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'

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

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

  - `'hours'`: `hour` を2文字の HH 書式で含めます。

  - `'minutes'`: `hour` および `minute` を HH:MM の書式で含めます。

  - `'seconds'`: `hour` と `minute` および `second` を HH:MM:SS の書式で含めます。

  - `'milliseconds'`: 全ての時間を含みますが、小数第二位をミリ秒に切り捨てます。 HH:MM:SS.sss の書式で表現します。

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

  注釈

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

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

      >>> 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`()

  日付を表す文字列を、例えば `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()))` と等価です。

`datetime.``strftime`(format)

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

`datetime.``__format__`(format)

  `datetime.strftime()` と等価です。 これにより、 フォーマット済み文字列リテラル の中や `str.format()` を使っているときに `datetime` オブジェクトの書式文字列を指定できます。 書式化コードの完全なリストについては strftime() と strptime() の振る舞い を参照してください。

datetime オブジェクトを使う例:

    >>> from datetime import datetime, date, time
    >>> # 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() or datetime.utcnow()
    >>> datetime.now()
    datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
    >>> datetime.utcnow()
    datetime.datetime(2007, 12, 6, 15, 29, 43, 79060)
    >>> # 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 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.'

datetime を tzinfo と組み合わせて使う:

    >>> 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):
    ...             # 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):
    ...         # 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
    ...
    ...         # 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")
    ...
    ...         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):
    ...         return timedelta(0)
    ...
    ...     def tzname(self, dt):
    ...         if dt >= self.UTC_MOVE_DATE:
    ...             return "+04:30"
    ...         else:
    ...             return "+04"
    ...
    ...     def  __repr__(self):
    ...         return f"{self.__class__.__name__}()"
    ...
    >>> 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.utctimetuple() == dt3.utctimetuple()
    True

## `time` オブジェクト

`time` オブジェクトは (ローカルの) 日中時刻を表現します。この時刻表現は特定の日の影響を受けず、 `tzinfo` オブジェクトを介した修正の対象となります。

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]`.

  引数がこれらの範囲外にある場合、 `ValueError` が送出されます。 tzinfo のデフォルト値が `None` である以外のデフォルト値は `0` です。

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

`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` と `time` の比較では、 a が b より前の時刻だった場合 a が b より小さいとされます。比較の一方が naive であり、もう一方が aware の場合に、順序比較が行われると `TypeError` が送出されます。等価比較では、 naive インスタンスと aware インスタンスは等価になることはありません。

  比較対象が両方とも aware であり、同じ `tzinfo` 属性を持つ場合、 `tzinfo` は無視され datetime だけで比較が行われます。 比較対象が両方とも aware であり、異なる `tzinfo` 属性を持つ場合、まず最初に (`self.utcoffset()` で取得できる) それぞれの UTC オフセットを引いて調整します。 異なる型どうしの比較がデフォルトのオブジェクトアドレス比較となってしまうのを防ぐために、 `time` オブジェクトを異なる型のオブジェクトと比較すると、比較演算子が `==` または `!=` でないかぎり `TypeError` が送出されます。 比較演算子が `==` または `!=` である場合、それぞれ `False` または `True` を返します。

  バージョン 3.3 で変更: naive な `time` インスタンスと aware な `time` インスタンスの等価比較では、 `TypeError` は送出されません。

- ハッシュ化、辞書のキーとしての利用

- 効率的な pickle 化

ブール値の文脈では、 `time` オブジェクトは常に真とみなされます。

バージョン 3.5 で変更: Python 3.5 以前は、 `time` オブジェクトは UTC で深夜を表すときに偽とみなされていました。 この挙動は分かりにくく、エラーの元となると考えられ、Python 3.5 で削除されました。 全詳細については bpo-13936 を参照してください。

その他のコンストラクタ:

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(s) `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()`.

  バージョン 3.7 で追加.

インスタンスメソッド:

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

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

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

`time.``isoformat`(timespec='auto')

  Return a string representing the time in ISO 8601 format, HH:MM:SS.ffffff or, if `microsecond` is 0, HH:MM:SS If `utcoffset()` does not return `None`, a string is appended, giving the UTC offset: HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]] or, if self.microsecond is 0, HH:MM:SS+HH:MM[:SS[.ffffff]].

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

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

  - `'hours'`: `hour` を2文字の HH 書式で含めます。

  - `'minutes'`: `hour` および `minute` を HH:MM の書式で含めます。

  - `'seconds'`: `hour` と `minute` および `second` を HH:MM:SS の書式で含めます。

  - `'milliseconds'`: 全ての時間を含みますが、小数第二位をミリ秒に切り捨てます。 HH:MM:SS.sss の書式で表現します。

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

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

`time.``__format__`(format)

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

`time.``utcoffset`()

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

  バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。

`time.``dst`()

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

  バージョン 3.7 で変更: DST オフセットが分単位でなければならない制限が無くなりました。

`time.``tzname`()

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

例:

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

  このクラスは抽象基底クラスで、直接インスタンス化すべきでないことを意味します。 具象サブクラスを作成し、(少なくとも) 使いたい `datetime` のメソッドが必要とする `tzinfo` のメソッドを実装する必要があります。 `datetime` モジュールは `tzinfo` のシンプルな具象サブクラス `timezone` を提供します。 これは UTC そのものか北アメリカの EST と EDT のような UTC からの固定されたオフセットを持つタイムゾーンを表せます。

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

  pickle 化についての特殊な要求事項: `tzinfo` のサブクラスは引数なしで呼び出すことのできる `__init__()` メソッドを持たなければなりません。そうでなければ、 pickle 化することはできますがおそらく unpickle 化することはできないでしょう。これは技術的な側面からの要求であり、将来緩和されるかもしれません。

  `tzinfo` の具体的なサブクラスでは、以下のメソッドを実装する必要があります。厳密にどのメソッドが必要なのかは、 aware な `datetime` オブジェクトがこのサブクラスのインスタンスをどのように使うかに依存します。不確かならば、単に全てを実装してください。

`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. Note that this is intended to be 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 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。

`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)`

  が、 `dt.tzinfo == tz` 全ての `datetime` オブジェクト dt について常に同じ結果を返さなければならないという点で、一貫性を持っていなければなりません。正常に実装された `tzinfo` のサブクラスでは、この式はタイムゾーンにおける "標準オフセット (standard offset)" を表し、特定の日や時刻の事情ではなく地理的な位置にのみ依存していなくてはなりません。 `datetime.astimezone()` の実装はこの事実に依存していますが、違反を検出することができません; 正しく実装するのはプログラマの責任です。 `tzinfo` のサブクラスでこれを保証することができない場合、 `tzinfo.fromutc()` の実装をオーバライドして、 `astimezone()` に関わらず正しく動作するようにしてもかまいません。

  ほとんどの `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.  Then

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

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

  バージョン 3.7 で変更: DST オフセットが分単位でなければならない制限が無くなりました。

`tzinfo.``tzname`(dt)

  `datetime` オブジェクト dt に対応するタイムゾーン名を文字列で返します。 `datetime` モジュールでは文字列名について何も定義しておらず、特に何かを意味するといった要求仕様もまったくありません。例えば、 "GMT","UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" は全て有効な応答となります。文字列名が未知の場合には `None` を返してください。 `tzinfo` のサブクラスでは、特に, `tzinfo` クラスが夏時間について記述している場合のように、渡された dt の特定の値によって異なった名前を返したい場合があるため、文字列値ではなくメソッドとなっていることに注意してください。

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

以下のメソッドは `datetime` や `time` オブジェクトにおいて、同名のメソッドが呼び出された際に応じて呼び出されます。 `datetime` オブジェクトは自身を引数としてメソッドに渡し、 `time` オブジェクトは引数として `None` をメソッドに渡します。従って、 `tzinfo` のサブクラスにおけるメソッドは引数 dt が `None` の場合と、 `datetime` の場合を受理するように用意しなければなりません。

`None` が渡された場合、最良の応答方法を決めるのはクラス設計者次第です。例えば、このクラスが `tzinfo` プロトコルと関係をもたないということを表明させたければ、 `None` が適切です。標準時のオフセットを見つける他の手段がない場合には、標準 UTC オフセットを返すために `utcoffset(None)` を使うともっと便利かもしれません。

`datetime` オブジェクトが `datetime()` メソッドの応答として返された場合、 `dt.tzinfo` は self と同じオブジェクトになります。ユーザが直接 `tzinfo` メソッドを呼び出さないかぎり、 `tzinfo` メソッドは `dt.tzinfo` と self が同じであることに依存します。その結果 `tzinfo` メソッドは dt がローカル時間であると解釈するので、他のタイムゾーンでのオブジェクトの振る舞いについて心配する必要がありません。

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

`tzinfo.``fromutc`(dt)

  デフォルトの `datetime.astimezone()` 実装で呼び出されます。 `datetime.astimezone()` から呼ばれた場合、 `dt.tzinfo` は self であり、 dt の日付および時刻データは UTC 時刻を表しているものとして見えます。 `fromutc()` の目的は、 self のローカル時刻に等しい `datetime` オブジェクトを返すことにより日付と時刻データメンバを修正することにあります。

  ほとんどの `tzinfo` サブクラスではデフォルトの `fromutc()` 実装を問題なく継承できます。デフォルトの実装は、固定オフセットのタイムゾーンや、標準時と夏時間の両方について記述しているタイムゾーン、そして DST 移行時刻が年によって異なる場合でさえ、扱えるくらい強力なものです。デフォルトの `fromutc()` 実装が全ての場合に対して正しく扱うことができないような例は、標準時の (UTCからの) オフセットが引数として渡された特定の日や時刻に依存するもので、これは政治的な理由によって起きることがあります。デフォルトの `astimezone()` や `fromutc()` の実装は、結果が標準時オフセットの変化にまたがる何時間かの中にある場合、期待通りの結果を生成しないかもしれません。

  エラーの場合のためのコードを除き、デフォルトの `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

次の `tzinfo_examples.py` ファイルには、 `tzinfo` クラスの例がいくつか載っています:

    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")

標準時および夏時間の両方を記述している `tzinfo` のサブクラスでは、夏時間の移行のときに、回避不能の難解な問題が年に 2 度あるので注意してください。 具体的な例として、東部アメリカ時刻 (US Eastern, UTC -0500) を考えます。 EDT は 3 月の第二日曜日の 1:59 (EST) の 1 分後に開始し、11 月の最初の日曜日の (EDTの) 1:59 に終了します:

      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

DSTの開始の際("startの並び") ローカルの壁時間は 1:59 から 3:00 に飛びます。この日には、 2:MM の形で表現される壁時間は意味をなさないので、`astimezone(Eastern)` は ``hour == 2``となる結果を返すことはありません。 例として、2016年の春向き移行では、以下の

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

DST が終了する際 ("end" の並び) では、問題はさらに悪化します: 1 時間の間、ローカルの壁時計ではっきりと時刻をいえなくなります: それは夏時間の最後の 1 時間です。東部時刻では、その日の UTC での 5:MM に夏時間は終了します。ローカルの壁時計は 1:59 (夏時間) から 1:00 (標準時) に再び巻き戻されます。ローカルの時刻における 1:MM はあいまいになります。 `astimezone()` は二つの UTC 時刻を同じローカルの時刻に対応付けることでローカルの時計の振る舞いをまねます。東部時刻の例では、 5:MM および 6:MM の形式をとる UTC 時刻は両方とも、東部時刻に変換された際に 1:MM に対応づけられますが、それ以前の時間は `fold` 属性を0にし、以降の時間では1にします。例えば、2016年での秋向き以降では、以下の

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

  標準ライブラリにはUTCからの任意の固定オフセットを扱うために、 `timezone` クラスが、 UTCタイムゾーンのインスタンスとして、 `timezone.utc` があります。

  dateutil.tz ライブラリは Python に IANA タイムゾーンデータベース (オルソンデータベースとしても知られています) をもたらし、そしてそれの利用が推奨されます。

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

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

## `timezone` オブジェクト

`timezone` クラスは `tzinfo` のサブクラスで、各インスタンスは UTC からの固定されたオフセットで定義されたタイムゾーンを表しています。このクラスのオブジェクトは、一年のうち異なる日に異なるオフセットが使われていたり、常用時 (civil time) に歴史的な変化が起きた場所のタイムゾーン情報を表すのには使えないので注意してください。

class `datetime.``timezone`(offset, name=None)

  ローカル時刻と UTC の差分を表す `timedelta` オブジェクトを offset 引数に指定しなくてはいけません。これは `-timedelta(hours=24)` から `timedelta(hours=24)` までの両端を含まない範囲に収まっていなくてはなりません。そうでない場合 `ValueError` が送出されます。

  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 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。

`timezone.``utcoffset`(dt)

  `timezone` インスタンスの作成時に指定された固定の値を返します。 dt 引数は無視されます。返り値は、ローカル時刻と UTC の差分に等しい `timedelta` インスタンスです。

  バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。

`timezone.``tzname`(dt)

  `timezone` インスタンスが構築されたときに指定された固定値を返します。 name が構築時に与えられなかった場合、 `tzname(dt)` によって返される name は以下の様に `offset` の値から生成されます。offset が `timedelta(0)` であった場合、 name は "UTC"になります。それ以外の場合、文字列 'UTC±HH:MM' となり、± は `offset` を、HH と MM はそれぞれ二桁の `offset.hours` と `offset.minutes` を表現します。

  バージョン 3.6 で変更: `offset=timedelta(0)` によって生成される名前は、プレーンな'UTC'であり、'UTC+00:00'ではありません。

`timezone.``dst`(dt)

  常に `None` を返します。

`timezone.``fromutc`(dt)

  `dt + offset` を返します。 dt 引数は `tzinfo` が `self` になっている aware な `datetime` インスタンスでなければなりません。

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

`timezone.``utc`

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

## `strftime()` と `strptime()` の振る舞い

`date`, `datetime`,および `time` オブジェクトは全て、明示的な書式文字列でコントロールして時刻表現文字列を生成するための `strftime(format)` メソッドをサポートしています。大雑把にいうと、 `d.strftime(fmt)` は `time` モジュールの `time.strftime(fmt, d.timetuple())` のように動作します。ただし全てのオブジェクトが `timetuple()` メソッドをサポートしているわけではありません。

逆に `datetime.strptime()` クラスメソッドは日付や時刻に対応する書式文字列から `datetime` オブジェクトを生成します。 `datetime.strptime(date_string, format)` は `datetime(*(time.strptime(date_string, format)[0:6]))` と等価です。ただし、 `datetime.strptime` ではサポートされていて `time.strptime` ではサポートされない、 小数秒以下の要素またはタイムゾーン情報が含まれる書式の場合には、その限りではありません。

`time` オブジェクトでは、年、月、日の値がないため、それらの書式化コードを使うことができません。無理矢理使った場合、年は `1900` に置き換えられ、月と日は `1` に置き換えられます。

`date` オブジェクトでは、時、分、秒、マイクロ秒の値がないため、それらの書式化コードを使うことができません。無理矢理使った場合、これらの値は `0` に置き換えられます。

`datetime.strptime()` クラスメソッドでは、デフォルト値は `1900-01-01T00:00:00.000` です。書式文字列で指定されなかった部分はデフォルト値から引っ張ってきます。 2

Python はプラットフォームの C ライブラリの `strftime()` 関数を呼び出していて、プラットフォームごとにその実装が異なるのはよくあることなので、サポートされるフォーマット記号全体はプラットフォームごとに様々です。プラットフォームでサポートされているフォーマット記号全体を見るには、 strftime(3) のドキュメントを参照してください。

同じ理由で、現在のロケールの文字集合で表現できない Unicode コードポイントを含む書式文字列の対処もプラットフォーム依存です。 あるプラットフォームではそういったコードポイントはそのまま出力に出される一方、他のプラットフォームでは `strftime` が `UnicodeError` を送出したり、その代わりに空文字列を返したりするかもしれません。

以下のリストはC標準(1989年版)が要求する全ての書式化コードで、標準C実装があれば全ての環境で動作します。1999 年版の C 標準では書式化コードが追加されているので注意してください。

ディレクティブ | 意味 | 使用例 | 注釈
--- | --- | --- | ---
`%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). | (空文字列), +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)
`%%` | 文字 `'%'` を表します。 | % |

C89規格により要求されない幾つかの追加のコードが便宜上含まれています。これらのパラメータはすべてISO 8601の日付値に対応しています。これらが `strftime()` メソッドと一緒に使用された場合、すべてのプラットフォームで利用できるわけではありません。 ISO 8601 year ディレクティブおよびISO 8601 week ディレクティブは、上記のyear および week number ディレクティブと互換性がありません。不完全またはあいまいなISO 8601ディレクティブで `strptime()` を呼び出すと、 `ValueError` が送出されます。

ディレクティブ | 意味 | 使用例 | 注釈
--- | --- | --- | ---
`%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)

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

注釈:

1. フォーマットは現在のロケールに依存するので、出力値について何か仮定するときは注意すべきです。フィールドの順序は様々で (例えば、"月/日/年" と "日/月/年") 、出力はロケールのデフォルトエンコーディングでエンコードされた Unicode 文字列を含むかもしれません (例えば、現在のロケールが `ja_JP` だった場合、デフォルトエンコーディングは `eucJP` 、 `SJIS` 、 `utf-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. `strptime()` メソッドと共に使われた場合、 `%f` 指定子は 1 桁から 6 桁の数字を受け付け、右側から 0 埋めされます。 `%f` は C 標準規格の書式セットに拡張されます。

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 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。

   バージョン 3.7 で変更: `%z` 指定子が `strptime()` メソッドに渡されたときは、時分秒のセパレータとしてコロンが UTC オフセットで使えます。 例えば、 `'+01:00:00'` は 1 時間のオフセットだと構文解析されます。 加えて、 `'Z'` を渡すことは `'+00:00'` と同等です。

   `%Z`

     `tzname()` が `None` を返した場合、 `%Z` は空文字列に置き換わります。そうでない場合、 `%Z` は返された値に置き換わりますが、 これは文字列でなければなりません。

   バージョン 3.2 で変更: `%z` 指定子が `strptime()` メソッドに与えられた場合、 aware な `datetime` オブジェクトが作成されます。返り値の `tzinfo` は `timezone` インスタンスになっています。

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

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

9. `strptime()` メソッドと共に使われたときは、書式 `%d`, `%m`, `%H`, `%I`, `%M`, `%S`, `%J`, `%U`, `%W`, `%V` の後ろに続ける 0 は任意です。 書式 `%y` では後ろに続ける 0 は必須です。

脚注

1

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

2

  `1900` は閏年ではないので `datetime.strptime('Feb 29', '%b %d')` を渡すと失敗します。