"datetime" --- Basic date and time types
****************************************

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

======================================================================

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

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

Tip:

  書式コード に飛ぶ。

参考:

  "calendar" モジュール
     汎用のカレンダー関連関数。

  "time" モジュール
     時刻へのアクセスと変換。

  "zoneinfo" モジュール
     IANAタイムゾーンデータベースを表す具体的なタイムゾーン。

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

  Package 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

   The smallest year number allowed in a "date" or "datetime" object.
   "MINYEAR" is 1.

datetime.MAXYEAR

   The largest year number allowed in a "date" or "datetime" object.
   "MAXYEAR" is 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)

   All arguments are optional and default to 0. Arguments may be
   integers or floats, and may be positive or negative.

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

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

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

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

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

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

   * "0 <= microseconds < 1000000"

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

   * "-999999999 <= days <= 999999999"

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

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

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

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

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

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

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

timedelta.min

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

timedelta.max

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

timedelta.resolution

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

Note that, because of normalization, "timedelta.max" is greater than
"-timedelta.min". "-timedelta.max" is not representable as a
"timedelta" object.

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

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

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

+----------------------------------+-------------------------------------------------+
| 演算                             | 結果                                            |
|==================================|=================================================|
| "t1 = t2 + t3"                   | Sum of "t2" and "t3". Afterwards "t1 - t2 ==    |
|                                  | t3" and "t1 - t3 == t2" are true. (1)           |
+----------------------------------+-------------------------------------------------+
| "t1 = t2 - t3"                   | Difference of "t2"  and "t3". Afterwards "t1 == |
|                                  | t2 - t3" and "t2 == t1 + t3" are true. (1)(6)   |
+----------------------------------+-------------------------------------------------+
| "t1 = t2 * i または t1 = i * t2" | Delta multiplied by an integer. Afterwards "t1  |
|                                  | // i == t2" is true, provided "i != 0".         |
+----------------------------------+-------------------------------------------------+
|                                  | In general, "t1  * i == t1 * (i-1) + t1" is     |
|                                  | true. (1)                                       |
+----------------------------------+-------------------------------------------------+
| "t1 = t2 * f" または "t1 = f *   | 時間差と浮動小数点の積。結果は最近接偶数への丸  |
| t2"                              | めを利用して最も近い timedelta.resolution の倍  |
|                                  | 数に丸められます。                              |
+----------------------------------+-------------------------------------------------+
| "f = t2 / t3"                    | Division (3) of overall duration "t2" by        |
|                                  | interval unit "t3". Returns a "float" object.   |
+----------------------------------+-------------------------------------------------+
| "t1 = t2 / f" または "t1 = t2 /  | 時間差を浮動小数点や整数で除したもの。結果は最  |
| i"                               | 近接偶数への丸めを利用し て最も近い             |
|                                  | timedelta.resolution の倍数に丸められます。     |
+----------------------------------+-------------------------------------------------+
| "t1 = t2 // i" または "t1 = t2   | floor が計算され、余りは (もしあれば) 捨てられ  |
| // t3"                           | ます。後者の場合、整数が 返されます。(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"                            | Equivalent to "timedelta(-t1.days,              |
|                                  | -t1.seconds*, -t1.microseconds)", and to "t1 *  |
|                                  | -1". (1)(4)                                     |
+----------------------------------+-------------------------------------------------+
| "abs(t)"                         | Equivalent to "+t" when "t.days >= 0", and to   |
|                                  | "-t" when "t.days < 0". (2)                     |
+----------------------------------+-------------------------------------------------+
| "str(t)"                         | "[D day[s], ][H]H:MM:SS[.UUUUUU]" という形式の  |
|                                  | 文字列を返します。"t" が 負の値の場合は "D" は  |
|                                  | 負の値となります。(5)                           |
+----------------------------------+-------------------------------------------------+
| "repr(t)"                        | "timedelta" オブジェクトの文字列表現を返します  |
|                                  | 。その文字列は、正規の属 性値を持つコンストラク |
|                                  | タ呼び出しのコードになっています。              |
+----------------------------------+-------------------------------------------------+

注釈:

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

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

3. Division by zero raises "ZeroDivisionError".

