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