Contributing to Scrapy

Important

https://docs.scrapy.org/en/master/contributing.html处仔细检查您是否正在阅读本文档的最新版本.

有许多方法可以为Scrapy做出贡献. 这里是其中的一些:

  • 关于Scrapy的博客. 告诉全世界您如何使用Scrapy. 这将为新手提供更多示例,并帮助Scrapy项目增加其可见性.
  • 问题跟踪器中报告错误和请求功能,尝试遵循下面的报告错误中详细介绍的准则.
  • 提交补丁以获取新功能和/或错误修复. 请阅读下面的编写补丁提交补丁以获取有关如何编写和提交补丁的详细信息.
  • 加入Scrapy subreddit,并分享有关如何改善Scrapy的想法. 我们随时欢迎您提出建议.
  • Stack Overflow上回答Scrapy问题.

Reporting bugs

Note

scrapy-security @ googlegroups报告安全问题. com . 这是仅对受信任的Scrapy开发人员开放的私人列表,并且其存档不是公开的.

编写良好的错误报告非常有帮助,因此在报告新错误时请记住以下准则.

  • 请先查看常见问题解答 ,看看您的问题是否在一个著名的问题中得到解决
  • 如果您有关于刮擦用法的一般问题,请在Stack Overflow (使用" scrapy"标签)上询问.
  • 检查未解决的问题,以查看问题是否已经报告. 如果有,请不要关闭该报告,而要检查故障单历史记录和注释. 如果您还有其他有用的信息,请发表评论,或考虑发送带有修复程序的请求请求 .
  • 搜索scrapy-users列表和Scrapy subreddit,以查看是否已在此处进行了讨论,或者不确定是否看到的是bug. 您也可以在#scrapy IRC频道中提问.
  • 编写完整的,可复制的,特定的错误报告 . 测试用例越小越好. 请记住,其他开发人员将没有您的项目来重现该错误,因此请包括所有需要重现该错误的相关文件. 请参阅例如StackOverflow关于创建最小,完整和可验证示例的指南,以展示此问题.
  • 提供完整可复制示例的最棒方法是发送请求请求,该请求将失败的测试用例添加到Scrapy测试套件中(请参阅提交补丁 ). 即使您自己不想解决此问题,这也很有用.
  • 包括scrapy version -v的输出,因此开发您的bug的开发人员可以准确知道它发生在哪个版本scrapy version -v台上,这通常对于重现它或确定它是否已被修复非常有帮助.

Writing patches

补丁写得越好,被接受的机会就越大,并且被合并的越早.

精心编写的补丁程序应:

  • 包含特定更改所需的最少代码量. 小补丁更易于查看和合并. 因此,如果您要进行多个更改(或错误修复),请考虑为每个更改提交一个补丁. 不要将多个更改折叠到一个补丁中. 对于较大的更改,请考虑使用修补程序队列.

  • 通过所有单元测试. 请参阅下面的运行测试 .

  • 包括一个(或多个)测试用例,用于检查已修复的错误或添加的新功能. 请参阅下面的编写测试 .

  • 如果您要添加或更改公共(已记录的)API,请在同一补丁中包含对文档所做的更改. 请参阅下面的文档政策 .

  • 如果要添加私有API,请向docs/conf.pycoverage_ignore_pyobjects变量添加正则表达式,以将新的私有API从文档覆盖率检查中排除.

    要查看您的私有API是否被正确跳过,请生成文档覆盖率报告,如下所示:

    tox -e docs-coverage
    

Submitting patches

提交补丁的最佳方法是在GitHub上发出拉取请求 ,可以选择先创建一个新的发布.

记住要解释什么是固定的或新功能(它是什么,为什么需要它,等等). 您包含的信息越多,核心开发人员就越容易理解和接受您的补丁.

您也可以在创建补丁之前讨论新功能(或错误修复),但是最好准备一个补丁来说明您的论点并表明您已对该主题进行了一些思考. 一个很好的起点是在GitHub上发送拉取请求. 它可以很简单地说明您的想法,并在想法经过验证并证明是有用的之后保留文档/测试供以后使用. 或者,您可以在Scrapy subreddit中开始对话以首先讨论您的想法.

