日期时间 API#

NumPy 在内部使用一个 int64 计数器和一个单元元数据结构来表示日期。时间差以类似的方式表示，使用一个 int64 和一个单元元数据结构。下面描述的函数可用于在 ISO 8601 日期字符串、NumPy 日期时间和 Python 日期时间对象之间进行转换。

数据类型#

除了用于 npy_int64 的 npy_datetime 和 npy_timedelta 类型定义之外，NumPy 还定义了两个额外的结构，它们表示时间单元元数据和日期时间的“展开”视图。

type PyArray_DatetimeMetaData#

表示日期时间单元元数据。

typedef struct {
    NPY_DATETIMEUNIT base;
    int num;
} PyArray_DatetimeMetaData;
NPY_DATETIMEUNIT base#

日期时间的单位。

int num#

单位的乘数。

type npy_datetimestruct#

日期时间值的“展开”视图

typedef struct {
    npy_int64 year;
    npy_int32 month, day, hour, min, sec, us, ps, as;
} npy_datetimestruct;
enum NPY_DATETIMEUNIT#

NumPy 支持的时间单位。枚举变体名称中的“FR”代表频率。

enumerator NPY_FR_ERROR#

错误或未确定的单位。

enumerator NPY_FR_Y#

年

enumerator NPY_FR_M#

月

enumerator NPY_FR_W#

周

enumerator NPY_FR_D#

天

enumerator NPY_FR_h#

小时

enumerator NPY_FR_m#

分钟

enumerator NPY_FR_s#

秒

enumerator NPY_FR_ms#

毫秒

enumerator NPY_FR_us#

微秒

enumerator NPY_FR_ns#

纳秒

enumerator NPY_FR_ps#

皮秒

enumerator NPY_FR_fs#

飞秒

enumerator NPY_FR_as#

阿秒

enumerator NPY_FR_GENERIC#

无界单位，可以转换为任何东西

转换函数#

int NpyDatetime_ConvertDatetimeStructToDatetime64(PyArray_DatetimeMetaData *meta, const npy_datetimestruct *dts, npy_datetime *out)#

将日期时间从 datetimestruct 转换为以单元元数据指定的单位表示的日期时间。假定日期有效。

如果元数据结构的 num 成员很大，则此函数中可能会发生整数溢出。

成功返回 0，失败返回 -1。

int NpyDatetime_ConvertDatetime64ToDatetimeStruct(PyArray_DatetimeMetaData *meta, npy_datetime dt, npy_datetimestruct *out)#

将以单元元数据指定的单位表示的日期时间转换为展开的日期时间结构。

成功返回 0，失败返回 -1。

int NpyDatetime_ConvertPyDateTimeToDatetimeStruct(PyObject *obj, npy_datetimestruct *out, NPY_DATETIMEUNIT *out_bestunit, int apply_tzinfo)#

测试并转换 Python datetime.datetime 或 datetime.date 对象为 NumPy npy_datetimestruct。

out_bestunit 根据对象是 datetime.date 还是 datetime.datetime 对象，提供建议的单位。

如果 apply_tzinfo 为 1，则此函数使用 tzinfo 将时间转换为 UTC 时间，否则它会返回具有本地时间的结构。

错误返回 -1，成功返回 0，如果 obj 没有所需的日期或日期时间属性，则返回 1（且没有设置错误）。

int NpyDatetime_ParseISO8601Datetime(char const *str, Py_ssize_t len, NPY_DATETIMEUNIT unit, NPY_CASTING casting, npy_datetimestruct *out, NPY_DATETIMEUNIT *out_bestunit, npy_bool *out_special)#

解析（几乎）标准的 ISO 8601 日期字符串。差异是

  • 日期“20100312”将被解析为 20100312 年，而不是等效于“2010-03-12”。日期中的“-”不是可选的。

  • 只有秒可能带有小数点，最多有 18 位小数（最大阿秒精度）。

  • 可以使用“T”（如 ISO 8601 中所示）或“ ”来分隔日期和时间。两者被等效地对待。

  • 不（目前）处理“YYYY-DDD”或“YYYY-Www”格式。

  • 不处理闰秒（这些情况下秒值为 60）。

  • 不处理 24:00:00 作为明天午夜（00:00:00）的同义词。

  • 接受特殊值“NaT”（非时间），“Today”（根据本地时间当前日期）和“Now”（当前 UTC 时间）。

str 必须是 NULL 终止字符串，而 len 必须是它的长度。

unit 应包含 -1（如果单位未知），或要使用的单位（如果有）。

casting 控制如何将从字符串中检测到的单位转换为“unit”参数。

out 将被解析的日期时间填充。

out_bestunit 根据字符串中提供的解析度给出建议的单位，或 -1 代表 NaT。

out_special 如果解析的时间是“today”、“now”、“空字符串”或“NaT”，则设置为 1。对于“today”，建议的单位是“D”，对于“now”，建议的单位是“s”，对于“NaT”，建议的单位是“Y”。

成功返回 0，失败返回 -1。

int NpyDatetime_GetDatetimeISO8601StrLen(int local, NPY_DATETIMEUNIT base)#

返回用于将具有给定本地时间和单位设置的日期时间对象转换为字符串的字符串长度。在构造要提供给 NpyDatetime_MakeISO8601Datetime 的字符串时，请使用此函数。

int NpyDatetime_MakeISO8601Datetime(npy_datetimestruct *dts, char *outstr, npy_intp outlen, int local, int utc, NPY_DATETIMEUNIT base, int tzoffset, NPY_CASTING casting)#

将 npy_datetimestruct 转换为（几乎）ISO 8601 NULL 终止字符串。如果字符串恰好在空间中容纳，它将省略 NULL 终止符并返回成功。

与 ISO 8601 的差异在于“NaT”字符串，以及年份数字的数量大于等于 4，而不是严格地为 4。

如果 local 非零，则会生成一个包含 +-#### 时区偏移量的本地时间字符串。如果 local 为零且 utc 非零，则会生成以 ‘Z’ 结尾的字符串以表示 UTC 时间。默认情况下，不会附加任何时区信息。

base 用于限制输出到该单位。将 base 设置为 -1 以自动检测所有值均为零之后的基数。

如果启用 local 且 tzoffset 设置为非 -1 值，则使用 tzoffset。这是对要使用的本地时区的手动覆盖，以分钟为单位的偏移量。

casting 控制是否允许数据丢失，方法是将数据截断为更粗略的单位。这与 local 有轻微的交互，为了将日期单位字符串格式化为本地时间，强制转换必须是不安全的。

成功返回 0，失败返回 -1（例如，如果输出字符串太短）。

本页内容