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