Sometimes there is an existing pull request for the problem you’d like to solve, which is stalled for some reason. Often the pull request is in a right direction, but changes are requested by Scrapy maintainers, and the original pull request author hasn’t had time to address them. In this case consider picking up this pull request: open a new pull request with all commits from the original pull request, as well as additional changes to address the raised issues. Doing so helps a lot; it is not considered rude as soon as the original author is acknowledged by keeping his/her commits.

您可以通过运行git fetch upstream pull/$PR_NUMBER/head:$BRANCH_NAME_TO_CREATE将现有的拉取请求拉至本地分支git fetch upstream pull/$PR_NUMBER/head:$BRANCH_NAME_TO_CREATE (将"上游"替换为scrapy存储库的远程名称,将$PR_NUMBER替换为拉取请求的ID,并使用$BRANCH_NAME_TO_CREATE ,以及您要在本地创建的分支的名称). 另请参阅: https : //help.github.com/articles/checking-out-pull-requests-locally/#modifying-an-inactive-pull-request-locally .

在编写GitHub拉取请求时,请尝试使标题简短但具有描述性. 例如,对于错误#411:"如果start_requests中出现异常,则Scrapy挂起",而不是"修复#411中的错误,则在start_requests(#411)中发生异常时修复挂起". 完整的标题可轻松浏览问题跟踪器.

最后,尝试保持审美变化( PEP 8合规性,未使用的进口移除等)与功能更改分开提交. 这将使拉取请求更易于审核,并且更有可能被合并.

Coding style

在编写要包含在Scrapy中的代码时,请遵循以下编码约定:

Documentation policies

对于API成员(类,方法等)的参考文档,请使用文档字符串,并确保Sphinx文档使用autodoc扩展名提取文档字符串. API参考文档应遵循docstring约定( PEP 257 ),并且应与IDE友好:简而言之,它可能会提供简短的示例.

docs/目录中的文件应涵盖其他类型的文档,例如教程或主题. 这包括特定于API成员的文档,但超出了API参考文档.

无论如何,如果文档字符串中包含某些内容,请使用autodoc扩展名将文档字符串拉入文档中,而不要在docs/目录中的文件中复制文档字符串.

Tests

测试是使用Twisted单元测试框架实现的 ,运行测试需要使用tox .

Running tests

确保您最近安装了足够的毒物

tox --version

如果您的版本低于1.7.0,请先更新:

pip install -U tox

要运行所有测试,请转到Scrapy源代码的根目录并运行:

tox

要运行特定的测试(例如tests/test_loader.py ),请使用:

tox -- tests/test_loader.py

要在特定的tox环境上运行测试,请使用-e <name>以及tox.ini的环境名称. 例如,要使用Python 3.6运行测试,请使用:

tox -e py36

您还可以指定一个用逗号分隔的环境列表,并使用tox的并行模式在多个环境中并行运行测试:

tox -e py27,py36 -p auto

要将命令行选项传递给pytest ,请在对tox的调用中-- 后面添加它们. 使用--会覆盖tox.ini定义的默认位置参数,因此,您还必须在--之后包括这些默认位置参数( scrapy tests ):

tox -- scrapy tests -x  # stop after first failure

您也可以使用pytest-xdist插件. 例如,要使用所有CPU内核在Python 3.6 tox环境中运行所有测试:

tox -e py36 -- scrapy tests -n auto

要查看覆盖率报告的安装覆盖率pip install coverage )并运行:

coverage report

请参阅coverage --help输出以获取更多选项,例如html或xml report.

Writing tests

所有功能(包括新功能和错误修复)都必须包含一个测试用例,以检查其是否按预期工作,因此,如果您希望它们的补丁能尽快被接受,请包括针对补丁的测试.

Scrapy使用位于tests /目录中的单元测试 . 他们的模块名称通常类似于他们正在测试的模块的完整路径. 例如,项目装载程序代码位于:

scrapy.loader

他们的单元测试在:

tests/test_loader.py