DateTime オブジェクト
*********************

"datetime" モジュールでは、様々な日付オブジェクトや時刻オブジェクトを
提供しています。以下に示す関数を使う場合には、あらかじめヘッダファイル
"datetime.h" をソースに include し ("Python.h" はこのファイルを
include しません)、 "PyDateTime_IMPORT" マクロを、通常はモジュール初期
化関数から、起動しておく必要があります。このマクロは以下のマクロで使わ
れる静的変数 "PyDateTimeAPI" に C 構造体へのポインタを入れます。

PyDateTime_IMPORT()

   Import the datetime C API.

   On success, populate the "PyDateTimeAPI" pointer. On failure, set
   "PyDateTimeAPI" to "NULL" and set an exception. The caller must
   check if an error occurred via "PyErr_Occurred()":

      PyDateTime_IMPORT;
      if (PyErr_Occurred()) { /* cleanup */ }

   警告:

     This is not compatible with subinterpreters.

   バージョン 3.15 で変更: This macro is now thread safe.

type PyDateTime_CAPI

   Structure containing the fields for the datetime C API.

   The fields of this structure are private and subject to change.

   Do not use this directly; prefer "PyDateTime_*" APIs instead.

PyDateTime_CAPI *PyDateTimeAPI

   Dynamically allocated object containing the datetime C API.

   This variable is only available once "PyDateTime_IMPORT" succeeds.

   バージョン 3.15 で変更: This variable should not be accessed
   directly as direct access is not thread-safe. Use
   "PyDateTime_IMPORT()" instead.

type PyDateTime_Date

   この "PyObject" のサブタイプは、Pythonの日付オブジェクトを表します
   。

type PyDateTime_DateTime

   この "PyObject" のサブタイプは Python の datetime オブジェクトを表
   します。

type PyDateTime_Time

   この "PyObject" のサブタイプは Python の time オブジェクトを表現し
   ます。

type PyDateTime_Delta

   この "PyObject" のサブタイプは二つの datetime の値の差分を表します
   。

PyTypeObject PyDateTime_DateType

   この "PyTypeObject" のインスタンスは Python の date 型を表します;
   Python レイヤにおける "datetime.date" と同じオブジェクトです。

PyTypeObject PyDateTime_DateTimeType

   この "PyTypeObject" のインスタンスは Python の datetime 型を表現し
   ます; Python レイヤにおける "datetime.datetime" と同じオブジェクト
   です。

PyTypeObject PyDateTime_TimeType

   この "PyTypeObject" のインスタンスは Python の time 型を表します;
   Python レイヤにおける "datetime.time" と同じオブジェクトです。

PyTypeObject PyDateTime_DeltaType

   This instance of "PyTypeObject" represents the Python type for the
   difference between two datetime values; it is the same object as
   "datetime.timedelta" in the Python layer.

PyTypeObject PyDateTime_TZInfoType

   この "PyTypeObject" のインスタンスは Python の タイムゾーン情報型を
   表します; Python レイヤにおける "datetime.tzinfo" と同じオブジェク
   トです。

UTCシングルトンにアクセスするためのマクロ:

PyObject *PyDateTime_TimeZone_UTC

   UTCタイムゾーンに相当するシングルトンを返します。これは
   "datetime.timezone.utc" と同じオブジェクトです。

   Added in version 3.7.

型チェックマクロ:

int PyDate_Check(PyObject *ob)

   *ob* が "PyDateTime_DateType" 型か "PyDateTime_DateType" 型のサブタ
   イプのオブジェクトの場合に真を返します; *ob* は "NULL" であってはな
   りません。この関数は常に成功します。

int PyDate_CheckExact(PyObject *ob)

   *ob* が "PyDateTime_DateType" の場合に真を返します。 *ob* は "NULL"
   であってはなりません。この関数は常に成功します。

int PyDateTime_Check(PyObject *ob)

   *ob* が "PyDateTime_DateTimeType" 型か "PyDateTime_DateTimeType" 型
   のサブタイプのオブジェクトの場合に真を返します; *ob* は "NULL" であ
   ってはなりません。この関数は常に成功します。

int PyDateTime_CheckExact(PyObject *ob)

   *ob* が "PyDateTime_DateTimeType" の場合に真を返します。 *ob* は
   "NULL" であってはなりません。この関数は常に成功します。

int PyTime_Check(PyObject *ob)

   *ob* が "PyDateTime_TimeType" 型か "PyDateTime_TimeType" 型のサブタ
   イプのオブジェクトの場合に真を返します; *ob* は "NULL" であってはな
   りません。この関数は常に成功します。

int PyTime_CheckExact(PyObject *ob)

   *ob* が "PyDateTime_TimeType" の場合に真を返します。 *ob* は "NULL"
   であってはなりません。この関数は常に成功します。

int PyDelta_Check(PyObject *ob)

   *ob* が "PyDateTime_DeltaType" 型か "PyDateTime_DeltaType" 型のサブ
   タイプのオブジェクトの場合に真を返します; *ob* は "NULL" であっては
   なりません。この関数は常に成功します。

int PyDelta_CheckExact(PyObject *ob)

   *ob* が "PyDateTime_DeltaType" の場合に真を返します。 *ob* は
   "NULL" であってはなりません。この関数は常に成功します。

int PyTZInfo_Check(PyObject *ob)

   *ob* が "PyDateTime_TZInfoType" 型か "PyDateTime_TZInfoType" 型のサ
   ブタイプのオブジェクトの場合に真を返します; *ob* は "NULL" であって
   はなりません。この関数は常に成功します。

