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