Устаревшие функции C API

Фон

API, предоставляемый NumPy для сторонних расширений, развивался на протяжении многих лет выпусков и позволял программистам напрямую обращаться к функциональности NumPy из C. Этот API можно лучше всего описать как «органический». Он возник из множества конкурирующих желаний и с разных точек зрения на протяжении многих лет, сильно повлияв на желание упростить пользователям переход на NumPy с Numeric и Numarray. Основной 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, вам нужно #define его до целевой версии API NumPy перед #include любых заголовков 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. См. Для авторов нижестоящих пакетов.