Skip to main content

有助于Scrapy

重要

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

有很多方法可以帮助Scrapy。这里是其中的一些:

  • 关于Scrapy的博客。告诉世界你如何使用Scrapy。这将帮助新移民更多的例子和Scrapy项目增加其可见性。

  • issue tracker 中报告错误和请求功能,尝试遵循以下 Reporting bugs 详细说明。

  • 提交新功能和/或错误修复的补丁。有关如何编写和提交修补程序的详细信息,请参阅下面的 Writing patchesSubmitting patches

  • 加入 scrapy-users 邮件列表,并分享您的想法如何改进Scrapy。我们总是乐意接受建议。

报告错误

注解

请向 scrapy-security@googlegroups.com 报告安全问题 只要。这是一个只对受信任的Scrapy开发人员开放的私人列表,其存档不是公开的。

精心编写的错误报告非常有用,因此在报告新错误时,请记住以下准则。

  • 首先检查 常问问题,看看你的问题是否在一个着名的问题得到解决

  • 检查 open issues 以查看它是否已经被报告。如果有,请不要关闭报告,但检查机票历史记录和评论,您可以找到更多有用的信息。

  • 搜索 scrapy-users 列表,看看是否已经讨论过,或者如果你不确定你看到的是一个错误。您也可以在 #scrapy IRC频道询问。

  • 完整,可重复,具体的错误报告。测试用例越小越好。请记住,其他开发人员不会有您的项目来重现错误,所以请包括重现它需要的所有相关文件。参见例如StackOverflow的关于创建表现出问题的 Minimal, Complete, and Verifiable example 的指南。

  • 包括 scrapy version -v 的输出,所以开发工作在你的bug知道它发生了什么版本和平台,这通常是非常有用的再现它,或者知道它是否已经固定。

写补丁

写得更好的补丁是,它被接受的机会越高,并且越快被合并。

精心编写的补丁应该:

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

  • 通过所有单位测试。见下面的 Running tests

  • 包括一个(或多个)检查修复的错误或添加的新功能的测试用例。见下面的 Writing tests

  • 如果您要添加或更改公开(已记录)的API,请将文档更改包含在同一个补丁中。见下面的 Documentation policies

提交修补程序

提交补丁的最好方法是在GitHub上发布一个 pull request,可选择首先创建一个新的问题。

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

您还可以在创建补丁之前讨论新功能(或错误修复),但是有一个补丁准备好说明您的参数并显示您已经在主题中添加了一些额外的想法总是很好。一个好的起点是在GitHub上发送一个pull请求。它可以很简单地说明你的想法,并留下文档/测试以后,在该想法已经验证和证明是有用的。或者,您可以向 scrapy-users 发送电子邮件,以先讨论您的想法。当编写GitHub pull请求时,尽量保持标题短但描述性。例如。对于错误#411:“如果在start_requests中引发异常,Scrapy挂起”更喜欢“在start_requests(#411)中发生异常时修复挂起”,而不是“修复#411”。完整的标题可以很容易地浏览问题跟踪器。

最后,尝试保持美学更改(PEP 8 合规性,未使用的导入删除等)在单独的提交比功能更改。这将使拉式请求更容易审核,更有可能合并。

编码风格

在编写用于包含在Scrapy中的代码时,请遵循这些编码惯例:

  • 除非另有规定,请遵循 PEP 8

  • 如果它提高代码的可读性,可以使用长于80个字符的行。

  • 不要把你的名字放在你贡献的代码。我们的政策是将撰稿人的姓名保留在随Scrapy一起发布的 AUTHORS 文件中。

Scrapy Contrib

Scrapy contrib与Django contrib有相似的理由,这在 这个帖子 中有解释。如果你正在开发一个新的功能,请按照理由决定它是否应该是一个Scrapy贡献。如果不确定,你可以在 scrapy-users 问。

文档政策

  • 使用docstrings来记录类,或者已经在官方(sphinx)文档中记录的方法。例如,ItemLoader.add_value() 方法应该记录在sphinx文档中,而不是它的docstring。

  • 使用文档字符串来记录官方(sphinx)文档中不存在的函数,例如 scrapy.utils 包及其子模块的函数。

测试

测试使用 Twisted unit-testing framework 实现,运行测试需要 tox

运行测试

确保您最近有足够的 tox 安装:

tox --version

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

pip install -U tox

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

tox

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

tox -- tests/test_loader.py

要查看coverage报告安装 coveragepip install coverage)并运行:

coverage report

看到 coverage --help 的输出更多的选项,如html或xml报告。

写测试

所有功能(包括新功能和错误修复)必须包括一个测试用例,以检查它是否按预期工作,所以如果您希望它们更早被接受,请包括补丁的测试。

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

scrapy.loader

他们的单元测试在:

tests/test_loader.py