API稳定性

scikit-bio中的所有公共功能都有一个定义的稳定状态。这些状态通知用户和开发人员他们可以在多大程度上依赖于包中的不同api。

您可以通过查看公共功能的docstring来了解其稳定性状态，它的格式基于 numpydoc . 这些信息要么在 扩展摘要 部分，或者在不推荐的情况下，此信息将显示为 小结 .

下图说明了scikit-bio中的API生命周期：

稳定性状态的定义和与之相关的信息如下。

稳定的

定义为稳定的功能是scikit-bio向后兼容API的一部分。用户可以确信，如果不首先通过不推荐的状态（通常至少在两个发布周期内），API不会更改。我们尽一切努力维护此代码的API。

稳定功能的docstrings将指示第一个scikit-bio版本，其中功能被认为是稳定的。

实验

定义为实验性的功能正在考虑添加到scikit bio的稳定API中。鼓励用户使用此代码，但要注意其API可能会更改或被删除。实验性功能通常会在被删除之前经过弃用状态，但在极少数情况下，它可能会被直接删除（例如，如果发现一个严重的方法缺陷，使功能在科学上无效）。

实验性功能的docstrings将指示scikit的第一个bio版本，其中该功能被认为是实验性的。

我们的目标是在实验阶段快速地移动功能（例如，在进入稳定阶段之前发布两个版本），但是我们没有对实验功能何时变得稳定做出具体承诺。这与我们的理念一致，我们不承诺实验性的api，只承诺稳定的api。

已弃用

定义为已弃用的功能的目标是从scikit-bio中删除。用户应该放弃使用它。

已弃用功能的docstrings将指示scikit-bio的第一个版本（其中该功能已被弃用）、scikit bio的版本（当该功能将被删除时）以及代码被弃用的原因（例如，因为某个函数被确定为科学上无效的，或是因为API被改编，用户应该使用不同版本的功能）。

使用不推荐的功能将引发 DeprecationWarning . 从Python2.7开始，这些类型的警告是 默认静音 . 在开发使用scikit-bio的工具时，我们建议启用禁用警告的显示，以通知即将发生的API更改。有关如何显示弃用警告的详细信息，请参阅 Python's deprecation warning docs .