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