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

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

Поскольку 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?» Самый простой способ — сначала написать скрипт Python, который вызывает C-код, выполнение которого вы хотите отладить. Например, mytest.py:

from numpy import linspace
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, и вы можете пройти по ней обычным способом. При установленных (часто по умолчанию в Linux) расширениях Python для gdb доступно множество полезных команд Python. Например, чтобы увидеть, где вы находитесь в коде Python, используйте py-list. Более подробную информацию см. в DebuggingWithGdb.

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

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

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

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

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