# `datetime` --- 基本的な日付と時間の型

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

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

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

Tip

書式コード に飛ぶ。

参考

`calendar` モジュール

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

`time` モジュール

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

`zoneinfo` モジュール

  IANAタイムゾーンデータベースを表す具体的なタイムゾーン。

dateutil パッケージ

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

DateType パッケージ

  Third-party library that introduces distinct static types to e.g. allow static type checkers to differentiate between naive and aware datetimes.

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

日時のオブジェクトは、それらがタイムゾーンの情報を含んでいるかどうかによって "aware" あるいは "naive" に分類されます。

タイムゾーンや夏時間の情報のような、アルゴリズム的で政治的な適用可能な時間調節に関する知識を持っているため、 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です。

datetime.UTC

  UTCタイムゾーンシングルトン `datetime.timezone.utc` の別名。

  Added in version 3.11.

## 利用可能なデータ型

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

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

class datetime.tzinfo

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

class datetime.timezone

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

  Added in version 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.tzinfo` が `None` でない

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

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

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

1. `t.tzinfo` が `None` でない

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

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

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

## `timedelta` オブジェクト

`timedelta` オブジェクトは経過時間、すなわち二つの `datetime` または `date` のインスタンスの差を表します。

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)

  Since the string representation of `timedelta` objects can be confusing, use the following recipe to produce a more readable format:

      >>> def pretty_timedelta(td):
      ...     if td.days >= 0:
      ...         return str(td)
      ...     return f'-({-td!s})'
      ...
      >>> d = timedelta(hours=-1)
      >>> str(d)  # not human-friendly
      '-1 day, 23:00:00'
      >>> pretty_timedelta(d)
      '-(1:00:00)'

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

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` オブジェクトとして表現することができません。

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

timedelta.days

  両端値を含む-999,999,999 から 999,999,999 の間

timedelta.seconds

  両端値を含む 0 から 86,399 の間

  注意

  It is a somewhat common bug for code to unintentionally use this attribute when it is actually intended to get a `total_seconds()` value instead:

      >>> from datetime import timedelta
      >>> duration = timedelta(seconds=11235813)
      >>> duration.days, duration.seconds
      (130, 3813)
      >>> duration.total_seconds()
      11235813.0

timedelta.microseconds

  両端値を含む 0 から 999,999 の間

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

演算 | 結果
--- | ---
`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` を `t3` で除算 (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(0)` に等しくない場合かつそのときに限り真となります。

インスタンスメソッド:

timedelta.total_seconds()

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

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

  Added in version 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` を送出するようになりました。

  バージョン 3.15 で変更: Accepts any real number as timestamp, not only integer or float.

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)

  以下の例外を除く、有効な ISO 8601 フォーマットで与えられた date_string に対応する `date` を返します :

  1. 精度の低い日付は現在サポートされていません(`YYYY-MM`, `YYYY`)。

  2. 拡張された日付表現は現在サポートされていません(`±YYYYYY-MM-DD`)。

  3. 序数の日付は現在サポートされていません(`YYYY-OOO`)。

  例:

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

  Added in version 3.7.

  バージョン 3.11 で変更: 以前はこのメソッドは `YYYY-MM-DD` フォーマットのみをサポートしていました。

classmethod date.fromisocalendar(year, week, day)

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

  Added in version 3.8.

