为NumPy贡献 > 设置和使用您的开发环境
由于NumPy包含用C和Cython编写的部分,在使用前需要进行编译,因此请确保已安装了必需的编译器和Python开发标头-请参见从源代码构建。从版本开始构建NumPy 1.17
需要兼容C99的编译器。
编译代码还意味着从开发源导入NumPy需要一些额外的步骤,下面将对此进行说明。在本章的其余部分中,我们假定您已按照Git中的开发说明设置了git repo 。
要构建NumPy的开发版本并运行测试,使用正确设置的Python导入路径生成交互式shell,请执行以下一项操作:
$ 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
,则针对当前PYTHONPATH上找到的NumPy版本(如果有)运行测试。
当使用-s
,-t
或来指定目标时,--python
可以runtests.py
通过在裸露位置之后传递额外的参数来将其他参数转发到嵌入的目标--
。例如,要运行将--pdb
标志转发到目标的测试方法,请运行以下命令:
$ python runtests.py -t numpy/tests/test_scripts.py:test_f2py -- --pdb
当使用pytest作为目标(默认)时,可以
通过将参数传递给pytest 来使用python运算符匹配测试名称-k
:
$ python runtests.py -v -t numpy/core/tests/test_multiarray.py -- -k "MatMul and not vector"
注意
请记住,在提交更改之前,所有NumPy测试都应通过。
runtests.py
建议使用来运行测试。它也有许多替代方案,例如就地构建或安装到virtualenv。有关详情,请参见下面的常见问题解答。
注意
测试套件中的某些测试需要大量内存,如果您的系统没有足够的内存,则将跳过这些测试。
要覆盖对可用内存的自动检测,请设置环境变量NPY_AVAILABLE_MEM
,例如
NPY_AVAILABLE_MEM=32GB
,或使用pytest --available-memory=32GB
target选项。
对于开发,您可以设置就地构建,以便对.py
文件所做的更改无需重新构建即可
生效。第一次运行:
$ python setup.py build_ext -i
这允许您仅从repo基本目录中导入就地内置的NumPy 。如果希望就地构建在该基本目录之外可见,则需要将PYTHONPATH
环境变量指向此目录。某些IDE(例如Spyder)具有要管理的实用程序
PYTHONPATH
。在Linux和OSX上,可以运行以下命令:
$ export PYTHONPATH=$PWD
在Windows上:
$ set PYTHONPATH=/path/to/numpy
现在,在NumPy中编辑Python源文件,您.py
只需重新启动解释器即可立即测试和使用您的更改(在文件中)。
注意,另一种在repo base dir外部可见的就地构建的方法是with 。无需进行调整,而是将文件安装到站点包中并在其中进行调整
,因此这是一个更永久(更神奇)的操作。python setup.py develop
PYTHONPATH
.egg-link
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的开发版?”。
一种简单的实现方法是,例如,使用二进制安装程序或pip将发布的版本安装在站点软件包中,并在virtualenv中设置开发版本。首先安装 virtualenv(可选使用virtualenvwrapper),然后使用以下命令创建您的virtualenv(在此处命名为numpy-dev):
$ virtualenv numpy-dev
现在,无论何时要切换到虚拟环境,都可以使用命令,并退出虚拟环境并返回到先前的Shell。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()"
也可以使用进行测试,但是找不到特定于NumPy的插件,这会导致奇怪的副作用pytest numpy
运行单个测试文件可能很有用;它比运行整个测试套件或整个模块的速度要快得多(例如:)np.random.test()
。这可以通过以下方式完成:
$ python path_to_testfile/test_file.py
这还需要额外的参数,例如--pdb
在测试失败或引发异常时将您带入Python调试器。
还支持使用tox运行测试。例如,要构建NumPy并使用Python 3.7运行测试套件,请使用:
$ tox -e py37
有关更多信息,请参阅测试准则。
注意:不要在没有``runtests.py''的numpy git repo的根目录中运行测试,这会导致奇怪的测试错误。
更改编译后的代码后,可以使用与先前相同的构建命令来重建NumPy-仅重新生成更改的文件。进行完整的构建(有时是必要的)需要首先清洁工作区。执行此操作的标准方法是(注意:删除所有未提交的文件!):
$ git clean -xdf
如果要放弃所有更改并返回到存储库中的最后一次提交,请使用以下方法之一:
$ git checkout .
$ git reset --hard
另一个常见问题是“如何在NumPy中调试C代码?”。最简单的方法是先编写一个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函数处停止执行,您可以照常逐步执行。安装了gdb的Python扩展(通常是Linux上的默认设置)后,可以使用许多有用的特定于Python的命令。例如,要查看您在Python代码中的位置,请使用py-list
。有关更多详细信息,请参见DebuggingWithGdb。
gdb
当然,您可以使用最喜欢的替代调试器代替简单的调试器;在带参数的python二进制文件上运行它
。runtests.py -g --python mytest.py
python-dbg
强烈建议使用带有调试支持的Python构建NumPy(在通常打包为的Linux发行版上)。
更好地理解代码库的最佳策略是选择要更改的内容,然后开始阅读代码以弄清楚其工作原理。如有疑问,您可以在邮件列表中提问。如果您的拉取请求不完美,那是完全可以的,社区总是很乐意提供帮助。作为一个志愿者项目,有时候事情确实会掉下来,如果我们坐了大约两到四个星期没有任何反应,对我们进行ping很好。
因此,继续进行一些选择,使您对numpy感到烦恼或困惑,尝试一下代码,闲逛以进行讨论,或者浏览参考文档以尝试进行修复。事情将就位,很快您将对整个项目有一个很好的了解。祝好运!