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

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

Поскольку 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 является рекомендуемым подходом для запуска тестов. Также есть ряд альтернатив, например, сборка на месте или установка в виртуальной среде или среде conda. Подробности см. в разделе 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 или conda, например, и настроить версию для разработки в виртуальной среде.

Если вы используете conda, мы рекомендуем создать отдельную виртуальную среду для разработки NumPy, используя файл environment.yml в корневом каталоге репозитория (это создаст среду и установит все зависимости разработки сразу):

$ conda env create -f environment.yml  # `mamba` works too for this command
$ conda activate numpy-dev

Если вы установили Python каким-то другим способом, кроме conda, сначала установите 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 без ``runtests.py``, это приведет к странным ошибкам в тестах.

Запуск проверки кода

Проверки кода могут выполняться на новых строках Python-кода.

Установите все зависимые пакеты, используя pip:

$ python -m pip install -r linter_requirements.txt

Чтобы выполнить проверки кода перед коммитом нового кода, запустите:

$ python runtests.py --lint uncommitted

Чтобы проверить все изменения в новом Python-коде текущей ветки с целевой веткой, запустите:

$ python runtests.py --lint main

Если ошибок нет, сценарий завершается без сообщения. В случае ошибок:

$ python runtests.py --lint main
./numpy/core/tests/test_scalarmath.py:34:5: E303 too many blank lines (3)
1       E303 too many blank lines (3)

Рекомендуется запускать проверки кода перед отправкой коммитов на удаленную ветку, так как linter выполняется как часть CI-пайплайна.

Для получения более подробной информации о рекомендациях по стилю:

• Руководство по стилю Python
• Руководство по стилю C

Перестройка и очистка рабочей области

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