classmethod date.strptime(date_string, format)

  Return a `date` corresponding to date_string, parsed according to format. This is equivalent to:

      date(*(time.strptime(date_string, format)[0:3]))

  date_string と format が `time.strptime()` で構文解析できない場合や、この関数が時刻タプルを返してこない場合には `ValueError` を送出します。strftime() と strptime() の振る舞い および `date.fromisoformat()` も参照してください。

  注釈

  If format specifies a day of month without a year a `DeprecationWarning` is emitted. This is to avoid a quadrennial leap year bug in code seeking to parse only a month and day as the default year used in absence of one in the format is not a leap year. Such format values may raise an error as of Python 3.15. The workaround is to always include a year in your format. If parsing date_string values that do not have a year, explicitly add a year that is a leap year before parsing:

      >>> from datetime import date
      >>> date_string = "02/29"
      >>> when = date.strptime(f"{date_string};1984", "%m/%d;%Y")  # Avoids leap year bug.
      >>> when.strftime("%B %d")
      'February 29'

  Added in version 3.14.

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

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` | 等価性の比較。(4)
`date1 < date2` `date1 > date2` `date1 <= date2` `date1 >= date2` | 順序の比較。(5)

注釈:

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. 同じ日を表す `date` オブジェクトは等しいです。

   `datetime` のインスタンスではない `date` オブジェクトは、同じ日を表していても、`datetime` オブジェクトとは決して等価にはなりません。

5. date1 is considered less than date2 when date1 precedes date2 in time. In other words, `date1 < date2` if and only if `date1.toordinal() < date2.toordinal()`.

   Order comparison between a `date` object that is not also a `datetime` instance and a `datetime` object raises `TypeError`.

バージョン 3.13 で変更: Comparison between `datetime` object and an instance of the `date` subclass that is not a `datetime` subclass no longer converts the latter to `date`, ignoring the time part and the time zone. The default behavior can be changed by overriding the special comparison methods in subclasses.

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

インスタンスメソッド:

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

  Return a new `date` object with the same values, but with specified parameters updated.

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

      >>> from datetime import date
      >>> d = date(2002, 12, 31)
      >>> d.replace(day=26)
      datetime.date(2002, 12, 26)

  The generic function `copy.replace()` also supports `date` objects.

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

  `year`、`week`、`weekday` の3つで構成された named tuple を返します。

  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()
      datetime.IsoCalendarDate(year=2004, week=1, weekday=1)
      >>> date(2004, 1, 4).isocalendar()
      datetime.IsoCalendarDate(year=2004, week=1, weekday=7)

  バージョン 3.9 で変更: 結果が タプル から named tuple へ変更されました。

date.isoformat()

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

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

date.__str__()

  For a date `d`, `str(d)` is equivalent to `d.isoformat()`.

date.ctime()

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

      >>> from datetime import date
      >>> date(2002, 12, 4).ctime()
      'Wed Dec  4 00:00:00 2002'

  `d.ctime()` は次の式と等価です:

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

  これが等価になるのは、 (`time.ctime()` に呼び出され、 `date.ctime()` に呼び出されない) ネイティブの C 関数 `ctime()` が C 標準に準拠しているプラットフォーム上でです。

date.strftime(format)

  明示的な書式文字列で制御された、日付を表現する文字列を返します。 時間、分、秒を表す書式コードは値 0 になります。 strftime() と strptime() の振る舞い および `date.isoformat()` も参照してください。

date.__format__(format)

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

### 使用例: `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 引数は必須です。 tzinfo は `None` または `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()

  `tzinfo` が `None` である現在のローカルの日付および時刻を返します。

  次と等価です:

      datetime.fromtimestamp(time.time())

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

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

classmethod datetime.now(tz=None)

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

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

  tz が `None` でない場合、 tz は `tzinfo` のサブクラスのインスタンスでなければならず、現在の日付および時刻は tz のタイムゾーンに変換されます。

  `today()` および `utcnow()` よりもこの関数を使う方が好ましいです。

  注釈

  Subsequent calls to `datetime.now()` may return the same instant depending on the precision of the underlying clock.

classmethod datetime.utcnow()

  `tzinfo` が `None` である現在の UTC の日付および時刻を返します。

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

  警告

  naive な `datetime` オブジェクトは多くの `datetime` メソッドでローカルな時間として扱われるため、 aware な datetime を使って UTC の時刻を表すのが好ましいです。 そのため、 UTC での現在の時刻を表すオブジェクトの作成では `datetime.now(timezone.utc)` を呼び出す方法が推奨されます。

  バージョン 3.12 で非推奨: Use `datetime.now()` with `UTC` instead.

classmethod datetime.fromtimestamp(timestamp, tz=None)

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

  tz が `None` でない場合、 tz は `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にしてインスタンスを返します。

  バージョン 3.15 で変更: Accepts any real number as timestamp, not only integer or float.

classmethod datetime.utcfromtimestamp(timestamp)

  POSIX タイムスタンプに対応する、`tzinfo` が `None` の UTC での `datetime` を返します。(返されるオブジェクトは naive です。)

  タイムスタンプがプラットフォームにおける C 関数 `localtime()` でサポートされている範囲を超えている場合には `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` を含みます) をサポートします。

  警告

  naive な `datetime` オブジェクトは多くの `datetime` メソッドでローカルな時間として扱われるため、 aware な datetime を使って UTC の時刻を表すのが好ましいです。 そのため、 UTC でのある特定のタイムスタンプを表すオブジェクトの作成では `datetime.fromtimestamp(timestamp, tz=timezone.utc)` を呼び出す方法が推奨されます。

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

  バージョン 3.12 で非推奨: Use `datetime.fromtimestamp()` with `UTC` instead.

  バージョン 3.15 で変更: Accepts any real number as timestamp, not only integer or float.

