Устаревшие API C

Предыстория

API, предоставляемое NumPy для сторонних расширений, развивалось на протяжении многих лет выпусков и позволяло программистам напрямую обращаться к функциональности NumPy из C. Данный API можно лучше всего описать как «органический». Он сформировался из множества взаимоисключающих желаний и точек зрения за эти годы, сильно повлиянных стремлением сделать переход пользователей с Numeric и Numarray на NumPy легким. Основной API восходит к Numeric в 1995 году и содержит такие паттерны, как интенсивное использование макросов, написанных для имитации C-API Python, а также учитывающих технологии компиляции конца 90-х годов. Кроме того, лишь небольшая группа добровольцев имела очень мало времени для улучшения данного API.

Ведется работа по улучшению API. Важно в этой работе гарантировать, что код, компилируемый для NumPy 1.X, продолжает компилироваться для NumPy 1.X. В то же время некоторые API будут помечены как устаревшие, чтобы код, ориентированный на будущее, мог избегать этих API и следовать лучшим практикам.

Еще одна важная роль, которую играют пометки устаревания в C API, заключается в стремлении к скрытию внутренних деталей реализации NumPy. Для тех, кому требуется прямой и легкий доступ к данным ndarrays, эта возможность не будет утеряна. Скорее, существует множество потенциальных оптимизаций производительности, требующих изменения деталей реализации, и разработчики NumPy не могли их опробовать из-за высокой ценности сохранения совместимости ABI. Устаревая этот прямой доступ, мы в будущем сможем улучшить производительность NumPy способами, которые нам сейчас недоступны.

Механизм устаревания NPY_NO_DEPRECATED_API

В C нет эквивалента предупреждениям об устаревании, которые поддерживает Python. Один из способов реализации устаревания — пометить их в документации и заметках к выпуску, а затем удалить или изменить устаревшие функции в будущей основной версии (NumPy 2.0 и выше). Небольшие версии NumPy не должны содержать существенных изменений в C API, препятствующих работе кода, который работал в предыдущем мажорном релизе. Например, мы постараемся гарантировать, что код, который компилировался и работал на NumPy 1.4, будет продолжать работать на NumPy 1.7 (возможно, с предупреждениями компилятора).

Для использования механизма NPY_NO_DEPRECATED_API необходимо #определить его на целевую версию API NumPy перед #включением любых заголовков NumPy. Если вы хотите убедиться, что ваш код совместим с 1.7, используйте:

#define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION

В компиляторах, которые поддерживают механизм #warning, NumPy выдает предупреждение компилятора, если вы не определите символ NPY_NO_DEPRECATED_API. Таким образом, факт наличия устаревших функций будет отмечен для разработчиков сторонних программ, которые, возможно, не внимательно прочитали заметки к выпуску.