Developer guideline
10. 开发者指南
10.1. 开发者工具函数
Imbalanced-learn 包含多种辅助开发的实用工具。这些工具位于 imblearn.utils 模块中，涵盖多个类别。以下列出的所有函数和类均属于模块 imblearn.utils。
警告
这些工具仅供 imbalanced-learn 包内部使用。它们在不同版本之间可能并不保持向后兼容。尤其是对旧版本功能的兼容支持（backports），会随着 imbalanced-learn 所依赖的库的发展而逐步移除。
10.1.1. 验证工具
这些工具用于检查和验证输入数据。当你编写接受数组、矩阵或稀疏矩阵作为参数的函数时，建议在适当的情况下使用以下工具：
check_neighbors_object: 检查对象是否适合作为最近邻（NN）模型。check_target_type: 检查目标变量类型是否符合当前采样器的要求。check_sampling_strategy: 检查采样策略是否一致，并返回一个字典，包含每个目标类别及其对应的样本数量。
10.1.2. 弃用机制
除了 deprecate_parameter 之外，本节其余内容均来自 scikit-learn。请参考其原始文档。
如果任何公开可访问的方法、函数、属性或参数被重命名，我们会在此后两个版本中继续支持旧名称，并在调用/传入/访问该名称时发出弃用警告。例如，若函数 zero_one 被重命名为 zero_one_loss，我们会在旧函数 zero_one 上添加 deprecated 装饰器（来自 sklearn.utils），并在该函数内部调用 zero_one_loss：
from ..utils import deprecated
def zero_one_loss(y_true, y_pred, normalize=True):
# 实际实现
pass
@deprecated("函数 'zero_one' 已在版本 0.13 中重命名为 'zero_one_loss'，"
"将在版本 0.15 中移除。默认行为由 'normalize=False' 改为 "
"'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("属性 labels_ 在版本 0.13 中已被弃用，"
"将在版本 0.15 中移除。请改用 'classes_'")
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' 参数已在版本 0.13 中重命名为 n_clusters，"
"将在版本 0.15 中移除。", DeprecationWarning)
n_clusters = k
如以上示例所示，警告信息应始终说明发生弃用的版本以及旧行为将被移除的版本。如果弃用发生在版本 0.x-dev 中，则消息中应注明弃用发生在 0.x 版本，并将在 0.(x+2) 版本中移除旧行为。例如，若弃用发生在 0.18-dev 版本，则消息应表明其发生在 0.18 版本，并且旧的行为将在 0.20 版本中被移除。
此外，应在文档字符串（docstring）中添加弃用说明，重申与上述弃用警告相同的信息。请使用 .. deprecated:: 指令：
.. deprecated:: 0.13
``k`` 参数在版本 0.13 中被重命名为 ``n_clusters``，并在版本 0.15 中移除。
除了 scikit-learn 提供的所有功能外，imbalanced-learn 还提供了 deprecate_parameter 函数：用于通过另一个参数替代某个采样器的参数（属性）。
10.2. 发布新版本
本节记录了发布新的 imbalanced-learn 版本所需的各个步骤。
10.2.1. 主版本发布
- 更新发布说明文件
whats_new/v0.<version number>.rst，添加日期并从标题中删除状态 “Under development”。 - 运行
bumpversion release。这会移除dev0标签。 - 提交更改：
git commit -am "bumpversion 0.<version number>.0"（例如：git commit -am "bumpversion 0.5.0"）。 - 为该版本创建分支（例如：
git checkout -b 0.<version number>.X）。 - 将新分支推送到上游的 imbalanced-learn 仓库。
- 在 imbalanced-learn 网站仓库 中修改
symlink，使 stable 指向最新的发布版本，即0.<version number>。操作方法是：克隆该仓库，运行unlink stable，接着运行ln -s 0.<version number> stable。要确认是否正确执行，请使用ls -l查看 stable 是否指向新的版本号。 - 返回你的 imbalanced-learn 仓库，并切换到
0.<version number>.X分支。 - 创建源代码分发包和 wheel 包：
python setup.py sdist和python setup.py bdist_wheel。 - 使用
twine upload dist/*将这些文件上传到 PyPI。 - 切换到
master分支，运行bumpversion minor，然后提交并推送到 upstream。此时我们正式进入版本0.<version number + 1>.0.dev0。 - 在 GitHub 上创建一个新的发布版本，点击 “Draft a new release”。“Tag version” 应为最新版本号（例如
0.<version>.0），“Target” 应为对应发布的分支（例如0.<version number>.X），而 “Release title” 应为 “Version ”。并将发布说明内容粘贴至此。 - 在
doc/whats_new/目录下新增一个v0.<version number + 1>.rst文件，并在doc/whats_new.rst中添加.. include::引用这个新文件，标记此版本为正在开发中的版本。 - 最后前往 conda-forge feedstock，当 feedstock 与 PyPI 同步时将会自动创建一个新的 PR。请合并此 PR，以便提供可用于
conda的二进制包。
10.2.2. 错误修复版本发布
- 使用
git log找到你想回溯提交的错误修复提交的哈希值。 - 切换到最后一个发布版本的分支，例如：
git checkout 0.<版本号>.X。 - 使用
git cherry-pick <哈希值>将修复提交追加到该分支。或者，你也可以从master分支使用交互式变基（rebase）方式添加。 - 使用
bumpversion patch命令增加版本号。这将升级补丁版本号，例如从0.X.0升级为0.X.* dev0。 - 使用
bumpversion release --allow-dirty将当前版本标记为正式发布版本（而非开发版本）。它会升级版本号，例如从0.X.* dev0升级为0.X.1。 - 使用
git commit -am 'bumpversion <新版本>'提交更改。 - 将更改推送到上游仓库的发布分支，例如：
git push <上游远程仓库> <发布分支>。 - 使用与主要版本发布时相同的方式上传到 PyPI 和 conda-forge。
该篇文章由ChatGPT翻译，如有疑问，欢迎提交Issues