classmethod datetime.fromordinal(ordinal)

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

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

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

  For any `datetime` object `d`, `d == datetime.combine(d.date(), d.time(), d.tzinfo)`.

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

classmethod datetime.fromisoformat(date_string)

  以下の例外を除く、有効な ISO 8601 フォーマットで与えられた date_string に対応する `datetime` を返します :

  1. 小数の秒があるタイムゾーンオフセット。

  2. `T` セパレーターを他の1文字のユニコードに置き換えたもの。

  3. 少数の時と分はサポートされていません。

  4. 精度の低い日付は現在サポートされていません(`YYYY-MM`, `YYYY`)。

  5. 拡張された日付表現は現在サポートされていません(`±YYYYYY-MM-DD`)。

  6. 序数の日付は現在サポートされていません(`YYYY-OOO`)。

  例:

      >>> from datetime import datetime
      >>> datetime.fromisoformat('2011-11-04')
      datetime.datetime(2011, 11, 4, 0, 0)
      >>> datetime.fromisoformat('20111104')
      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-04T00:05:23Z')
      datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)
      >>> datetime.fromisoformat('20111104T000523')
      datetime.datetime(2011, 11, 4, 0, 5, 23)
      >>> datetime.fromisoformat('2011-W01-2T00:05:23.283')
      datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)
      >>> 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)))

  Added in version 3.7.

  バージョン 3.11 で変更: Previously, this method only supported formats that could be emitted by `date.isoformat()` or `datetime.isoformat()`.

classmethod datetime.fromisocalendar(year, week, day)

  年月日で指定された ISO 暦の日付に対応する `datetime` を返します。 datetime の日付でない部分は、標準のデフォルト値で埋められます。 この関数は `datetime.isocalendar()` の逆関数です。

  Added in version 3.8.

classmethod datetime.strptime(date_string, format)

  date_string に対応した `datetime` を返します。 format にしたがって構文解析されます。

  format がマイクロ秒やタイムゾーン情報を含まない場合は、以下と等価です:

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

  date_string と format が `time.strptime()` で構文解析できない場合や、この関数が時刻タプルを返してこない場合には `ValueError` を送出します。strftime() と strptime() の振る舞い および `datetime.fromisoformat()` も参照してください。

  バージョン 3.13 で変更: If format specifies a day of month without a year a `DeprecationWarning` is now emitted. This is to avoid a quadrennial leap year bug in code seeking to parse only a month and day as the default year used in absence of one in the format is not a leap year. Such format values may raise an error as of Python 3.15. The workaround is to always include a year in your format. If parsing date_string values that do not have a year, explicitly add a year that is a leap year before parsing:

      >>> from datetime import datetime
      >>> date_string = "02/29"
      >>> when = datetime.strptime(f"{date_string};1984", "%m/%d;%Y")  # Avoids leap year bug.
      >>> when.strftime("%B %d")
      'February 29'

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

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

  `[0, 1]` のどちらかです。 繰り返し期間中の実時間の曖昧さ除去に使われます。 (繰り返し期間は、夏時間の終わりに時計が巻き戻るときや、現在のゾーンの UTC オフセットが政治的な理由で減少するときに発生します。) 0または1という値は、同じ実時間で表現される 2 つの時刻のうちのそれぞれ早い方または遅い方を表します。

  Added in version 3.6.

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

