弃用策略

随着生物信息学和计算生物学快速发展，一些以前开发的 Biopython 模块可能不再与当今世界相关。为了保持代码库的整洁，我们的目标是从 Biopython 中弃用并删除此类代码，同时避免对可能依赖旧代码的用户造成任何意外情况。

我们使用相同的流程来弃用过时的模块、方法、函数和类。

我们在 Biopython 源代码中保留一个纯文本文件来记录这些更改，名为 DEPRECATED.rst。

这是当前从 Biopython 弃用和删除代码的策略

• 首先，在 Biopython 邮件列表 上询问给定代码段是否有任何用户。请记住，并非所有用户都关注 Biopython 邮件列表。
• 考虑在弃用 *之前* 将模块声明为“过时”。无需代码更改，只需
  • 在 DEPRECATED 文件中记录此信息，
  • 在模块文档字符串的第一行添加“(OBSOLETE)”
  • 使用模块文档字符串解释模块过时的原因以及应该使用什么来代替。
  • 由于应该避免在 Biopython 代码库中使用过时代码，因此开始用新推荐的代码替换过时代码。这也有助于验证代码是否可以实际弃用和删除。为了更轻松地跟踪更改，可以使用多个拉取请求来替换过时代码。
  • 开始重新组织或重写 Biopython 文档，以便将用户指向新推荐的代码，而不是指向弃用的代码。但是，在弃用过程中，过时代码的描述应该保留在文档中，直到代码被实际删除。
• 如果没有任何明显的用户，则实际弃用它
  • 在 DEPRECATED 文件中记录此信息，
  • 在模块文档字符串的第一行添加“(DEPRECATED)”
  • 使用模块文档字符串来解释任何必要的迁移，理想情况下包含示例或对教程的引用。
  • 最重要的是，在代码中添加一个 BiopythonDeprecationWarning（Python 的 DeprecationWarning 默认情况下是静默的）

import warnings
from Bio import BiopythonDeprecationWarning

warnings.warn(
    "Bio.SomeModule has been deprecated, and we intend to remove it"
    " in a future release of Biopython. Please use the SomeOtherModule"
    " instead, as described in the Tutorial. If you would like to"
    " continue using Bio.SomeModule, please contact the Biopython"
    " developers via the mailing list or GitHub.",
    BiopythonDeprecationWarning,
)

• 在测试中静默新的警告，例如，如果您的测试使用 from Bio import SomeModule，请将其替换为

from Bio import BiopythonDeprecationWarning

with warnings.catch_warnings():
    warnings.simplefilter("ignore", BiopythonDeprecationWarning)
    from Bio import SomeModule

• 原则上，我们要求在实际删除代码之前进行两次带有弃用警告的 Biopython 发布。
• 此外，第一个带有弃用警告的 Biopython 版本与第一个实际删除代码的 Biopython 版本之间至少要间隔一年。

查看邮件列表上的讨论

http://lists.open-bio.org/pipermail/biopython-dev/2008-November/004920.html