贡献给 Biopython。

贡献给 Biopython 的指南

你想贡献给 Biopython，是吗？太棒了！新的贡献是该项目的生命线。然而，如果做得不正确，它们会迅速吞噬宝贵的开发时间。（我们也有日常工作！）这是一个关于向 Biopython 贡献代码的推荐方式的简短指南。

另请参阅 教程（PDF）中关于贡献的章节。

如果你已经做到了通过变更创建拉取请求，你应该阅读 CONTRIBUTING.rst，它描述了如何进行包括样式检查在内的自动化测试。

非代码贡献

即使你没有准备好或无法贡献代码，你仍然可以帮助我们。总有一些东西可以改进 文档（即使只是校对，或告诉我们某个部分是否不够清晰）。我们也需要邮件列表中的人来帮助解决初学者的疑问，或参与关于新功能的讨论。也许你可以为 wiki 食谱 提出一般性的示例？

寻找项目

最好的贡献是你已经在日常研究中使用过的代码。这应该是你认为可能对其他人有用的并且已经没有错误的代码。如果你正在考虑提交它，请继续执行步骤 2，提交代码！

否则，仍然有很多方法可以为 Biopython 做出贡献，包括编码和非编码贡献。一些你可以帮助的事情包括

• 更多单元测试：我们的一些模块仍然只有部分单元测试覆盖率。
• 支持更多程序：正在开发许多不同的生物信息学程序。识别目前 Biopython 不支持的程序并为其添加支持。
• 支持更多文件格式：我们可以读取和写入许多不同的文件格式，但总有更多格式。对于序列和比对，首先查看 SeqIO 和 AlignIO 页面。请注意，不鼓励针对特定网站的 HTML 解析器，因为这些解析器需要长期维护。
• 支持数据库：识别目前 Biopython 不支持的生物数据库并为其添加支持。
• 添加新的数据类型：你可以添加处理新类型数据的代码。不过，这是一个艰难的领域。创建新的健壮且有用的数据类型很困难，我们可能会犹豫添加某些东西，除非它已经被尝试和测试过。
• 添加新算法：你可以添加一个可能对其他生物学家有用的新算法。
• 解析器验证：由于 Biopython 支持越来越多的数据库，维护格式解析器的难度越来越大。这些格式变化非常快。因此，我们需要定期验证解析器是否仍然有效。例如，需要检查 GenBank 解析器以确保它能够处理 GenBank 的每次新转储。
• 回归测试：Biopython 使用回归测试框架来确保代码正常运行。虽然 Biopython 中的大部分功能都经过了测试，但仍然存在一些漏洞。
• 文档：教程并不完整，还需要一些工作。新用户在这里可以特别有用，因为你会学习新包。我们的 API 文档也需要改进，请参阅下面的编码规范。
• 新闻发布：如果你持续关注邮件列表（邮件列表的邮件量相当低），我们需要有人帮助将重要的帖子和事件总结为 新闻条目。

提交代码

一般来说，我们会考虑任何适用于生物或化学数据的代码。请不要提交功能与 Biopython 中已有的代码大量重叠的代码，除非有明显的改进并且你有一个集成代码的计划。

在你提交它之前，请检查它

• 它是通用的，并且可能对其他事情有用。
• 依赖关系是合理的。添加对第三方命令行工具的支持是可以的，但需要讨论添加额外的 Python 库。对商业封闭源代码软件的依赖可能不会被 Biopython 接受。
• 代码将使用 Biopython 许可证进行许可。
• 你必须拥有法律权利来贡献它并根据 Biopython 许可证对其进行许可。
• 你对维护它并响应错误报告充满热情。
• 你在代码中添加了文档字符串，并且愿意编写文档。
• 你已经编写了，或者愿意编写，一个用于新代码的单元测试。

如果所有这些条款看起来都可以接受，请将你的代码描述发送到 [email protected]（请参阅 邮件列表）。请务必在发送邮件之前订阅 biopython 邮件列表，否则你的邮件将被邮件服务器丢弃（这样做是为了避免邮件列表上的垃圾邮件）。不要直接将代码发送到 biopython 邮件列表。相反，请使用 我们的 GitHub 页面，通过创建问题并将文件附加或链接到你的 GitHub 分支。

编码规范

Biopython 试图遵循 PEP 8 和 PEP 257 中列出的编码规范。重要的要点是

• 类应该使用 AllFirstLetterUppercase 样式。
• 函数应该使用 lowercase_separated_by_underscores 样式。
• 变量使用 lowercase_separated_by_underscores 或 lowercasemungedtogether 样式，具体取决于你的偏好和变量的长度。
• _single_leading_underscores 表示内部函数或类，用户不应该直接调用它们。
• 制表符很糟糕。现在 Python 社区中的大多数人都不喜欢制表符，而是更喜欢使用 4 个空格进行缩进。大多数编辑器可以帮助你解决这个问题（例如，Emacs python-mode 使用 4 个空格规则）。Python 发行版中的 Tools/scripts/reindent.py 将有助于消除文件中的制表符。

一个值得注意的例外是模块名称，我们倾向于使用首字母大写。事后看来，这很不幸，但我们受到向后兼容性的限制。

Epydoc 和/或 Sphinx apidoc 用于生成源代码的自动文档，因此在代码中添加有用的注释非常有用，以便它们能够反映在 API 文档 中（除了所有正常的文档代码的原因之外）。

我们通常不会做任何花哨的事情来尝试格式化代码中的注释 - 但它们被解释为 reStructuredText 标记，它允许像项目符号和斜体这样的东西。这不是花哨的，但它很有效，而且比处理尝试结构化源代码注释的无数不同方法更容易。

但是，有一些技巧可以使你的文档看起来最好。主要的技巧是

• 模块、类和函数文档应该以一行描述开始。这必须以句号结束。

这是一个模块文档的示例，以便 epydoc 可以正常工作

"""This is a one line description of the module followed with a period.

More information about the module and its goals and usage.
"""


class MyClass:
    """One line description of the class followed by a period.

    More information about the class -- its purpose, usage, and
    implementation.
    """

    def my_function(self, spam):
        """A terse description of my function followed with a period.

        A longer description with all kinds of additional goodies. This may
        include information about what the function does, along with
        what parameters it will be passed and what it returns. You know,
        information so people know how to use the function.
        """
        # the code ...