10. 开发者指南#

10.1. 开发者工具#

Imbalanced-learn 包含了许多用于辅助开发的工具。这些工具位于 imblearn.utils 中，并涵盖了多个类别的工具。以下所有的函数和类都在模块 imblearn.utils 中。

警告

这些实用程序旨在在imbalanced-learn包内部使用。它们不保证在imbalanced-learn的不同版本之间保持稳定。特别是，随着imbalanced-learn依赖项的发展，向后移植将被移除。

10.1.1. 验证工具#

这些是用于检查和验证输入的工具。当你编写一个接受数组、矩阵或稀疏矩阵作为参数的函数时，以下内容应在适用时使用。

10.1.2. 弃用#

警告

除了deprecate_parameter之外，本节的其余部分均来自scikit-learn。请参考他们的原始文档。

如果任何公开可访问的方法、函数、属性或参数被重命名，我们仍然会在两个版本中支持旧名称，并在调用/传递/访问时发出弃用警告。例如，如果函数 zero_one 被重命名为 zero_one_loss，我们会将装饰器 deprecated（来自 sklearn.utils）添加到 zero_one 并从该函数中调用 zero_one_loss：

from ..utils import deprecated

def zero_one_loss(y_true, y_pred, normalize=True):
    # actual implementation
    pass

@deprecated("Function 'zero_one' was renamed to 'zero_one_loss' "
            "in version 0.13 and will be removed in release 0.15. "
            "Default behavior is changed from 'normalize=False' to "
            "'normalize=True'")
def zero_one(y_true, y_pred, normalize=False):
    return zero_one_loss(y_true, y_pred, normalize)

如果一个属性将被弃用，可以在属性上使用装饰器 deprecated。例如，将属性 labels_ 重命名为 classes_ 可以这样做：

@property
@deprecated("Attribute labels_ was deprecated in version 0.13 and "
            "will be removed in 0.15. Use 'classes_' instead")
def labels_(self):
    return self.classes_

如果一个参数需要被弃用，请适当使用FutureWarning。 在以下示例中，k被弃用并重命名为n_clusters：

import warnings

def example_function(n_clusters=8, k=None):
    if k is not None:
        warnings.warn("'k' was renamed to n_clusters in version 0.13 and "
                      "will be removed in 0.15.", DeprecationWarning)
        n_clusters = k

如这些示例所示，警告消息应始终提供弃用发生的版本以及旧行为将被移除的版本。如果弃用发生在0.x-dev版本中，消息应说明弃用发生在0.x版本中，并且旧行为将在0.(x+2)版本中被移除。例如，如果弃用发生在0.18-dev版本中，消息应说明它发生在0.18版本中，并且旧行为将在0.20版本中被移除。

此外，应在文档字符串中添加一个弃用说明，回顾与上述弃用警告相同的信息。使用.. deprecated::指令：

.. deprecated:: 0.13
   ``k`` was renamed to ``n_clusters`` in version 0.13 and will be removed
   in 0.15.

在scikit-learn提供的所有功能之上，imbalanced-learn提供了deprecate_parameter：用于通过另一个参数（属性）来弃用采样器的参数。

10.2. 发布版本#

本节记录了进行新的不平衡学习版本发布所需的不同步骤。

10.2.1. 主要版本#

  • 更新发布说明 whats_new/v0. number>.rst，通过添加日期并从标题中移除“开发中”状态。

  • 运行 bumpversion release。它将移除 dev0 标签。

  • 提交更改 git commit -am "bumpversion 0. number>.0" （例如，git commit -am "bumpversion 0.5.0"）。

  • 为此版本创建一个分支 （例如，git checkout -b 0. number>.X）。

  • 将新分支推送到上游远程的imbalanced-learn仓库。

  • 更改imbalanced-learn 网站仓库中的symlink，使稳定版指向最新的发布版本，即0. number>。为此，克隆仓库，run unlink stable，然后执行ln -s 0. number> stable。要检查是否正确执行，请使用ls -l确保稳定版具有新的版本号。

  • 返回到您的imbalanced-learn仓库，在分支 0. number>.X。

  • 创建源代码分发和轮子：python setup.py sdist 和 python setup.py bdist_wheel。

  • 使用twine upload dist/*将这些文件上传到PyPI

  • 切换到master分支并运行bumpversion minor，在上游提交并推送。我们正式处于0. number + 1>.0.dev0。

  • 通过点击这里的“Draft a new release”来创建一个GitHub发布。 “Tag version”应该是最新的版本号（例如，0..0）， “Target”应该是该发布的分支 （例如，0. number>.X），而“Release title”应该是 “Version ”。在那里添加发布说明中的注释。

  • 在doc/whats_new/中添加一个新的v0.<版本号 + 1>.rst文件，并在doc/whats_new.rst中使用.. include::包含这个新文件。将该版本标记为开发中的版本。

  • 最后，前往conda-forge feedstock，当feedstock与PyPI仓库同步时，将创建一个新的PR。合并此PR，以便我们拥有conda的二进制文件。

10.2.2. Bug修复版本#

  • 使用git log找到你希望回移植的错误修复提交的提交哈希。

  • 检出最新发布的分支，例如， git checkout 0. number>.X。

  • 使用git cherry-pick 将错误修复提交附加到分支上。 或者，您可以从master分支使用交互式变基。

  • 使用 bumpversion patch 增加版本号。这将增加补丁版本，例如从 0.X.0 增加到 0.X.* dev0。

  • 将当前版本标记为发布版本（与dev版本相对） 使用bumpversion release --allow-dirty。它将提升版本号，例如从0.X.* dev0提升到0.X.1。

  • 使用 git commit -am 'bumpversion version>' 提交更改。

  • 将更改推送到上游的发布分支，例如 git push remote> branch>。

  • 使用与主要版本相同的流程在PyPI和conda-forge上上传。