演算 | 結果
--- | ---
`datetime2 = datetime1 + timedelta` | (1)
`datetime2 = datetime1 - timedelta` | (2)
`timedelta = datetime1 - datetime2` | (3)
`datetime1 == datetime2` `datetime1 != datetime2` | 等価性の比較。(4)
`datetime1 < datetime2` `datetime1 > datetime2` `datetime1 <= datetime2` `datetime1 >= datetime2` | 順序の比較。(5)

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` が送出されます。

   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. The result is `(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset())` except that the implementation never overflows.

4. `datetime` オブジェクトはタイムゾーンを考慮して同じ日付と時刻を表す場合、等しいです。

   Naive and aware `datetime` objects are never equal.

   If both comparands are aware, and have the same `tzinfo` attribute, the `tzinfo` and `fold` attributes are ignored and the base datetimes are compared. If both comparands are aware and have different `tzinfo` attributes, the comparison acts as comparands were first converted to UTC datetimes except that the implementation never overflows. `datetime` instances in a repeated interval are never equal to `datetime` instances in other time zone.

5. タイムゾーンを考慮して、datetime1 が時刻として datetime2 よりも前を表す場合に、datetime1 は datetime2 よりも小さいと見なされます。

   Order comparison between naive and aware `datetime` objects raises `TypeError`.

   If both comparands are aware, and have the same `tzinfo` attribute, the `tzinfo` and `fold` attributes are ignored and the base datetimes are compared. If both comparands are aware and have different `tzinfo` attributes, the comparison acts as comparands were first converted to UTC datetimes except that the implementation never overflows.

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

バージョン 3.13 で変更: Comparison between `datetime` object and an instance of the `date` subclass that is not a `datetime` subclass no longer converts the latter to `date`, ignoring the time part and the time zone. The default behavior can be changed by overriding the special comparison methods in subclasses.

インスタンスメソッド:

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)

  Return a new `datetime` object with the same attributes, but with specified parameters updated. Note that `tzinfo=None` can be specified to create a naive datetime from an aware datetime with no conversion of date and time data.

  `datetime` オブジェクトは汎用的な関数 `copy.replace()` にもサポートされています。

  バージョン 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 を持つことを示します。

  単に `timezone` オブジェクト tz を `datetime` オブジェクト dt に追加したいだけで、日付や時刻データへの調整を行わないのなら、`dt.replace(tzinfo=tz)` を使ってください。単に aware な `datetime` オブジェクト dt から `timezone` オブジェクトを除去したいだけで、日付や時刻データの変換を行わないのなら、`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 timezone 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()

  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.

  警告

  naive な `datetime` オブジェクトは多くの `datetime` メソッドでローカルな時間として扱われるため、 aware な datetime を使って UTC の時刻を表すのが好ましいです。結果として、 `datetime.utctimetuple()` は誤解を招きやすい返り値を返すかもしれません。 UTC を表す naive な `datetime` があった場合、 `datetime.timetuple()` が使えるところでは `datetime.replace(tzinfo=timezone.utc)` で aware にします。

datetime.toordinal()

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

datetime.timestamp()

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

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

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

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

  Added in version 3.3.

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

  バージョン 3.6 で変更: This method no longer relies on the platform C `mktime()` function to perform conversions.

  注釈

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

  `year`、`week`、`weekday` の3つで構成された named tuple を返します。 `self.date().isocalendar()` と等価です。

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

  日時を ISO 8601 書式で表した文字列で返します:

  - `microsecond` が 0 でない場合は `YYYY-MM-DDTHH:MM:SS.ffffff`

  - `microsecond` が 0 の場合は `YYYY-MM-DDTHH:MM:SS`

  `utcoffset()` が `None` を返さない場合は、文字列の後ろに UTC オフセットが追記されます:

  - `microsecond` が 0 でない場合は `YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]`

  - `microsecond` が 0 の場合は `YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]`

  例:

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

  オプションの引数 sep (デフォルトでは `'T'` です) は 1 文字のセパレータで、結果の文字列の日付と時刻の間に置かれます。例えば:

      >>> 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'`: `hour` を2桁の `HH` 書式で含めます。

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

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

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

  - `'microseconds'`: 全ての時刻を `HH:MM:SS.mmmmmm` の書式で含めます。

  注釈

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

  不正な 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__()

  For a `datetime` instance `d`, `str(d)` is equivalent to `d.isoformat(' ')`.

datetime.ctime()

  日付および時刻を表す文字列を返します:

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

  出力文字列は入力が aware であれ naive であれ、タイムゾーン情報を含み ません。

  `d.ctime()` は次の式と等価です:

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

  これが等価になるのは、 (`time.ctime()` に呼び出され、 `datetime.ctime()` に呼び出されない) ネイティブの C 関数 `ctime()` が C 標準に準拠しているプラットフォーム上でです。

datetime.strftime(format)

  明示的な書式文字列で制御された、日付および時刻を表現する文字列を返します。strftime() と strptime() の振る舞い および `datetime.isoformat()` も参照してください。

datetime.__format__(format)

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

### 使用例: `datetime`

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

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

下にある例では、1945年までは +4 UTC 、それ以降は +4:30 UTC を使用しているアフガニスタンのカブールのタイムゾーン情報を表現する `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):
                # 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"

上に出てきた `KabulTz` の使い方:

    >>> 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` オブジェクト

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

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

  全ての引数はオプションです。 tzinfo は `None` または `tzinfo` クラスのサブクラスのインスタンスにすることができます。残りの引数は整数で、以下のような範囲に入らなければなりません:

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

  `[0, 1]` のどちらかです。 繰り返し期間中の実時間の曖昧さ除去に使われます。 (繰り返し期間は、夏時間の終わりに時計が巻き戻るときや、現在のゾーンの UTC オフセットが政治的な理由で減少するときに発生します。) 0または1という値は、同じ実時間で表現される 2 つの時刻のうちのそれぞれ早い方または遅い方を表します。

  Added in version 3.6.