int PyTZInfo_CheckExact(PyObject *ob)

   *ob* が "PyDateTime_TZInfoType" の場合に真を返します。 *ob* は
   "NULL" であってはなりません。この関数は常に成功します。

以下はオブジェクトを作成するためのマクロです:

PyObject *PyDate_FromDate(int year, int month, int day)
    *戻り値: 新しい参照。*

   指定した年、月、日の "datetime.date" オブジェクトを返します。

PyObject *PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
    *戻り値: 新しい参照。*

   指定した年、月、日、時、分、秒、マイクロ秒の "datetime.datetime" オ
   ブジェクトを返します。

PyObject *PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)
    *戻り値: 新しい参照。*

   指定された年、月、日、時、分、秒、マイクロ秒、fold の
   "datetime.datetime" オブジェクトを返します。

   Added in version 3.6.

PyObject *PyTime_FromTime(int hour, int minute, int second, int usecond)
    *戻り値: 新しい参照。*

   指定された時、分、秒、マイクロ秒の "datetime.time" オブジェクトを返
   します。

PyObject *PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)
    *戻り値: 新しい参照。*

   指定された時、分、秒、マイクロ秒、fold の "datetime.time" オブジェ
   クトを返します。

   Added in version 3.6.

PyObject *PyDelta_FromDSU(int days, int seconds, int useconds)
    *戻り値: 新しい参照。*

   指定された日、秒、マイクロ秒の "datetime.timedelta" オブジェクトを
   返します。マイクロ秒と秒が "datetime.timedelta" オブジェクトで定義
   されている範囲に入るように正規化を行います。

PyObject *PyTimeZone_FromOffset(PyObject *offset)
    *戻り値: 新しい参照。*

   *offset* 引数で指定した固定オフセットを持つ、名前のない
   "datetime.timezone" オブジェクトを返します。

   Added in version 3.7.

PyObject *PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)
    *戻り値: 新しい参照。*

   *offset*引数で指定した固定のオフセットと、*name* のタイムゾーン名を
   持つ "datetime.timezone" オブジェクトを返します。

   Added in version 3.7.

以下のマクロは date オブジェクトからフィールド値を取り出すためのもので
す。引数は "PyDateTime_Date" またはそのサブクラス (例えば
"PyDateTime_DateTime")の  インスタンスでなければなりません。引数を
"NULL" にしてはならず、型チェックは行いません:

int PyDateTime_GET_YEAR(PyDateTime_Date *o)

   年を正の整数で返します。

int PyDateTime_GET_MONTH(PyDateTime_Date *o)

   月を 1 から 12 の間の整数で返します。

int PyDateTime_GET_DAY(PyDateTime_Date *o)

   日を 1 から 31 の間の整数で返します。

以下のマクロは datetime オブジェクトからフィールド値を取り出すためのも
のです。引数は "PyDateTime_DateTime" またはそのサブクラスのインスタン
スでなければなりません。引数を "NULL" にしてはならず、型チェックは行い
ません:

int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)

   時を 0 から 23 の間の整数で返します。

int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)

   分を 0 から 59 の間の整数で返します。

int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)

   秒を 0 から 59 の間の整数で返します。

int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)

   マイクロ秒を 0 から 999999 の間の整数で返します。

int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)

   フォールド(訳注: サマータイムによる時間のずれのこと)を 0 から 1 ま
   での整数で返します。

   Added in version 3.6.

PyObject *PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)

   Return the tzinfo (which may be "None").

   Added in version 3.10.

以下のマクロは time オブジェクトからフィールド値を取り出すためのもので
す。引数は "PyDateTime_Time" またはそのサブクラスのインスタンスでなけ
ればなりません。引数を "NULL" にしてはならず、型チェックは行いません:

int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)

   時を 0 から 23 の間の整数で返します。

int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)

   分を 0 から 59 の間の整数で返します。

int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)

   秒を 0 から 59 の間の整数で返します。

int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)

   マイクロ秒を 0 から 999999 の間の整数で返します。

int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)

   フォールド(訳注: サマータイムによる時間のずれのこと)を 0 から 1 ま
   での整数で返します。

   Added in version 3.6.

PyObject *PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)

   Return the tzinfo (which may be "None").

   Added in version 3.10.

以下のマクロは time delta オブジェクトからフィールド値をとりだすための
ものです。引数は "PyDateTime_Delta" かそのサブクラスのインスタンスでな
ければなりません。引数を "NULL" にしてはならず、型チェックは行いません
:

int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)

   日数を -999999999 から 999999999 の間の整数で返します。

   Added in version 3.3.

int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)

   秒数を 0 から 86399 の間の整数で返します。

   Added in version 3.3.

int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)

   マイクロ秒を 0 から 999999 の間の整数で返します。

   Added in version 3.3.

以下のマクロは DB API を実装する上での便宜用です:

PyObject *PyDateTime_FromTimestamp(PyObject *args)
    *戻り値: 新しい参照。*

   Create and return a new "datetime.datetime" object given an
   argument tuple suitable for passing to
   "datetime.datetime.fromtimestamp()".

PyObject *PyDate_FromTimestamp(PyObject *args)
    *戻り値: 新しい参照。*

   Create and return a new "datetime.date" object given an argument
   tuple suitable for passing to "datetime.date.fromtimestamp()".


Internal data
*************

The following symbols are exposed by the C API but should be
considered internal-only.

PyDateTime_CAPSULE_NAME

   Name of the datetime capsule to pass to "PyCapsule_Import()".

   Internal usage only. Use "PyDateTime_IMPORT" instead.
