Устаревшие элементы C API

Обзор

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

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

Ещё одна важная роль, которую играют пометки устаревания в C API, — это переход к скрытию внутренних деталей реализации NumPy. Для тех, кому нужен прямой и лёгкий доступ к данным ndarray, эта возможность не будет удалена. Скорее, существует множество потенциальных оптимизаций производительности, требующих изменения деталей реализации, и разработчики 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. Таким образом, факт наличия устаревших функций будет отмечен для разработчиков сторонних расширений, которые, возможно, не тщательно изучили примечания к релизу.