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

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

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

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

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

Часто задаваемый вопрос: «Как настроить версию 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 # activate virtual environment
$ python -m pip install -r requirements/all_requirements.txt

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

Компиляция из исходного кода

См. Компиляция из исходного кода.

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

Перед запуском тестов сначала установите зависимости для тестирования:

$ python -m pip install -r requirements/test_requirements.txt
$ python -m pip install asv # only for running benchmarks

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

$ spin test -v
$ spin test numpy/random  # to run the tests in a specific module
$ spin test -v -t numpy/_core/tests/test_nditer.py::test_iter_c_order

Это сначала скомпилирует NumPy, поэтому в первый раз это может занять несколько минут.

Вы также можете использовать spin bench для бенчмаркинга. См. spin --help для получения дополнительных командных параметров.

Дополнительные аргументы могут быть переданы в pytest путём передачи дополнительных аргументов после чистого --. Например, чтобы запустить метод тестирования с флагом --pdb переданным целевой команде, выполните следующее:

$ spin test -t numpy/tests/test_scripts.py::test_f2py -- --pdb

Вы также можете сопоставлять имена тестов с использованием операторов Python, передав аргумент -k в pytest:

$ spin test -v -t numpy/_core/tests/test_multiarray.py -- -k "MatMul and not vector"

Другие параметры сборки

Для получения дополнительных параметров, включая выбор компиляторов, настройку пользовательских флагов компилятора и управление параллелизмом, см. Выбор компилятора и настройка сборки (из документации SciPy).

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

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

>>> 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.9, используйте:

$ tox -e py39

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

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

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

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

Установите все зависимые пакеты с помощью pip:

$ python -m pip install -r requirements/linter_requirements.txt

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

$ python tools/linter.py

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

$ python tools/linter.py --branch main

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

$ python tools/linter.py --branch 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 не включают отладочные символы и скомпилированы с включенными оптимизациями компилятора. Для лучшей отладки рекомендуется использовать отладочную сборку Python, см. Расширенные инструменты отладки.

Для отладки NumPy также необходимо, чтобы он был скомпилирован в отладочном режиме. Вам нужно использовать debug тип сборки и отключить оптимизации, чтобы убедиться, что -O0 флаг используется во время построения объектов. Обратите внимание, что NumPy не должен быть установлен в вашей среде до того, как вы выполните сборку с помощью команды spin build.

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

$ spin build --clean -- -Dbuildtype=debug -Ddisable-optimization=true

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

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

Обратите внимание, что ваш тестовый файл должен находиться вне клонированного вами NumPy. Теперь вы можете запустить:

$ spin gdb /path/to/mytest.py

Если вы используете инструмент сборки clang:

$ spin lldb /path/to/mytest.py

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

(gdb) break array_empty_like
(gdb) run

Аналог lldb:

(lldb) breakpoint set --name array_empty_like
(lldb) run

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

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

Для полноценной поддержки отладки Python необходимо, чтобы скрипт python-gdb.py , поставляемый с Python, был установлен в пути, который gdb может найти. Если вы установили Python через системный менеджер пакетов, вам, вероятно, не нужно ничего делать вручную. Однако, если вы скомпилировали Python из исходного кода, вам, скорее всего, потребуется создать файл .gdbinit в своем домашнем каталоге, указывающий gdb на расположение вашей установки Python. Например, версия python, установленная с помощью pyenv, нуждается в файле .gdbinit со следующим содержимым:

add-auto-load-safe-path ~/.pyenv

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

Понимание кода и начало работы

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

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