Настройка и использование среды разработки

Рекомендуемая настройка среды разработки

Поскольку NumPy содержит части, написанные на C и Cython, которые необходимо скомпилировать перед использованием, убедитесь, что у вас установлены необходимые компиляторы и заголовочные файлы для разработки Python — см. Компиляция из исходного кода. Для компиляции NumPy по состоянию на версию 1.17 требуется компилятор, совместимый с C99.

Использование скомпилированного кода также означает, что для импорта NumPy из исходных кодов разработки требуются дополнительные шаги, которые описаны ниже. В этой главе мы предполагаем, что вы настроили свой репозиторий Git, как описано в Git для разработки.

Тестирование сборок

Для компиляции версии NumPy для разработки и запуска тестов, создания интерактивных оболочек с правильно настроенными путями импорта Python и т. д., выполните одно из следующих действий:

$ python runtests.py -v
$ python runtests.py -v -s random
$ python runtests.py -v -t numpy/core/tests/test_nditer.py::test_iter_c_order
$ python runtests.py --ipython
$ python runtests.py --python somescript.py
$ python runtests.py --bench
$ python runtests.py -g -m full

Это сначала скомпилирует NumPy, поэтому в первый раз это может занять несколько минут. Если вы укажете -n, тесты будут выполнены для версии NumPy (если есть) из текущей PYTHONPATH.

При указании целевого объекта с помощью -s, -t, или --python, дополнительные аргументы могут быть переданы целевому объекту, встраиваемому runtests.py путем передачи дополнительных аргументов после простого --. Например, чтобы запустить метод теста с переданным флагом --pdb, выполните следующее:

$ python runtests.py -t numpy/tests/test_scripts.py::test_f2py -- --pdb

При использовании pytest в качестве целевого объекта (по умолчанию) вы можете сопоставить имена тестов с помощью операторов Python, передав аргумент -k в pytest:

$ python runtests.py -v -t numpy/core/tests/test_multiarray.py -- -k "MatMul and not vector"

Использование runtests.py является рекомендуемым подходом для запуска тестов. Также есть ряд альтернативных способов, например, компиляция на месте или установка в виртуальной среде. Подробности см. в FAQ ниже.

Компиляция на месте

Для разработки вы можете настроить компиляцию на месте, чтобы изменения, внесенные в файлы .py, вступали в силу без перекомпиляции. Сначала выполните:

$ python setup.py build_ext -i

Это позволяет импортировать скомпилированный на месте NumPy только из базового каталога репозитория. Если вы хотите, чтобы компиляция на месте была видна за пределами базового каталога, вам необходимо указать переменную среды PYTHONPATH на этот каталог. Некоторые IDE (Spyder, например) имеют средства для управления PYTHONPATH. В Linux и OSX можно выполнить команду:

$ export PYTHONPATH=$PWD

а в Windows:

$ set PYTHONPATH=/path/to/numpy

Теперь редактирование файла исходного кода Python в NumPy позволяет вам немедленно тестировать и использовать внесенные изменения (в файлах .py), просто перезапустив интерпретатор.

Обратите внимание, что еще один способ выполнения компиляции на месте, видимой за пределами каталога репозитория, заключается в использовании python setup.py develop. Вместо того, чтобы изменять PYTHONPATH, это устанавливает файл .egg-link в ваши site-packages, а также изменяет easy-install.pth там, что является более постоянной (и магической) операцией.

Другие варианты компиляции

Варианты компиляции можно узнать, выполнив любое из следующих действий:

$ python setup.py --help
$ python setup.py --help-commands

Можно выполнить параллельную компиляцию с numpy.distutils с опцией -j; см. Параллельная компиляция для получения более подробной информации.

Аналогичный подход к компиляции на месте и использованию PYTHONPATH, но вне древовидной структуры исходного кода, заключается в использовании:

$ pip install . --prefix /some/owned/folder
$ export PYTHONPATH=/some/owned/folder/lib/python3.4/site-packages

NumPy использует ряд тестов для проверки компилятора и библиотек libc на наличие функций. Результаты сохраняются в файлах _numpyconfig.h и config.h с использованием определений HAVE_XXX. Эти тесты выполняются во время стадии build_src модуля _multiarray_umath в функциях generate_config_h и generate_numpyconfig_h. Поскольку выходные данные этих вызовов включают много предупреждений и ошибок компилятора, по умолчанию он выполняется в тихом режиме. Если вы хотите увидеть эти выходные данные, вы можете запустить стадию build_src в подробном режиме:

$ python build build_src -v

Использование виртуальных сред

Часто задаваемый вопрос: «Как настроить версию NumPy для разработки параллельно с релизной версией, которую я использую для своей работы/исследований?».

