编码规范#

编码风格#

在编码方面，我们遵循

  • 我们遵循 PEP8 编码指南。一个好的示例可以在 这里 找到。

  • 根据 ruff 进行代码格式化

代码格式化和静态检查#

我们遵循以下代码格式化标准

这通过我们的 CI/CD 工作流程，经由 pre-commit 来强制执行。

完整的 pre-commit 配置可在 .pre-commit-config.yaml 中找到。额外配置可在 pyproject.toml 中找到。

sktime 特定代码格式化约定#

  • 在非类名中使用下划线分隔单词：使用 n_instances 而非 ninstances。

  • 例外情况是，大写字母 X、Y、Z 可以作为变量名或变量名的一部分（例如 X_train），如果它们用于指代数据集，并且符合 PEP8 关于此类变量名在特定领域（此处指与 scikit-learn 相邻的生态系统）已有先例使用的约定。

  • 避免一行中有多个语句。控制流语句（if/for）后优先换行。

  • 在 sktime 内部引用时使用绝对导入。

  • 不要在源代码中使用 import *。官方 Python 推荐认为这是有害的。它使代码更难阅读，因为符号的来源不再明确引用，但最重要的是，它阻止使用像 pyflakes 这样的静态分析工具自动查找错误。

设置本地代码质量检查#

设置本地代码质量检查有两种选择

  • 使用 pre-commit 进行自动化代码格式化

  • 在本地开发 IDE 中手动设置 ruff 和/或 numpydoc

使用 pre-commit#

要在安装了 sktime dev 依赖项的 Python 环境中设置 pre-commit，请按照以下步骤操作。

在您的 Python 环境中以及本地仓库克隆的根目录中输入以下内容

  1. 如果尚未安装，请确保安装了带有 dev 依赖项的 sktime，其中包含 pre-commit

pip install -e .[dev]

  1. 设置 pre-commit

pre-commit install

安装后，pre-commit 将在您每次提交新更改时，自动对您更改的文件运行所有 sktime 代码质量检查。

您可以在 .pre-commit-config.yaml 中找到我们的 pre-commit 配置。额外配置可在 pyproject.toml 中找到。

注意

如果您想排除某一行代码不被检查，可以在该行末尾添加 # noqa: rule（无质量保证）注释。可以排除的规则集可以在此处找到 ruff rules。

与本地开发者 IDE 集成#

本地开发者 IDE 通常会集成常见的代码质量检查，但需要在 IDE 中进行特定设置。

对于 Visual Studio Code，需要在偏好设置中单独激活 ruff 和/或 numpydoc。您可以从 marketplace 安装 ruff vscode 扩展，其链接在此处 ruff extension。Ruff VS Code 扩展将遵循您项目中 pyproject.toml、ruff.toml 或 .ruff.toml file 文件中定义的任何 Ruff 配置，这意味着安装扩展后即可立即使用。IDE 使用的 Python 环境需要安装 ruff 等包，这可以通过安装带有 dev 依赖项的 sktime 来实现。

在 Visual Studio Code 中，我们还建议在本地 settings.json 中添加 "editor.ruler": 88 来显示最大行长。

API 设计#

sktime 的总体设计方法在论文 “Designing Machine Learning Toolboxes: Concepts, Principles and Patterns” 中有所描述。

注意

非常欢迎反馈和改进建议！