`time` objects support equality and order comparisons, where `a` is considered less than `b` when `a` precedes `b` in time.

Naive and aware `time` objects are never equal. Order comparison between naive and aware `time` objects raises `TypeError`.

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

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

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

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

Other constructors:

classmethod time.fromisoformat(time_string)

  以下の例外を除く、有効な ISO 8601 フォーマットで与えられた time_string に対応する `time` を返します :

  1. 小数の秒があるタイムゾーンオフセット。

  2. The leading `T`, normally required in cases where there may be ambiguity between a date and a time, is not required.

  3. Fractional seconds may have any number of digits (anything beyond 6 will be truncated).

  4. 少数の時と分はサポートされていません。

  例:

      >>> from datetime import time
      >>> time.fromisoformat('04:23:01')
      datetime.time(4, 23, 1)
      >>> time.fromisoformat('T04:23:01')
      datetime.time(4, 23, 1)
      >>> time.fromisoformat('T042301')
      datetime.time(4, 23, 1)
      >>> time.fromisoformat('04:23:01.000384')
      datetime.time(4, 23, 1, 384)
      >>> 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)))
      >>> time.fromisoformat('04:23:01Z')
      datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
      >>> time.fromisoformat('04:23:01+00:00')
      datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)

  Added in version 3.7.

  バージョン 3.11 で変更: Previously, this method only supported formats that could be emitted by `time.isoformat()`.

classmethod time.strptime(date_string, format)

  Return a `time` corresponding to date_string, parsed according to format.

  format がマイクロ秒やタイムゾーン情報を含まない場合は、以下と等価です:

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

  `ValueError` is raised if the date_string and format cannot be parsed by `time.strptime()` or if it returns a value which is not a time tuple. See also strftime() と strptime() の振る舞い and `time.fromisoformat()`.

  Added in version 3.14.

インスタンスメソッド:

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

  Return a new `time` with the same values, but with specified parameters updated. Note that `tzinfo=None` can be specified to create a naive `time` from an aware `time`, without conversion of the time data.

  `time` オブジェクトは汎用的な関数 `copy.replace()` にもサポートされています。

  バージョン 3.6 で変更: fold パラメータが追加されました。

time.isoformat(timespec='auto')

  時刻を ISO 8601 書式で表した次の文字列のうち1つを返します:

  - `microsecond` が 0 でない場合は `HH:MM:SS.ffffff`

  - `microsecond` が 0 の場合は `HH:MM:SS`

  - `utcoffset()` が `None` を返さない場合、 `HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]`

  - `microsecond` が 0 で `utcoffset()` が `None` を返さない場合、 `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'`: 全ての時刻を `HH:MM:SS.mmmmmm` の書式で含めます。

  注釈

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

  不正な 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__()

  For a time `t`, `str(t)` is equivalent to `t.isoformat()`.

time.strftime(format)

  明示的な書式文字列で制御された、時刻を表現する文字列を返します。strftime() と strptime() の振る舞い および `time.isoformat()` も参照してください。

time.__format__(format)

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

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` か文字列オブジェクトのいずれかを返さない場合には例外を送出します。

### 使用例: `time`

`time` オブジェクトを使う例:

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

  このクラスは抽象基底クラスで、直接インスタンス化すべきでないことを意味します。 `tzinfo` のサブクラスを定義し、ある特定のタイムゾーンに関する情報を保持するようにしてください。

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

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

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

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

tzinfo.utcoffset(dt)

  ローカル時間の UTC からのオフセットを、 UTC から東向きを正とした `timedelta` オブジェクトで返します。ローカル時間が UTC の西側にある場合、この値は負になります。

  このメソッドは UTC からのオフセットの 総計 を表しています。例えば、 `tzinfo` オブジェクトがタイムゾーンと DST 修正の両方を表現する場合、 `utcoffset()` はそれらの合計を返さなければなりません。 UTC オフセットが未知である場合、 `None` を返します。 そうでない場合には、返される値は `-timedelta(hours=24)` から `timedelta(hours=24)` までの `timedelta` 境界を含まないオブジェクトでなければなりません (オフセットの大きさは 1 日より短くなければなりません)。 ほとんどの `utcoffset()` 実装は、おそらく以下の二つのうちの一つに似たものになるでしょう:

      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)

  夏時間 (DST) 修正を、 `timedelta` オブジェクトで返します。 DST 情報が未知の場合、 `None` が返されます。

  DST が有効でない場合には `timedelta(0)` を返します。 DST が有効の場合、オフセットは `timedelta` オブジェクトで返します (詳細は `utcoffset()` を参照してください)。 DST オフセットが利用可能な場合、この値は `utcoffset()` が返す UTC からのオフセットには既に加算されているため、 DST を個別に取得する必要がない限り `dst()` を使って問い合わせる必要はないので注意してください。 例えば、 `datetime.timetuple()` は `tzinfo` 属性の `dst()` メソッドを呼んで `tm_isdst` フラグがセットされているかどうか判断し、 `tzinfo.fromutc()` は `dst()` タイムゾーンを移動する際に DST による変更があるかどうかを調べます。

  標準および夏時間の両方をモデル化している `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.

          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()` から呼ばれた場合、 `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
    # https://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 という形式の実時間は意味をなさないので、 DST が始まった日に `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()` は 2 つの隣り合う 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

