DeepChem 开发规范指南从 pre-commit 到类型注解的完整代码质量保障体系【免费下载链接】deepchemDemocratizing Deep-Learning for Drug Discovery, Quantum Chemistry, Materials Science and Biology项目地址: https://gitcode.com/GitHub_Trending/de/deepchem本篇技术指南以 DeepChem 官方开发文档中的 Coding Conventions 为核心系统讲解这个药物发现、量子化学与材料科学深度学习框架的代码质量规范体系。你将掌握 DeepChem 贡献者提交代码前的完整检查流程如何通过 pre-commit 自动化钩子、YAPF 格式化、Flake8 静态检查、numpy 规范 Docstring、pytest 单元测试含机器学习模型专项测试以及 mypy 类型注解来保证代码风格统一、逻辑正确且可维护并了解仓库中与之配套的配置文件与真实测试用例。为什么需要一套编码规范DeepChem 的代码库横跨 deepchem/data、deepchem/feat、deepchem/models含 torch_models、jax_models、deepchem/dock 等数十个模块涉及 TensorFlow、PyTorch、JAX、scikit-learn 多种后端。在这样的多后端、多人协作场景下统一编码规范的价值主要体现在两方面在代码审查前自动拦截低级问题语法错误、拼写错误、未使用的代码、不规范的缩进等都可以在提交阶段由机器自动发现避免浪费审查者的时间消除格式争论当所有代码都由同一套格式化工具处理时团队不必再为这段代码应该怎么排版产生分歧讨论精力可以聚焦在真正的算法与设计问题上。该指南对应的核心配置文件位于仓库根目录的 .pre-commit-config.yaml它一次性声明了 YAPF、Flake8、mypy 等多个钩子是下面所有规范落地的总入口。用 pre-commit 在提交前自动执行检查pre-commit 是一个在每次git commit前自动运行一组钩子hooks的框架DeepChem 用它把 lint、代码约定和类型注解检查固化到开发流程中。虽然初次接触时可能觉得为什么要跑这么多测试和检查但它能在代码进入人工审查之前就识别出简单问题。安装钩子脚本在仓库根目录执行pre-commit install安装之后每次 commit 时 pre-commit 都会自动对修改过的文件运行必要的钩子。DeepChem 的钩子清单从 .pre-commit-config.yaml 可以看到仓库实际配置的四类钩子钩子来源版本检查内容pre-commit/pre-commit-hooksv3.4.0check-merge-conflict检查未解决的合并冲突、trailing-whitespace尾随空白、end-of-file-fixer文件末尾换行、check-yamlYAML 语法pre-commit/mirrors-yapfv0.32.0以 YAPF 0.32 执行 Python 代码格式化PyCQA/flake83.8.4以--count参数运行 Flake8 静态检查pre-commit/mirrors-mypyv0.790以--ignore-missing-imports参数运行 mypy 类型检查值得注意的是这些钩子与文档正文保持严格一致YAPF 固定为 0.32.0flake8 使用--countmypy 使用--ignore-missing-imports——这正是后面各小节命令行参数的来源。如果你希望在本地获得与 CI 一致的环境requirements/env_common.yml 中同样将pre-commit列入了 pip 依赖。用 YAPF 统一代码格式DeepChem 使用 Google 的 YAPF 格式化全库代码。YAPF 偶尔会产出略显笨拙的排版但它有两个核心优势保证整个代码库完全一致不会出现不同开发者风格各异的情况避免格式争论机器裁决人不再参与排版争吵。修改文件后手动格式化每次修改文件后在提交前对它运行 YAPFyapf -i modified file-i参数表示原地修改in-place直接改写文件内容。版本必须与 CI 一致每个 Pull Request 上都会运行 YAPF 校验格式如果忘记格式化CI 会提醒你。关键约束是版本一致性不同版本的 YAPF 可能产生不同结果因此必须使用与 CI 相同的版本当前为0.32仓库会定期升级。这一约束在配置文件中有双重印证钩子配置 .pre-commit-config.yaml 中mirrors-yapf固定为v0.32.0测试环境 requirements/env_test.yml 中也精确锁定yapf0.32.0。YAPF 的仓库级风格基线在 setup.cfg 的[yapf]段可以查看仓库的格式化基线[yapf] based_on_style google indent_width 4即以 Google 风格为基底、4 空格缩进。这意味着运行yapf -i并非随意排版而是落到一套有据可查的风格规则上。用 Flake8 做语法与风格检查Flake8 用于检查代码语法。Lint 工具的核心收益有两点预防语法错误和拼写错误节省审查时间审查者无需再检查未使用的代码或笔误。本地检查命令修改文件后对它运行flake8 modified file --count如果命令返回0说明你的代码通过了 Flake8 检查。仓库的 Flake8 策略setup.cfg 的[flake8]段展示了 DeepChem 的具体取舍忽略了一批风格类告警如 E111/E114 缩进非 4 的倍数、E121/E124/E126/E127 缩进续行类、W503/W504 二元运算符换行位置、W605 无效转义序列、E722 裸except等max-line-length 300放宽了默认的行宽限制——这符合科学计算代码中长表达式、长函数签名的实际情况。在 CI 层面scripts/flake8_for_ci.sh 给出了完整流程它依次对deepchem/data、deepchem/feat、deepchem/models、deepchem/utils、deepchem/molnet等核心模块执行flake8 ${item} --exclude__init__.py --count --show-source --statistics即排除__init__.py、显示违规源码并输出统计。你可以通过source scripts/flake8_for_ci.sh在本地复现 CI 的检查范围。Docstring所有类与函数都必须有文档规范要求所有类和函数都包含描述其用途与预期用法的 docstring。拿不准要写多少信息时宁可多写也不要少写。一份合格的 docstring 应当说明这个类/函数要解决什么问题它使用了什么算法如何正确使用它适当时引用相关出版物。遵循 numpy 文档规范所有 docstring 必须遵循 numpy docstring 格式约定 各模块的源码风格一致。用 doctest 验证文档示例为了确保 docstring 中的代码示例确实能运行需要对修改的文件执行python -m doctest modified file单元测试未测试的功能等于未完成规范的立场非常鲜明如果你没有为一个功能写测试那么这个功能就还没完成。未测试的代码很可能是无法正常工作的代码。 拥有大量的测试用例是保证代码正确性的根本。数值代码的测试策略复杂数值代码的完整测试往往有挑战算法产出结果后有时难以判断结果是否正确。规范给出的原则是尽可能寻找答案精确已知的简单示例来测试某些情况下依赖随机性测试stochastic tests代码正确时大概率通过、出错时大概率失败。这类测试被预期会有小比例偶发失败因此可以打上flaky注解——如果它在 CI 中失败会被再运行一次只有再次失败才报错。flaky注解在仓库中应用广泛例如 deepchem/models/tests/test_gan.py6 处、deepchem/hyper/tests/test_gaussian_hyperparam_opt.py3 处、deepchem/metalearning/tests/test_maml.py 等多出现在生成式模型与随机优化这类天然带随机性的测试中。慢测试的标记与运行每个测试最好能在几秒内完成但偶尔无法做到。此时用pytest.mark.slow标记。慢测试在 CI 中会被跳过因此破坏它们的改动可能偶尔漏进仓库团队仍会定期运行它们希望问题能较快暴露。从仓库根目录运行全部慢测试pytest -v -m slow deepchem仓库中真实存在大量慢测试用例例如 deepchem/models/tests/test_graph_models.py 中多处同时叠加pytest.mark.slow与pytest.mark.tensorflow标记deepchem/models/tests/test_atomic_conv.py 中同样如此。pytest 标记体系在 setup.cfg 的[tool:pytest]段注册jax、torch、tensorflow、slow、serial、dqc、hf其中 slow 标记的说明正是标记慢测试可用-m not slow反选排除。本地开发环境的可编辑安装要在本地测试你的代码改动需要把开发目录以符号链接方式接入 Python 环境。以源码方式安装包时执行python setup.py develop这会让你import包时直接看到源码改动从而能够在单元测试中导入新类/新方法。提交前必须本地通过确保测试在本地通过检查命令python -m pytest modified file机器学习模型的专项测试测试机器学习模型的正确性在实践中相当棘手。向 DeepChem 新增一个模型时至少要添加以下几类基础单元测试过拟合测试Overfitting Test创建一个小型合成数据集验证模型能以高精度学会它对回归与分类任务表现为训练集上的低训练误差对生成任务表现为训练集上的低训练损失。仓库中 deepchem/models/tests/test_overfit.py 是这一测试类型的典型实现包含test_sklearn_regression_overfit、test_sklearn_classification_overfit、test_regression_overfit、test_classification_overfit、test_multitask_classification_overfit、test_robust_multitask_classification_overfit标记pytest.mark.tensorflow、test_multitask_regression_overfit标记pytest.mark.torch等数十个用例覆盖 sklearn、TensorFlow、PyTorch 三种后端与单任务、多任务、稳健多任务等多种模型形态。重载测试Reloading Test检查训练好的模型能否正确保存到磁盘并重新加载关键判定标准是保存前与重载后模型产出的预测必须完全一致。注意单元测试不足以衡量模型的真实性能。你还应在更大的数据集上做 benchmark并把基准测试结果写进 PR 评论。TensorFlow 与 PyTorch 分环境测试TensorFlow 2.6 支持 numpy 1.19而 PyTorch 支持 numpy 1.21这种 numpy 依赖版本差异有时会导致二者无法共存于同一环境。因此规范建议在不同的 conda 环境中分别测试两种后端的模型。创建 TensorFlow 测试环境并运行conda create -n tf-test python3.8 conda activate tf-test pip install conda-merge conda-merge requirements/tensorflow/env_tensorflow.yml requirements/env_test.yml env.yml conda env update --file env.yml --prune pytest -v -m tensorflow deepchem创建 PyTorch 测试环境并运行conda create -n pytorch-test python3.8 conda activate pytorch-test pip install conda-merge conda-merge requirements/torch/env_torch.yml requirements/torch/env_torch.cpu.yml requirements/env_test.yml env.yml conda env update --file env.yml --prune pytest -v -m torch deepchem这两段流程用conda-merge将框架专用环境文件与通用测试环境文件 requirements/env_test.yml 合并后者包含flake8、flaky、mypy1.15.0、pytest、pytest-cov、types-setuptools、yapf0.32.0等测试与检查工具再以--prune更新环境最终通过-m tensorflow/-m torch选择对应后端的测试集合执行。这与 setup.cfg 中注册的tensorflow、torch标记一一对应也与 deepchem/models/tests/test_overfit.py、deepchem/models/tests/test_graph_models.py 中大量pytest.mark.tensorflow/pytest.mark.torch标注相印证。类型注解用 mypy 静态验证正确性类型注解是避免 bug 的重要工具。所有新代码都必须为函数参数和返回值提供类型注解当对没有类型注解的存量代码做较大改动时也应考虑同步补上注解。本地运行 mypymypy 静态类型检查器会在每个 Pull Request 上自动运行。在本地、提交前验证类型用法是否正确先cd到仓库顶层目录再执行mypy -p deepchem --ignore-missing-imports输入宽松、输出严格Python 是动态语言有时难以确定该写什么类型。规范给出的经验法则是输入类型尽量宽松permissive例如很多函数文档上写接受一个 list实际用 tuple 也完全没问题此时输入类型应写为Sequence以同时接受两者输出类型必须严格strict如果函数返回 list就明确标注List因为我们可以保证返回值永远是该精确类型。NumPy 数组的特殊约定很多函数文档上写接受一个数组实际却能接受任何 array-like 对象数字列表、数字列表的列表、数组的列表等。此时类型标注为Sequence。反过来如果函数确实要求 ndarray、传入其他类型会失败则标注为np.ndarray。deepchem.utils.typing 公共类型deepchem/utils/typing.py 模块定义了一些在 DeepChem API 中频繁出现的类型别名标注代码时可以直接复用类型别名含义ArrayLikeNumPy 数组或可转换为数组的对象Union[np.ndarray, Sequence]即输入宽松原则的落地OneOrMany单个值或一组值Union[T, Sequence[T]]ShapeNumPy 数组形状Tuple[int, ...]ActivationFn激活函数函数或标准激活函数名字符串LossFn用于 KerasModel/TorchModel 的损失函数签名RDKitMol/RDKitAtom/RDKitBondRDKit 对象占位类型PymatgenStructure/PymatgenCompositionPymatgen 对象占位类型其中ArrayLike的注释明确写道一旦项目升级到 NumPy 1.20将用numpy.typing.ArrayLike替代——这正体现了输入宽松约定在公共 API 层的制度化。一条完整的提交检查清单综合上述规范一次符合 DeepChem 开发标准的代码提交大致需要经过pre-commit install安装钩子让每次 commit 自动触发全部检查合并冲突、尾随空白、YAML 语法、YAPF、Flake8、mypy对修改的文件运行yapf -i file版本 0.32与 CI 一致保证格式合规对修改的文件运行flake8 file --count返回 0 才算通过为新类/新函数编写遵循 numpy 规范的 docstring并运行python -m doctest file验证示例编写单元测试能秒级完成的不打标记慢测试打pytest.mark.slow随机性测试打flaky新增模型必须包含过拟合测试与重载测试python setup.py develop安装可编辑包后运行python -m pytest modified file确保本地通过TensorFlow 与 PyTorch 模型分别在独立 conda 环境tf-test / pytorch-test中通过pytest -v -m tensorflow deepchem与pytest -v -m torch deepchem验证为所有新代码补充类型注解运行mypy -p deepchem --ignore-missing-imports静态校验。这套流程在仓库中并非纸上谈兵——.pre-commit-config.yaml、setup.cfg、requirements/env_test.yml、scripts/flake8_for_ci.sh 与 deepchem/models/tests/test_overfit.py 等测试文件共同构成了一个可运行、可复现的质量保障体系任何 DeepChem 贡献者都可以对照本文在本地完整复现 CI 的检查行为。【免费下载链接】deepchemDemocratizing Deep-Learning for Drug Discovery, Quantum Chemistry, Materials Science and Biology项目地址: https://gitcode.com/GitHub_Trending/de/deepchem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
