Устаревшие функции 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 будут помечены как устаревшие, чтобы будущий код мог избежать использования этих 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. Таким образом, факт наличия устаревших функций будет отмечен для разработчиков сторонних пакетов, которые могут не очень внимательно прочитать примечания к выпуску.

Обратите внимание, что определение NPY_NO_DEPRECATED_API недостаточно для обеспечения совместимости вашего расширения ABI с данной версией NumPy. См. Для авторов пакетов-потребителей.