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