Один из простых способов сделать это — установить релизную версию в site-packages, например, с помощью установщика двоичных файлов или pip, а версию для разработки — в виртуальной среде. Сначала установите virtualenv (можно использовать virtualenvwrapper), затем создайте свою виртуальную среду (называется numpy-dev здесь) с помощью:

$ virtualenv numpy-dev

Теперь, когда вы захотите переключиться на виртуальную среду, вы можете использовать команду source numpy-dev/bin/activate, а deactivate для выхода из виртуальной среды и возврата к предыдущей оболочке.

Запуск тестов

Помимо использования runtests.py, есть различные способы запуска тестов. Внутри интерпретатора тесты можно запустить так:

>>> np.test()  
>>> np.test('full')   # Also run tests marked as slow
>>> np.test('full', verbose=2)   # Additionally print test name/file

An example of a successful test :
``4686 passed, 362 skipped, 9 xfailed, 5 warnings in 213.99 seconds``

Или похожим способом из командной строки:

$ python -c "import numpy as np; np.test()"

Тесты также можно запустить с помощью pytest numpy, однако тогда плагин NumPy не будет найден, что приведет к странным побочным эффектам.

Запуск отдельных файлов тестов может быть полезен; это намного быстрее, чем запуск всего набора тестов или всего модуля (пример: np.random.test()). Это можно сделать с помощью:

$ python path_to_testfile/test_file.py

Это также принимает дополнительные аргументы, например, --pdb, который запустит отладчик Python при возникновении ошибки теста или исключения.

Запуск тестов с помощью tox также поддерживается. Например, чтобы скомпилировать NumPy и запустить набор тестов с Python 3.7, используйте:

$ tox -e py37

Дополнительную информацию см. в Руководстве по тестированию.

Примечание: не запускайте тесты из корневого каталога вашего репозитория NumPy Git без ``runtests.py``, это приведет к странным ошибкам тестов.

Перекомпиляция и очистка рабочей области

Перекомпиляция NumPy после внесения изменений в скомпилированный код может быть выполнена с помощью той же команды компиляции, что и ранее — будут перекомпилированы только изменённые файлы. Для полной перекомпиляции, которая иногда необходима, сначала необходимо очистить рабочую область. Стандартный способ сделать это (Примечание: удаляет все несохранённые файлы!):

$ git clean -xdf

Когда вы хотите отбросить все изменения и вернуться к последней фиксации в репозитории, используйте одну из следующих команд:

$ git checkout .
$ git reset --hard

Отладка

Еще один часто задаваемый вопрос: «Как отладить код C внутри NumPy?».

Сначала убедитесь, что у вас установлен gdb с расширениями для Python (часто по умолчанию в Linux). Вы можете увидеть, какая версия Python работает внутри gdb, чтобы проверить свою настройку:

(gdb) python
>import sys
>print(sys.version_info)
>end
sys.version_info(major=3, minor=7, micro=0, releaselevel='final', serial=0)

Затем вам нужно написать скрипт Python, который вызывает код C, выполнение которого вы хотите отладить. Например, mytest.py:

import numpy as np
x = np.arange(5)
np.empty_like(x)

Теперь можно выполнить:

$ gdb --args python runtests.py -g --python mytest.py

И затем в отладчике:

(gdb) break array_empty_like
(gdb) run

Выполнение теперь остановится на соответствующей функции C, и вы можете проходить по ней обычным способом. Доступно несколько полезных команд, специфичных для Python. Например, чтобы увидеть, где вы находитесь в коде Python, используйте py-list. Более подробную информацию см. в DebuggingWithGdb. Вот некоторые часто используемые команды:

• list: Вывести указанную функцию или строку.
• next: Шаг за шагом проходить программу, переходя через вызовы подпрограмм.
• step: Продолжить отладку программы после сигнала или точки останова.
• print: Вывести значение выражения EXP.

Вместо простого gdb вы, конечно, можете использовать свой любимый альтернативный отладчик; запустите его на двоичном файле Python с аргументами runtests.py -g --python mytest.py.

Настоятельно рекомендуется компилировать NumPy с Python, в котором включена поддержка отладки (в дистрибутивах Linux обычно поставляется как python-dbg).

Изучение кода и начало работы

Лучшая стратегия для лучшего понимания кода — выбрать то, что вы хотите изменить, и начать чтение кода, чтобы понять, как он работает. Если у вас есть вопросы, задавайте их на почтовой рассылке. Совершенно нормально, если ваши запросы на добавление изменений не идеальны, сообщество всегда готово помочь. Как добровольческий проект, иногда вещи откладываются, и абсолютно нормально отправлять нам запросы, если на что-то не получен ответ в течение двух-четырёх недель.

Итак, выберите что-нибудь, что вызывает у вас раздражение или непонимание в numpy, экспериментируйте с кодом, общайтесь или изучите справочную документацию, чтобы попытаться это исправить. Всё встанет на свои места, и вскоре вы получите хорошее представление о проекте в целом. Удачи!