`fold` 属性が異なるだけの `datetime` インスタンスは比較において等しいとみなされることに注意してください。

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

参考

> `zoneinfo`

>   `datetime` モジュールには (UTC からの任意の固定オフセットを扱う) 基本的な `timezone` クラスと、(UTC `timezone` のインスタンスである) `timezone.utc` 属性があります。

>   `zoneinfo` は Python に IANA タイムゾーンデータベース (オルソンデータベースとしても知られています) を導入するもので、これを使うことが推奨されています。

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

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

## `timezone` オブジェクト

`timezone` クラスは `tzinfo` のサブクラスで、各インスタンスは UTC からの固定されたオフセットで定義されたタイムゾーンを表しています。

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

class datetime.timezone(offset[, name])

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

  name 引数は必須ではありません。もし指定された場合、その値は `datetime.tzname()` メソッドの返り値として使われる文字列でなければなりません。

  Added in version 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)` メソッドをサポートし、時刻を表現する文字列を明示的な書式文字列で統制して作成しています。

Conversely, the `date.strptime()`, `datetime.strptime()` and `time.strptime()` class methods create an object from a string representing the time and a corresponding format string.

下の表は `strftime()` と `strptime()` との高レベルの対比を表しています。

| `strftime` | `strptime`
--- | --- | ---
使用法 | オブジェクトを与えられた書式に従って文字列に変換する | Parse a string into an object given a corresponding format
メソッドの種類 | インスタンスメソッド | クラスメソッド
シグネチャ | `strftime(format)` | `strptime(date_string, format)`

### `strftime()` と `strptime()` の書式コード

These methods accept format codes that can be used to parse and format dates:

    >>> datetime.strptime('31/01/22 23:59:59.999999',
    ...                   '%d/%m/%y %H:%M:%S.%f')
    datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)
    >>> _.strftime('%a %d %b %Y, %I:%M%p')
    'Mon 31 Jan 2022, 11:59PM'

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

ディレクティブ | 意味 | 使用例 | 注釈
--- | --- | --- | ---
`%a` | ロケールの曜日名を短縮形で表示します。 | Sun, Mon, ..., Sat (en_US); So, Mo, ..., Sa (de_DE) | (1)
`%A` | ロケールの曜日名を表示します。 | Sunday, Monday, ..., Saturday (en_US); Sonntag, Montag, ..., Samstag (de_DE) | (1)
`%b` | ロケールの月名を短縮形で表示します。 | Jan, Feb, ..., Dec (en_US); Jan, Feb, ..., Dez (de_DE) | (1)
`%B` | ロケールの月名を表示します。 | January, February, ..., December (en_US); Januar, Februar, ..., Dezember (de_DE) | (1)
`%c` | ロケールの日時を適切な形式で表します。 | Tue Aug 16 21:30:00 1988 (en_US); Di 16 Aug 21:30:00 1988 (de_DE) | (1)
`%C` | The year divided by 100 and truncated to an integer as a zero-padded decimal number. | 01, 02, ..., 99 | (0)
`%d` | 0埋めした10進数で表記した月中の日にち。 | 01, 02, ..., 31 | (9)
`%D` | Equivalent to `%m/%d/%y`. | 11/10/2025 | (9), (0)
`%e` | The day of the month as a space-padded decimal number. | ␣1, ␣2, ..., 31 |
`%F` | Equivalent to `%Y-%m-%d`, the ISO 8601 format. | 2025-10-11, 1001-12-30 | (0)
`%g` | Last 2 digits of ISO 8601 year representing the year that contains the greater part of the ISO week (`%V`). | 00, 01, ..., 99 | (0)
`%G` | ISO week(`%V`)の内過半数を含む西暦表記の ISO 8601 year です。 | 0001, 0002, ..., 2013, 2014, ..., 9998, 9999 | (8)
`%h` | Equivalent to `%b`. | See `%b`. | (0)
`%H` | 0埋めした10進数で表記した時 (24時間表記)。 | 00, 01, ..., 23 | (9)
`%I` | 0埋めした10進数で表記した時 (12時間表記)。 | 01, 02, ..., 12 | (9)
`%j` | 0埋めした10進数で表記した年中の日にち。 | 001, 002, ..., 366 | (9)
`%m` | 0埋めした10進数で表記した月。 | 01, 02, ..., 12 | (9)
`%M` | 0埋めした10進数で表記した分。 | 00, 01, ..., 59 | (9)
`%n` | The newline character (`'\n'`). | `\n` | (0)
`%p` | ロケールの AM もしくは PM と等価な文字列になります。 | AM, PM (en_US); am, pm (de_DE) | (1), (3)
`%r` | Locale's 12-hour clock time. | 12:00:00 AM | (1), (0)
`%R` | Equivalent to `%H:%M`. | 10:01 |
`%S` | 0埋めした10進数で表記した秒。 | 00, 01, ..., 59 | (4), (9)
`%t` | The tab character (`'\t'`). | `\t` | (0)
`%T` | ISO 8601 time format, equivalent to `%H:%M:%S`. | 10:01:59 |
`%u` | 1 を月曜日を表す 10進数表記の ISO 8601 weekday です。 | 1, 2, ..., 7 |
`%U` | 0埋めした10進数で表記した年中の週番号 (週の始まりは日曜日とする)。新年の最初の日曜日に先立つ日は 0週に属するとします。 | 00, 01, ..., 53 | (7), (9)
`%V` | 週で最初の月曜日を始めとする ISO 8601 week です。Week 01 は 1月4日を含みます。 | 01, 02, ..., 53 | (8), (9)
`%w` | 曜日を10進表記した文字列を表示します。0 が日曜日で、6 が土曜日を表します。 | 0, 1, ..., 6 |
`%W` | 0埋めした10進数で表記した年中の週番号 (週の始まりは月曜日とする)。新年の最初の月曜日に先立つ日は 0週に属するとします。 | 00, 01, ..., 53 | (7), (9)
`%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)
`%y` | 0埋めした10進数で表記した世紀無しの年。 | 00, 01, ..., 99 | (9)
`%Y` | 西暦 ( 4桁) の 10 進表記を表します。 | 0001, 0002, ..., 2013, 2014, ..., 9998, 9999 | (2)
`%z` | UTCオフセットを `±HHMM[SS[.ffffff]]` の形式で表示します (オブジェクトがnaiveであれば空文字列)。 | (空文字列), +0000, -0400, +1030, +063415, -030712.345216 | (6)
`%Z` | タイムゾーンの名前を表示します (オブジェクトがnaiveであれば空文字列)。 | (空文字列), UTC, GMT | (6)
`%%` | 文字 `'%'` を表します。 | % |

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

