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

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

Поскольку 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 на этот каталог. Некоторые среды разработки (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, поэкспериментируйте с кодом, поучаствуйте в обсуждениях или ознакомьтесь с справочными документами, чтобы попытаться это исправить. Всё встанет на свои места, и вскоре вы получите довольно хорошее понимание проекта в целом. Удачи!