# DateTime 物件

`datetime` 模块提供了各种日期和时间对象。 在使用这些函数之前，必须在你的源代码中包含头文件 `datetime.h` (请注意此文件并未包括在 `Python.h` 中)，并且 `PyDateTime_IMPORT` 必须被唤起，通常是作为模块初始化函数的一部分。 这个宏会将指向特定 C 结构体的指针放入一个静态变量 `PyDateTimeAPI` 中，它将被下列的宏所使用。

type PyDateTime_Date

  `PyObject` 的这个子类型表示 Python 日期对象。

type PyDateTime_DateTime

  `PyObject` 的这个子类型表示 Python 日期时间对象。

type PyDateTime_Time

  `PyObject` 的这个子类型表示 Python 时间对象。

type PyDateTime_Delta

  `PyObject` 的这个子类型表示两个日期时间值之间的差值。

PyTypeObject PyDateTime_DateType

  这个 `PyTypeObject` 的实例代表 Python 日期类型；它与 Python 层面的 `datetime.date` 对象相同。

PyTypeObject PyDateTime_DateTimeType

  这个 `PyTypeObject` 的实例代表 Python 日期时间类型；它与 Python 层面的 `datetime.datetime` 对象相同。

PyTypeObject PyDateTime_TimeType

  这个 `PyTypeObject` 的实例代表 Python 时间类型；它与 Python 层面的 `datetime.time` 对象相同。

PyTypeObject PyDateTime_DeltaType

  这个 `PyTypeObject` 的实例是代表两个日期时间值之间差值的 Python 类型；它与 Python 层面的 `datetime.timedelta` 对象相同。

PyTypeObject PyDateTime_TZInfoType

  这个 `PyTypeObject` 的实例代表 Python 时区信息类型；它与 Python 层面的 `datetime.tzinfo` 对象相同。

用於存取 UTC 單例 (singleton) 的巨集：

PyObject *PyDateTime_TimeZone_UTC

  回傳表示 UTC 的時區單例，是與 `datetime.timezone.utc` 相同的物件。

  在 3.7 版新加入.

型別檢查巨集：

int PyDate_Check( PyObject *ob)

  如果 ob 为 `PyDateTime_DateType` 类型或 `PyDateTime_DateType` 的某个子类型则返回真值。 ob 不能为 `NULL`。 此函数总是会成功执行。

int PyDate_CheckExact( PyObject *ob)

  如果 ob 的型別為 `PyDateTime_DateType`，則回傳 true。 ob 不得為 `NULL`。這個函式一定會執行成功。

int PyDateTime_Check( PyObject *ob)

  如果 ob 为 `PyDateTime_DateTimeType` 类型或 `PyDateTime_DateTimeType` 的某个子类型则返回真值。 ob 不能为 `NULL`。 此函数总是会成功执行。

int PyDateTime_CheckExact( PyObject *ob)

  如果 ob 的型別為 `PyDateTime_DateTimeType`，則回傳 true。ob 不得為 `NULL`。這個函式一定會執行成功。

int PyTime_Check( PyObject *ob)

  如果 ob 为 `PyDateTime_TimeType` 类型或 `PyDateTime_TimeType` 的某个子类型则返回真值。 ob 不能为 `NULL`。 此函数总是会成功执行。

int PyTime_CheckExact( PyObject *ob)

  如果 ob 的型別為 `PyDateTime_TimeType`，則回傳 true。ob 不得為 `NULL`。這個函式一定會執行成功。

int PyDelta_Check( PyObject *ob)

  如果 ob 为 `PyDateTime_DeltaType` 类型或 `PyDateTime_DeltaType` 的某个子类型则返回真值。 ob 不能为 `NULL`。 此函数总是会成功执行。

int PyDelta_CheckExact( PyObject *ob)

  如果 ob 的型別為 `PyDateTime_DeltaType`，則回傳 true。ob 不得為 `NULL`。這個函式一定會執行成功。

int PyTZInfo_Check( PyObject *ob)

  如果 ob 为 `PyDateTime_TZInfoType` 类型或 `PyDateTime_TZInfoType` 的某个子类型则返回真值。 ob 不能为 `NULL`。 此函数总是会成功执行。

int PyTZInfo_CheckExact( PyObject *ob)

  如果 ob 的型別為 `PyDateTime_TZInfoType`，則回傳 true。 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`。

  在 3.6 版新加入.

PyObject *PyTime_FromTime(int hour, int minute, int second, int usecond)
  回傳值：新的參照。

  回傳一個有特定時、分、秒、微秒的物件 `datetime.date`。

PyObject *PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)
  回傳值：新的參照。

  回傳一個有特定時、分、秒、微秒與 fold（時間折疊）的物件 `datetime.time`。

  在 3.6 版新加入.

PyObject *PyDelta_FromDSU(int days, int seconds, int useconds)
  回傳值：新的參照。

  回傳一個 `datetime.timedelta` 物件，表示給定的天數、秒數和微秒數。執行標準化 (normalization) 以便生成的微秒數和秒數位於 `datetime.timedelta` 物件記錄的範圍內。

PyObject *PyTimeZone_FromOffset( PyObject *offset)
  回傳值：新的參照。

  回傳一個 `datetime.timezone` 物件，其未命名的固定偏移量由 offset 引數表示。

  在 3.7 版新加入.

PyObject *PyTimeZone_FromOffsetAndName( PyObject *offset, PyObject *name)
  回傳值：新的參照。

  回傳一個 `datetime.timezone` 物件，其固定偏移量由 offset 引數表示，並帶有 tzname name。

  在 3.7 版新加入.

一些用来从日期对象中提取字段的宏。 参数必须是 `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。

一些用来从日期时间对象中提取字段的宏。 参数必须是 `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)

  回傳 fold，為 0 或 1 的正整數。

  在 3.6 版新加入.

PyObject *PyDateTime_DATE_GET_TZINFO( PyDateTime_DateTime *o)

  回傳 tzinfo（可能是 `None`）。

  在 3.10 版新加入.

一些用来从时间对象中提取字段的宏。 参数必须是 `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)

  回傳 fold，為 0 或 1 的正整數。

  在 3.6 版新加入.

PyObject *PyDateTime_TIME_GET_TZINFO( PyDateTime_Time *o)

  回傳 tzinfo（可能是 `None`）。

  在 3.10 版新加入.

一些用来从时间差对象中提取字段的宏。 参数必须是 `PyDateTime_Delta` 包括其子类的实例。参数不能为 `NULL`，并且不会检查类型:

int PyDateTime_DELTA_GET_DAYS( PyDateTime_Delta *o)

  以 -999999999 到 999999999 之間的整數形式回傳天數。

  在 3.3 版新加入.

int PyDateTime_DELTA_GET_SECONDS( PyDateTime_Delta *o)

  以 0 到 86399 之間的整數形式回傳秒數。

  在 3.3 版新加入.

int PyDateTime_DELTA_GET_MICROSECONDS( PyDateTime_Delta *o)

  以 0 到 999999 之間的整數形式回傳微秒數。

  在 3.3 版新加入.

為了方便模組實作 DB API 的巨集：

PyObject *PyDateTime_FromTimestamp( PyObject *args)
  回傳值：新的參照。

  給定一個適合傳遞給 `datetime.datetime.fromtimestamp()` 的引數元組，建立並回傳一個新的 `datetime.datetime` 物件。

PyObject *PyDate_FromTimestamp( PyObject *args)
  回傳值：新的參照。

  給定一個適合傳遞給 `datetime.date.fromtimestamp()` 的引數元組，建立並回傳一個新的 `datetime.date` 物件。