Several additional directives not required by the C11 standard are included for convenience.

ディレクティブ | 意味 | 使用例 | 注釈
--- | --- | --- | ---
`%f` | 10進数で表記したマイクロ秒 (6桁に0埋めされます)。 | 000000, 000001, ..., 999999 | (5)
`%:z` | UTCオフセットを `±HH:MM[:SS[.ffffff]]` の形式で表示します (オブジェクトがnaiveであれば空文字列)。 | (空文字列), +00:00, -04:00, +10:30, +06:34:15, -03:07:12.345216 | (6)

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

Added in version 3.6: `%G`, `%u` および `%V` が追加されました。

Added in version 3.12: `%:z` was added for `strftime()`

Added in version 3.15: `%:z` was added for `strptime()`

### 技術詳細

大雑把にいうと、 `d.strftime(fmt)` は `time` モジュールの `time.strftime(fmt, d.timetuple())` のように動作します。ただし全てのオブジェクトが `timetuple()` メソッドをサポートしているわけではありません。

For the `datetime.strptime()` and `date.strptime()` class methods, 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.

注釈

When used to parse partial dates lacking a year, `datetime.strptime()` and `date.strptime()` will raise when encountering February 29 because the default year of 1900 is not a leap year. Always add a default leap year to partial date strings before parsing.

    >>> from datetime import datetime
    >>> value = "2/29"
    >>> datetime.strptime(value, "%m/%d")
    Traceback (most recent call last):
    ...
    ValueError: day 29 must be in range 1..28 for month 2 in year 1900
    >>> datetime.strptime(f"1904 {value}", "%Y %m/%d")
    datetime.datetime(1904, 2, 29, 0, 0)

