Интерфейс API дат и времени

Типы данных

В дополнение к типам npy_datetime и npy_timedelta для npy_int64, NumPy определяет две дополнительные структуры, представляющие метаданные единицы времени и «развёрнутый» вид даты и времени.

типPyArray_DatetimeMetaData

Представляет метаданные единицы даты и времени.

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

NPY_DATETIMEUNITbase

Единица даты и времени.

intnum

Множитель для единицы.

типnpy_datetimestruct

«Развёрнутый» вид значения даты и времени.

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

перечислениеNPY_DATETIMEUNIT

Единицы времени, поддерживаемые NumPy. «FR» в именах вариантов перечисления — сокращение от частоты.

перечислительNPY_FR_ERROR

Ошибка или неопределённые единицы.

перечислительNPY_FR_Y

Года

перечислительNPY_FR_M

Месяцы

перечислительNPY_FR_W

Недели

перечислительNPY_FR_D

Дни

перечислительNPY_FR_h

Часы

перечислительNPY_FR_m

Минуты

перечислительNPY_FR_s

Секунды

перечислительNPY_FR_ms

Миллисекунды

перечислительNPY_FR_us

Микросекунды

перечислительNPY_FR_ns

Наносекунды

перечислительNPY_FR_ps

Пикосекунды

перечислительNPY_FR_fs

Фемтосекунды

перечислительNPY_FR_as

Аттосекунды

перечислительNPY_FR_GENERIC

Неопределённые единицы, могут быть преобразованы в любые другие

Функции преобразования

intNpyDatetime_ConvertDatetimeStructToDatetime64(PyArray_DatetimeMetaData*meta, constnpy_datetimestruct*dts, npy_datetime*out)

Преобразует дату и время из структуры datetimestruct в значение datetime64 в указанных единицах измерения из метаданных. Предполагается, что дата действительна.

Если значение num в структуре метаданных велико, в этой функции может произойти переполнение целых чисел.

Возвращает 0 при успехе и -1 при ошибке.

intNpyDatetime_ConvertDatetime64ToDatetimeStruct(PyArray_DatetimeMetaData*meta, npy_datetimedt, npy_datetimestruct*out)

Преобразует значение datetime64 с единицами измерения, указанными в метаданных, в структуру datetimestruct.

Возвращает 0 при успехе и -1 при ошибке.

intNpyDatetime_ConvertPyDateTimeToDatetimeStruct(PyObject*obj, npy_datetimestruct*out, NPY_DATETIMEUNIT*out_bestunit, intapply_tzinfo)

Проверяет и преобразует объект Python datetime.datetime или datetime.date в структуру NumPy npy_datetimestruct.

out_bestunit предлагает рекомендуемые единицы измерения, основываясь на том, был ли объект datetime.date или datetime.datetime объектом.

Если apply_tzinfo равно 1, эта функция использует tzinfo для преобразования во временную зону UTC, в противном случае возвращает структуру с локальным временем.

Возвращает -1 при ошибке, 0 при успехе и 1 (без установки ошибки), если у объекта obj отсутствуют необходимые атрибуты даты или времени.

intNpyDatetime_ParseISO8601Datetime(charconst*str, Py_ssize_tlen, NPY_DATETIMEUNITunit, NPY_CASTINGcasting, 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 должна быть строкой с нулевым завершением, а len - её длиной.

unit должно содержать -1, если единица измерения неизвестна, или единицу измерения, если она известна.

casting управляет тем, как обнаруженная единица измерения из строки может быть приведена к типу 'unit'.

out заполняется распарсенной датой и временем.

out_bestunit предлагает рекомендуемые единицы измерения, основываясь на разрешении, предоставленном в строке, или -1 для NaT.

out_special устанавливается в 1, если распарсенное время было 'today', 'now', пустой строкой или 'NaT'. Для 'today' рекомендуемая единица измерения 'D', для 'now' - 's', а для 'NaT' - 'Y'.

Возвращает 0 при успехе и -1 при ошибке.

intNpyDatetime_GetDatetimeISO8601StrLen(intlocal, NPY_DATETIMEUNITbase)

Возвращает длину строки, используемую для преобразования объектов datetime с заданными настройками местного времени и единиц измерения в строки. Используйте это при создании строк для передачи в NpyDatetime_MakeISO8601Datetime.

intNpyDatetime_MakeISO8601Datetime(npy_datetimestruct*dts, char*outstr, npy_intpoutlen, intlocal, intutc, NPY_DATETIMEUNITbase, inttzoffset, NPY_CASTINGcasting)

Преобразует структуру npy_datetimestruct в строку (почти) в формате ISO 8601 с нулевым завершением. Если строка помещается точно в отведенное место, она опускает нулевой терминатор и возвращает успех.

Отличия от формата ISO 8601 — строка 'NaT' и количество цифр в году (>= 4 вместо точно 4).

Если local отлично от нуля, генерируется строка в локальном времени с отступом часового пояса (+/-####). Если local равно нулю, а utc отлично от нуля, генерируется строка, оканчивающаяся на 'Z', обозначающая UTC. По умолчанию информация о часовом поясе не добавляется.

base ограничивает вывод данной единицей измерения. Установите base в -1 для автоматического определения базовой единицы измерения после которой все значения равны нулю.

tzoffset используется, если local включено, и tzoffset установлено в значение отличное от -1. Это ручная переопределённая локальная временная зона для использования, как смещение в минутах.

casting управляет тем, разрешается ли потеря данных путем усечения данных до более грубой единицы измерения. Это взаимодействует с local, незначительно, для формирования строки с единицей измерения даты как местного времени, приведение типов должно быть небезопасным.

Возвращает 0 при успехе и -1 при ошибке (например, если строка вывода была слишком короткой).