4. "-timedelta.max" is not representable as a "timedelta" object.

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

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. Reduced precision dates are not currently supported ("YYYY-MM",
      "YYYY").

   2. Extended date representations are not currently supported
      ("±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.

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

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" will be "timedelta.days" days after    |
|                                 | "date1". (1)                                   |
+---------------------------------+------------------------------------------------+
| "date2 = date1 - timedelta"     | Computes "date2" such that "date2 + timedelta  |
|                                 | == date1". (2)                                 |
+---------------------------------+------------------------------------------------+
| "timedelta = date1 - date2"     | (3)                                            |
+---------------------------------+------------------------------------------------+
| "date1 == date2" "date1 !=      | 等価性の比較。(4)                              |
| date2"                          |                                                |
+---------------------------------+------------------------------------------------+
| "date1 < date2" "date1 > date2" | 順序の比較。(5)                                |
| "date1 <= date2" "date1 >=      |                                                |
| date2"                          |                                                |
+---------------------------------+------------------------------------------------+

注釈:

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. This is exact, and cannot overflow. "timedelta.seconds" and
   "timedelta.microseconds" are 0, and "date2 + timedelta == date1"
   after.

4. 同じ日を表す "date" オブジェクトは等しいです。

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

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

インスタンスメソッド:

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

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

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

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

date.timetuple()

   "time.localtime()" が返すような "time.struct_time" を返します。

   時分秒が 0 で、 DST フラグが -1 です。

   "d.timetuple()" は次の式と等価です:

      time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))

   where "yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1"
   is the day number within the current year starting with 1 for
   January 1st.

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

   "date" オブジェクト *d* において、"str(d)" は "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()" よりもこの関数を使う方が好ましいです。

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 で非推奨: 代わりに "UTC" で "datetime.now()" を使用
   してください。

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にしてインス
   タンスを返します。

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 で非推奨: 代わりに "UTC" で
   "datetime.fromtimestamp()" を使用してください。

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" 属性は無視されます。

   任意の "datetime" オブジェクト *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. Reduced precision dates are not currently supported ("YYYY-MM",
      "YYYY").

   5. Extended date representations are not currently supported
      ("±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 で変更: 以前は、このメソッドは "date.isoformat()"
   または "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()" も参照してください。

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

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 values 0 and
   1 represent, respectively, the earlier and later of the two moments
   with the same wall time representation.

   Added in version 3.6.

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

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

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

2. Computes the "datetime2" such that "datetime2 + timedelta ==
   datetime1". As for addition, the result has the same "tzinfo"
   attribute as the input datetime, and no time zone adjustments are
   done even if the input is 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. "datetime" オブジェクトはタイムゾーンを考慮して同じ日付と時刻を表す
   場合、等しいです。

   Naive and aware "datetime" objects are never equal. "datetime"
   objects are never equal to "date" objects that are not also
   "datetime" instances, even if they represent the same date.

   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, as
   well as a "datetime" object and a "date" object that is not also a
   "datetime" instance, 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" は送出されません。

インスタンスメソッド:

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

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

datetime.utctimetuple()

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

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

   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.

   注釈:

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

   "datetime" オブジェクト *d* において、 "str(d)" は "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]".

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

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

time.min

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

time.max

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

time.resolution

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

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

time.hour

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

time.minute

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

time.second

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

time.microsecond

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

time.tzinfo

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

time.fold

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

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

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

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

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

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

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

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 で変更: 以前は、このメソっどは "time.isoformat()"
   から出力されるフォーマットのみをサポートしていました。

インスタンスメソッド:

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

   時刻を 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__()

   "time" オブジェクト *t* において、"str(t)" は "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) 修正を、 class:*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)"

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

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

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

   もしくは:

      def dst(self, dt):
          # Code to set dston and dstoff to the time zone's DST
          # transition times based on the input dt.year, and expressed
          # in standard local time.

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

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

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

tzinfo.tzname(dt)

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

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

以下のメソッドは "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
   # 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.utc" 属性があります。

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

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

逆に "datetime.strptime()" クラスメソッドは日付や時刻に対応する書式文
字列から "datetime" オブジェクトを生成します。

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

+------------------+----------------------------------------------------------+--------------------------------------------------------------------------------+
|                  | "strftime"                                               | "strptime"                                                                     |
|==================|==========================================================|================================================================================|
| 使用法           | オブジェクトを与えられた書式に従って文字列に変換する     | 指定された対応する書式で文字列を構文解析して "datetime" オブジェクトに する    |
+------------------+----------------------------------------------------------+--------------------------------------------------------------------------------+
| メソッドの種類   | インスタンスメソッド                                     | クラスメソッド                                                                 |
+------------------+----------------------------------------------------------+--------------------------------------------------------------------------------+
| メソッドを持つク | "date"; "datetime"; "time"                               | "datetime"                                                                     |
| ラス             |                                                          |                                                                                |
+------------------+----------------------------------------------------------+--------------------------------------------------------------------------------+
| シグネチャ       | "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'

以下のリストは 1989 C 標準が要求する全ての書式コードで、標準 C 実装が
あれば全ての環境で動作します。

+-------------+----------------------------------+--------------------------+---------+
| ディレクテ  | 意味                             | 使用例                   | 注釈    |
| ィブ        |                                  |                          |         |
|=============|==================================|==========================|=========|
| "%a"        | ロケールの曜日名を短縮形で表示し | Sun, Mon, ..., Sat       | (1)     |
|             | ます。                           | (en_US); So, Mo, ..., Sa |         |
|             |                                  | (de_DE)                  |         |
+-------------+----------------------------------+--------------------------+---------+
| "%A"        | ロケールの曜日名を表示します。   | Sunday, Monday, ...,     | (1)     |
|             |                                  | Saturday (en_US);        |         |
|             |                                  | Sonntag, Montag, ...,    |         |
|             |                                  | Samstag (de_DE)          |         |
+-------------+----------------------------------+--------------------------+---------+
| "%w"        | 曜日を10進表記した文字列を表示し | 0, 1, ..., 6             |         |
|             | ます。0 が日曜日で、6 が土曜日を |                          |         |
|             | 表しま す。                      |                          |         |
+-------------+----------------------------------+--------------------------+---------+
| "%d"        | 0埋めした10進数で表記した月中の  | 01, 02, ..., 31          | (9)     |
|             | 日にち。                         |                          |         |
+-------------+----------------------------------+--------------------------+---------+
| "%b"        | ロケールの月名を短縮形で表示しま | Jan, Feb, ..., Dec       | (1)     |
|             | す。                             | (en_US); Jan, Feb, ...,  |         |
|             |                                  | Dez (de_DE)              |         |
+-------------+----------------------------------+--------------------------+---------+
| "%B"        | ロケールの月名を表示します。     | January, February, ...,  | (1)     |
|             |                                  | December (en_US);        |         |
|             |                                  | Januar, Februar, ...,    |         |
|             |                                  | Dezember (de_DE)         |         |
+-------------+----------------------------------+--------------------------+---------+
| "%m"        | 0埋めした10進数で表記した月。    | 01, 02, ..., 12          | (9)     |
+-------------+----------------------------------+--------------------------+---------+
| "%y"        | 0埋めした10進数で表記した世紀無  | 00, 01, ..., 99          | (9)     |
|             | しの年。                         |                          |         |
+-------------+----------------------------------+--------------------------+---------+
| "%Y"        | 西暦 ( 4桁) の 10 進表記を表しま | 0001, 0002, ..., 2013,   | (2)     |
|             | す。                             | 2014, ..., 9998, 9999    |         |
+-------------+----------------------------------+--------------------------+---------+
| "%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   | (1),    |
|             | な文字列になります。             | (de_DE)                  | (3)     |
+-------------+----------------------------------+--------------------------+---------+
| "%M"        | 0埋めした10進数で表記した分。    | 00, 01, ..., 59          | (9)     |
+-------------+----------------------------------+--------------------------+---------+
| "%S"        | 0埋めした10進数で表記した秒。    | 00, 01, ..., 59          | (4),    |
|             |                                  |                          | (9)     |
+-------------+----------------------------------+--------------------------+---------+
| "%f"        | 10進数で表記したマイクロ秒 (6桁  | 000000, 000001, ...,     | (5)     |
|             | に0埋めされます)。               | 999999                   |         |
+-------------+----------------------------------+--------------------------+---------+
| "%z"        | UTCオフセットを                  | (空文字列), +0000,       | (6)     |
|             | "±HHMM[SS[.ffffff]]" の形式で表  | -0400, +1030, +063415,   |         |
|             | 示します (オブジェクト がnaiveで | -030712.345216           |         |
|             | あれば空文字列)。                |                          |         |
+-------------+----------------------------------+--------------------------+---------+
| "%Z"        | タイムゾーンの名前を表示します ( | (空文字列), UTC, GMT     | (6)     |
|             | オブジェクトがnaiveであれば空文  |                          |         |
|             | 字列)。                          |                          |         |
+-------------+----------------------------------+--------------------------+---------+
| "%j"        | 0埋めした10進数で表記した年中の  | 001, 002, ..., 366       | (9)     |
|             | 日にち。                         |                          |         |
+-------------+----------------------------------+--------------------------+---------+
| "%U"        | 0埋めした10進数で表記した年中の  | 00, 01, ..., 53          | (7),    |
|             | 週番号 (週の始まりは日曜日とする |                          | (9)     |
|             | )。新年 の最初の日曜日に先立つ日 |                          |         |
|             | は 0週に属するとします。         |                          |         |
+-------------+----------------------------------+--------------------------+---------+
| "%W"        | 0埋めした10進数で表記した年中の  | 00, 01, ..., 53          | (7),    |
|             | 週番号 (週の始まりは月曜日とする |                          | (9)     |
|             | )。新年 の最初の月曜日に先立つ日 |                          |         |
|             | は 0週に属するとします。         |                          |         |
+-------------+----------------------------------+--------------------------+---------+
| "%c"        | ロケールの日時を適切な形式で表し | Tue Aug 16 21:30:00 1988 | (1)     |
|             | ます。                           | (en_US); Di 16 Aug       |         |
|             |                                  | 21:30:00 1988 (de_DE)    |         |
+-------------+----------------------------------+--------------------------+---------+
| "%x"        | ロケールの日付を適切な形式で表し | 08/16/88 (None);         | (1)     |
|             | ます。                           | 08/16/1988 (en_US);      |         |
|             |                                  | 16.08.1988 (de_DE)       |         |
+-------------+----------------------------------+--------------------------+---------+
| "%X"        | ロケールの時間を適切な形式で表し | 21:30:00 (en_US);        | (1)     |
|             | ます。                           | 21:30:00 (de_DE)         |         |
+-------------+----------------------------------+--------------------------+---------+
| "%%"        | 文字 "'%'" を表します。          | %                        |         |
+-------------+----------------------------------+--------------------------+---------+

C89規格により要求されない幾つかの追加のコードが便宜上含まれています。
これらのパラメータはすべてISO 8601の日付値に対応しています。

+-------------+----------------------------------+--------------------------+---------+
| ディレクテ  | 意味                             | 使用例                   | 注釈    |
| ィブ        |                                  |                          |         |
|=============|==================================|==========================|=========|
| "%G"        | ISO week("%V")の内過半数を含む西 | 0001, 0002, ..., 2013,   | (8)     |
|             | 暦表記の ISO 8601 year です。    | 2014, ..., 9998, 9999    |         |
+-------------+----------------------------------+--------------------------+---------+
| "%u"        | 1 を月曜日を表す 10進数表記の    | 1, 2, ..., 7             |         |
|             | ISO 8601 weekday です。          |                          |         |
+-------------+----------------------------------+--------------------------+---------+
| "%V"        | 週で最初の月曜日を始めとする ISO | 01, 02, ..., 53          | (8),    |
|             | 8601 week です。Week 01 は 1月4  |                          | (9)     |
|             | 日を含 みます。                  |                          |         |
+-------------+----------------------------------+--------------------------+---------+
| "%:z"       | UTCオフセットを                  | (空文字列), +00:00,      | (6)     |
|             | "±HH:MM[:SS[.ffffff]]" の形式で  | -04:00, +10:30,          |         |
|             | 表示します (オブジェク トがnaive | +06:34:15,               |         |
|             | であれば空文字列)。              | -03:07:12.345216         |         |
+-------------+----------------------------------+--------------------------+---------+

これらが "strftime()" メソッドと一緒に使用された場合、すべてのプラット
フォームで利用できるわけではありません。 ISO 8601 year 指定子およびISO
8601 week 指定子は、上記のyear および week number 指定子と互換性があり
ません。不完全またはあいまいなISO 8601 指定子で "strptime()" を呼び出
すと、 "ValueError" が送出されます。

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

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

Added in version 3.12: "%:z" が追加されました。


技術詳細
--------

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

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

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

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

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

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

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

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

注釈:

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

   "%:z"
      Behaves exactly as "%z", but has a colon separator added between
      hours, minutes and seconds.

   "%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" では先行ゼロは必須です。

-[ 脚注 ]-

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

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

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

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