`datetime.strptime(date_string, format)` は次の式と等価です:

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

ただし、 `datetime.strptime` はサポートしているが `time.strptime` には無い、秒未満の単位やタイムゾーンオフセットの情報が format に 含まれているときは除きます。

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

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

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

注釈:

0. This format code is currently unsupported by `strptime()`.

1. Because the format depends on the current locale, care should be taken when making assumptions about the output value. Field orderings will vary (for example, "month/day/year" versus "day/month/year"), and the output may contain non-ASCII characters.

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 標準規格の書式文字セットの拡張です (とは言え、 datetime モジュールのオブジェクトそれぞれに実装されているので、どれででも使えます)。

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

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

   `%z`

     `utcoffset()` は `±HHMM[SS[.ffffff]]` 形式の文字列に変換されます。ここで、 `HH` は UTC オフセットの時間を表す 2 桁の文字列、 `MM` は UTC オフセットの分数を表す 2 桁の文字列、 `SS` は UTC オフセットの秒数を表す 2 桁の文字列、 `ffffff` は UTC オフセットのマイクロ秒数を表す 6 桁の文字列です。 オフセットに秒未満の端数が無いときは `ffffff` 部分は省略され、オフセットに分未満の端数が無いときは `ffffff` 部分も `SS` 部分も省略されます。 例えば、 `utcoffset()` が `timedelta(hours=-3, minutes=-30)` を返す場合、 `%z` は文字列 `'-0330'` に置き換えられます。

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

   バージョン 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, both `'+010000'` and `'+01:00:00'` will be parsed as an offset of one hour. In addition, providing `'Z'` is identical to `'+00:00'`.

   `%:z`

     When used with `strftime()`, behaves exactly as `%z`, except that a colon separator is added between hours, minutes and seconds.

     When used with `strptime()`, the UTC offset is required to have a colon as a separator between hours, minutes and seconds. For example, `'+01:00:00'` (but not `'+010000'`) will be parsed as an offset of one hour. In addition, providing `'Z'` is identical to `'+00:00'`.

   `%Z`

     In `strftime()`, `%Z` is replaced by an empty string if `tzname()` returns `None`; otherwise `%Z` is replaced by the returned value, which must be a string.

     `strptime()` は `%Z` に特定の値のみを受け入れます:

     1. 使用しているマシンのロケールによる `time.tzname` の任意の値

     2. ハードコードされた値 `UTC` または `GMT`

     つまり、日本に住んでいる場合は `JST`, `UTC` と `GMT` が有効な値であり、 `EST` はおそらく無効な値となります。無効な値の場合は `ValueError` を送出します。

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

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

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

9. `strptime()` メソッドと共に使われるとき、書式 `%d`, `%m`, `%H`, `%I`, `%M`, `%S`, `%j`, `%U`, `%W`, `%V` では先行ゼロは任意です。 書式 `%y` では先行ゼロは必須です。

10. When parsing a month and day using `strptime()`, always include a year in the format. If the value you need to parse lacks a year, append an explicit dummy leap year. Otherwise your code will raise an exception when it encounters leap day because the default year used by the parser (1900) is not a leap year. Users run into that bug every leap year.

        >>> month_day = "02/29"
        >>> datetime.strptime(f"{month_day};1984", "%m/%d;%Y")  # No leap year bug.
        datetime.datetime(1984, 2, 29, 0, 0)

    Deprecated since version 3.13, removed in version 3.15: `strptime()` calls using a format string containing a day of month without a year now emit a `DeprecationWarning`. In 3.15 or later we may change this into an error or change the default year to a leap year. See gh-70647.

脚注

[1]

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

[2]

この暦法は、全ての計算における基本カレンダーである、 Dershowitz と Reingold の書籍 Calendrical Calculations における先発グレゴリオ暦 ("proleptic Gregorian") の定義に一致します。 先発グレゴリオ暦の序数とその他多くの暦法どうしの変換アルゴリズムについては、この書籍を参照してください。

[3]

優れた説明は R. H. van Gent の guide to the mathematics of the ISO 8601 calendar を参照してください。