PyTorch Image Modelstimm贡献指南代码风格约定、开发环境搭建与单元测试实战【免费下载链接】pytorch-image-modelsThe largest collection of PyTorch image encoders / backbones. Including train, eval, inference, export scripts, and pretrained weights -- ResNet, ResNeXT, EfficientNet, NFNet, Vision Transformer (ViT), MobileNetV4, MobileNet-V3 V2, RegNet, DPN, CSPNet, Swin Transformer, MaxViT, CoAtNet, ConvNeXt, and more项目地址: https://gitcode.com/GitHub_Trending/py/pytorch-image-models本文以仓库根目录的 CONTRIBUTING.md 为主体系统梳理 timm 项目对代码、文档、类型标注的规范要求并给出完整的开发环境安装、pytest 单元测试筛选与并行执行的实操方法。读完后你可以按照维护者认可的编码风格修改代码、搭建本地测试环境、用标记marker与-k表达式高效运行测试子集并了解 CI 是如何按标记拆分测试矩阵的。一、代码风格约定Coding StyleCONTRIBUTING.md 首先说明timm 目前没有强制的 lint / auto-format 工具链Black 等尚未全面引入但持开放态度在过渡期内贡献代码的风格基线是Google Python Style Guide并在此基础上有几处明确的具体约定。1.1 两个核心差异120 字符行宽与悬挂缩进行宽 120 字符。超过 120 字符在特定情况下可以接受例如维护者倾向于不把 URL 拆行书写。悬挂缩进hanging indent是首选。文档明确要求避免把参数与右括号/右花括号对齐的写法。以下对照示例直接来自 CONTRIBUTING.md不推荐参数与左括号对齐# Aligned with opening delimiter. foo long_function_name(var_one, var_two, var_three, var_four) meal (spam, beans) # Aligned with opening delimiter in a dictionary. foo { long_dictionary_key: value1 value2, ... }推荐4 空格悬挂缩进首行不放内容右括号独立成行# 4-space hanging indent; nothing on first line, # closing parenthesis on a new line. foo long_function_name( var_one, var_two, var_three, var_four ) meal ( spam, beans, ) # 4-space hanging indent in a dictionary. foo { long_dictionary_key: long_dictionary_value, ... }1.2 与 Black / Ruff 的一处分歧函数参数缩进文档指出 timm 的风格与 Black / Ruff大体兼容但由于维护者自 Black 出现之前就一直遵循 PEP 8因此在函数定义处参数列表的缩进上坚持 PEP 8 的做法——参数列表需要比def再多一级缩进。Black 风格的写法文档中标注为需要调整的一方def very_important_function( template: str, *variables, file: os.PathLike, engine: str, header: bool True, debug: bool False, ): with open(file, w) as f: ...按 timm 期望的 PEP 8 缩进参数应再缩进一级def very_important_function( template: str, *variables, file: os.PathLike, engine: str, header: bool True, debug: bool False, ): with open(file, w) as f: ...文档特别强调请不要对既有文件整体运行 Black把全文件的参数缩进一次性转换掉原话还带了一句幽默的I do like sadface though。1.3 文件内风格不一致时跟随该文件由于 timm 各部分代码来源众多并非所有文件都已更新到当前期望的风格因此文档给出的规则是当某个源文件内部风格不一致时请遵循该文件自身的既有风格。此外还有两条 PR 卫生规范避免格式化与你 PR 无关的代码纯格式化 / 风格修复的 PR 会被接受但必须与功能性改动隔离且最好在动手前先与维护者确认。值得注意的是pyproject.toml 末尾已出现[tool.wruff.format]配置段quote-style preserve、preview true从源码结构看项目正在逐步向 Ruff 系格式化工具靠拢这印证了文档中auto-format 尚未就位但开放考虑的说法。二、文档字符串与类型标注DocumentationCONTRIBUTING.md 的 Documentation 一节提出三条要求docstring 风格同样基于 Google Python Style Guide类型标注的目标让所有主要函数和__init__方法逐步具备 PEP 484 类型标注标注是唯一事实来源一旦函数使用了类型标注就不要在 docstring 中重复标注内容类型标注作为 typing 的唯一来源one source of truth。文档还坦承相对 timm 的功能面当前文档存在大量空白鼓励贡献者document away——为缺失的模块、参数和用法补写文档本身就是有价值的贡献方向。三、开发环境搭建InstallationCONTRIBUTING.md 给出的安装步骤非常简洁用Python 3.10创建虚拟环境按系统选择安装torch与torchvision参考 PyTorch 官方站点对应系统的安装说明然后安装其余依赖并以可编辑模式安装 timmpython -m pip install -r requirements.txt python -m pip install -r requirements-dev.txt # for testing python -m pip install -e .结合仓库中的实际依赖文件可以更精确地理解每一步装了什么requirements.txt运行时依赖包含torch1.7、torchvision、pyyaml、huggingface_hub0.17.0、safetensors0.2、numpy。这也与 pyproject.toml 中[project] dependencies的声明一致requirements-dev.txt测试依赖包含pytest、pytest-timeout、pytest-xdist、pytest-forked、expecttest。其中pytest-xdist正是下文并行测试-n选项的实现pytest-forked则支撑 CI 中使用的--forked模式pyproject.toml 中requires-python 3.8即 Python 3.8 及以上均可安装而 timm/version.py 当前版本号为1.0.29.dev0。贡献指南推荐 Python 3.10 与 CI 的基线环境保持一致见下文测试矩阵。可编辑安装-e .的意义在于本地修改timm/下的源码后无需重新打包import timm即生效适合边改边测。四、单元测试运行、筛选与并行Unit tests4.1 基本运行方式CONTRIBUTING.md 给出全量测试命令pytest tests/文档明确指出全量测试套件在本地耗时很长a few hours因此建议针对自己改动相关的测试进行子集运行。4.2 用-k按名称筛选、-n并行执行pytest -k substring-to-match -n 4 tests/-k选项按测试函数/类的名称做子串匹配或表达式匹配例如pytest -k resnet tests/test_models.py只跑名称中包含 resnet 的测试-n选项由 requirements-dev.txt 中的pytest-xdist插件提供上例表示以 4 个进程并行执行。从源码结构看[pyproject.toml](https://link.gitcode.com/i/07618576908ed3655651636fea40f3cc)的[tool.pytest.ini_options]已声明testpaths [tests]因此实际直接运行pytest也会定位到tests/目录文档示例中显式写出tests/路径只是更直白的写法。4.3 测试标记markers体系与 CI 矩阵pyproject.toml 中注册了 6 个 pytest 标记这是理解 timm 测试组织的钥匙标记用途base使用基本配置跑的模型测试cfg校验模型配置config的测试torchscriptTorchScript 路径的模型测试features特征提取feature extraction相关测试fxforwardTorch FX 前向测试fxbackwardTorch FX 反向测试.github/workflows/tests.yml 展示了这些标记如何被 CI 消费测试任务按testmarker维度拆分成多个并行 runner每个 runner 执行类似pytest -vv --forked --durations0 -m marker tests的命令其中-m按标记选择测试--forked让每个测试在独立子进程中运行--durations0输出耗时排序。该矩阵还覆盖 Python 3.10 / 3.13 与 torch 1.13.0 / 2.9.1 的组合Linux 上通过LD_PRELOAD加载 tcmalloc 控制内存行为。tests/test_models.py 的文件头注释进一步贡献了一条对贡献者很实用的规则新增测试必须使用上述已有标记之一或注册新标记如果使用新标记必须同步调整 tests.yml 中的测试矩阵否则 CI 会直接跳过这些测试。文件头部还给出了按 CI 环境区分的大模型排除清单EXCLUDE_FILTERS等实现细节说明模型级测试对运行环境的资源敏感贡献新模型时最好参照该文件的过滤与超时约定来组织测试。五、构建文档Building documentationCONTRIBUTING.md 将文档构建指向仓库内的hfdocs目录该目录下的 hfdocs/README.md 给出了本地构建 Hugging Face 文档的具体步骤先安装 doc-builder 工具及watchdog、black依赖然后在本地预览文档doc-builder preview timm hfdocs/source文档的源文件位于 hfdocs/source 下models/子目录按模型逐一组织如 resnet.mdx、efficientnet.mdxreference/子目录则覆盖 data.mdx、models.mdx、optimizers.mdx、schedulers.mdx 等 API 参考页。从源码结构看贡献文档主要是按 hfdocs/source/_toctree.yml 的目录结构补充/修正这些.mdx页面。六、提问渠道QuestionsCONTRIBUTING.md 建议关于贡献方式、贡献位置的任何疑问先到项目的 Discussions 中提有专门的Contributing话题分类而不是直接开 PR 试错。七、要点速查风格基线Google Python Style Guide 120 字符行宽 4 空格悬挂缩进右括号独立成行与 Black 的唯一明确分歧是函数定义参数缩进坚持 PEP 8 多一级缩进不要对存量文件整体跑 Black文件内风格不一致时跟随该文件既有风格纯格式化 PR 需与功能改动隔离并事先沟通类型标注是 typing 唯一事实来源docstring 不重复标注环境Python 3.10 虚拟环境 torch/torchvision pip install -r requirements.txt -r requirements-dev.txtpip install -e .测试pytest tests/全量数小时-k筛选、-n并行按 marker 组织测试并保持与 tests.yml 矩阵一致文档按 hfdocs/README.md 用 doc-builder 本地预览。【免费下载链接】pytorch-image-modelsThe largest collection of PyTorch image encoders / backbones. Including train, eval, inference, export scripts, and pretrained weights -- ResNet, ResNeXT, EfficientNet, NFNet, Vision Transformer (ViT), MobileNetV4, MobileNet-V3 V2, RegNet, DPN, CSPNet, Swin Transformer, MaxViT, CoAtNet, ConvNeXt, and more项目地址: https://gitcode.com/GitHub_Trending/py/pytorch-image-models创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PyTorch Image Models（timm）贡献指南：代码风格约定、开发环境搭建与单元测试实战
PyTorch Image Modelstimm贡献指南代码风格约定、开发环境搭建与单元测试实战【免费下载链接】pytorch-image-modelsThe largest collection of PyTorch image encoders / backbones. Including train, eval, inference, export scripts, and pretrained weights -- ResNet, ResNeXT, EfficientNet, NFNet, Vision Transformer (ViT), MobileNetV4, MobileNet-V3 V2, RegNet, DPN, CSPNet, Swin Transformer, MaxViT, CoAtNet, ConvNeXt, and more项目地址: https://gitcode.com/GitHub_Trending/py/pytorch-image-models本文以仓库根目录的 CONTRIBUTING.md 为主体系统梳理 timm 项目对代码、文档、类型标注的规范要求并给出完整的开发环境安装、pytest 单元测试筛选与并行执行的实操方法。读完后你可以按照维护者认可的编码风格修改代码、搭建本地测试环境、用标记marker与-k表达式高效运行测试子集并了解 CI 是如何按标记拆分测试矩阵的。一、代码风格约定Coding StyleCONTRIBUTING.md 首先说明timm 目前没有强制的 lint / auto-format 工具链Black 等尚未全面引入但持开放态度在过渡期内贡献代码的风格基线是Google Python Style Guide并在此基础上有几处明确的具体约定。1.1 两个核心差异120 字符行宽与悬挂缩进行宽 120 字符。超过 120 字符在特定情况下可以接受例如维护者倾向于不把 URL 拆行书写。悬挂缩进hanging indent是首选。文档明确要求避免把参数与右括号/右花括号对齐的写法。以下对照示例直接来自 CONTRIBUTING.md不推荐参数与左括号对齐# Aligned with opening delimiter. foo long_function_name(var_one, var_two, var_three, var_four) meal (spam, beans) # Aligned with opening delimiter in a dictionary. foo { long_dictionary_key: value1 value2, ... }推荐4 空格悬挂缩进首行不放内容右括号独立成行# 4-space hanging indent; nothing on first line, # closing parenthesis on a new line. foo long_function_name( var_one, var_two, var_three, var_four ) meal ( spam, beans, ) # 4-space hanging indent in a dictionary. foo { long_dictionary_key: long_dictionary_value, ... }1.2 与 Black / Ruff 的一处分歧函数参数缩进文档指出 timm 的风格与 Black / Ruff大体兼容但由于维护者自 Black 出现之前就一直遵循 PEP 8因此在函数定义处参数列表的缩进上坚持 PEP 8 的做法——参数列表需要比def再多一级缩进。Black 风格的写法文档中标注为需要调整的一方def very_important_function( template: str, *variables, file: os.PathLike, engine: str, header: bool True, debug: bool False, ): with open(file, w) as f: ...按 timm 期望的 PEP 8 缩进参数应再缩进一级def very_important_function( template: str, *variables, file: os.PathLike, engine: str, header: bool True, debug: bool False, ): with open(file, w) as f: ...文档特别强调请不要对既有文件整体运行 Black把全文件的参数缩进一次性转换掉原话还带了一句幽默的I do like sadface though。1.3 文件内风格不一致时跟随该文件由于 timm 各部分代码来源众多并非所有文件都已更新到当前期望的风格因此文档给出的规则是当某个源文件内部风格不一致时请遵循该文件自身的既有风格。此外还有两条 PR 卫生规范避免格式化与你 PR 无关的代码纯格式化 / 风格修复的 PR 会被接受但必须与功能性改动隔离且最好在动手前先与维护者确认。值得注意的是pyproject.toml 末尾已出现[tool.wruff.format]配置段quote-style preserve、preview true从源码结构看项目正在逐步向 Ruff 系格式化工具靠拢这印证了文档中auto-format 尚未就位但开放考虑的说法。二、文档字符串与类型标注DocumentationCONTRIBUTING.md 的 Documentation 一节提出三条要求docstring 风格同样基于 Google Python Style Guide类型标注的目标让所有主要函数和__init__方法逐步具备 PEP 484 类型标注标注是唯一事实来源一旦函数使用了类型标注就不要在 docstring 中重复标注内容类型标注作为 typing 的唯一来源one source of truth。文档还坦承相对 timm 的功能面当前文档存在大量空白鼓励贡献者document away——为缺失的模块、参数和用法补写文档本身就是有价值的贡献方向。三、开发环境搭建InstallationCONTRIBUTING.md 给出的安装步骤非常简洁用Python 3.10创建虚拟环境按系统选择安装torch与torchvision参考 PyTorch 官方站点对应系统的安装说明然后安装其余依赖并以可编辑模式安装 timmpython -m pip install -r requirements.txt python -m pip install -r requirements-dev.txt # for testing python -m pip install -e .结合仓库中的实际依赖文件可以更精确地理解每一步装了什么requirements.txt运行时依赖包含torch1.7、torchvision、pyyaml、huggingface_hub0.17.0、safetensors0.2、numpy。这也与 pyproject.toml 中[project] dependencies的声明一致requirements-dev.txt测试依赖包含pytest、pytest-timeout、pytest-xdist、pytest-forked、expecttest。其中pytest-xdist正是下文并行测试-n选项的实现pytest-forked则支撑 CI 中使用的--forked模式pyproject.toml 中requires-python 3.8即 Python 3.8 及以上均可安装而 timm/version.py 当前版本号为1.0.29.dev0。贡献指南推荐 Python 3.10 与 CI 的基线环境保持一致见下文测试矩阵。可编辑安装-e .的意义在于本地修改timm/下的源码后无需重新打包import timm即生效适合边改边测。四、单元测试运行、筛选与并行Unit tests4.1 基本运行方式CONTRIBUTING.md 给出全量测试命令pytest tests/文档明确指出全量测试套件在本地耗时很长a few hours因此建议针对自己改动相关的测试进行子集运行。4.2 用-k按名称筛选、-n并行执行pytest -k substring-to-match -n 4 tests/-k选项按测试函数/类的名称做子串匹配或表达式匹配例如pytest -k resnet tests/test_models.py只跑名称中包含 resnet 的测试-n选项由 requirements-dev.txt 中的pytest-xdist插件提供上例表示以 4 个进程并行执行。从源码结构看[pyproject.toml](https://link.gitcode.com/i/07618576908ed3655651636fea40f3cc)的[tool.pytest.ini_options]已声明testpaths [tests]因此实际直接运行pytest也会定位到tests/目录文档示例中显式写出tests/路径只是更直白的写法。4.3 测试标记markers体系与 CI 矩阵pyproject.toml 中注册了 6 个 pytest 标记这是理解 timm 测试组织的钥匙标记用途base使用基本配置跑的模型测试cfg校验模型配置config的测试torchscriptTorchScript 路径的模型测试features特征提取feature extraction相关测试fxforwardTorch FX 前向测试fxbackwardTorch FX 反向测试.github/workflows/tests.yml 展示了这些标记如何被 CI 消费测试任务按testmarker维度拆分成多个并行 runner每个 runner 执行类似pytest -vv --forked --durations0 -m marker tests的命令其中-m按标记选择测试--forked让每个测试在独立子进程中运行--durations0输出耗时排序。该矩阵还覆盖 Python 3.10 / 3.13 与 torch 1.13.0 / 2.9.1 的组合Linux 上通过LD_PRELOAD加载 tcmalloc 控制内存行为。tests/test_models.py 的文件头注释进一步贡献了一条对贡献者很实用的规则新增测试必须使用上述已有标记之一或注册新标记如果使用新标记必须同步调整 tests.yml 中的测试矩阵否则 CI 会直接跳过这些测试。文件头部还给出了按 CI 环境区分的大模型排除清单EXCLUDE_FILTERS等实现细节说明模型级测试对运行环境的资源敏感贡献新模型时最好参照该文件的过滤与超时约定来组织测试。五、构建文档Building documentationCONTRIBUTING.md 将文档构建指向仓库内的hfdocs目录该目录下的 hfdocs/README.md 给出了本地构建 Hugging Face 文档的具体步骤先安装 doc-builder 工具及watchdog、black依赖然后在本地预览文档doc-builder preview timm hfdocs/source文档的源文件位于 hfdocs/source 下models/子目录按模型逐一组织如 resnet.mdx、efficientnet.mdxreference/子目录则覆盖 data.mdx、models.mdx、optimizers.mdx、schedulers.mdx 等 API 参考页。从源码结构看贡献文档主要是按 hfdocs/source/_toctree.yml 的目录结构补充/修正这些.mdx页面。六、提问渠道QuestionsCONTRIBUTING.md 建议关于贡献方式、贡献位置的任何疑问先到项目的 Discussions 中提有专门的Contributing话题分类而不是直接开 PR 试错。七、要点速查风格基线Google Python Style Guide 120 字符行宽 4 空格悬挂缩进右括号独立成行与 Black 的唯一明确分歧是函数定义参数缩进坚持 PEP 8 多一级缩进不要对存量文件整体跑 Black文件内风格不一致时跟随该文件既有风格纯格式化 PR 需与功能改动隔离并事先沟通类型标注是 typing 唯一事实来源docstring 不重复标注环境Python 3.10 虚拟环境 torch/torchvision pip install -r requirements.txt -r requirements-dev.txtpip install -e .测试pytest tests/全量数小时-k筛选、-n并行按 marker 组织测试并保持与 tests.yml 矩阵一致文档按 hfdocs/README.md 用 doc-builder 本地预览。【免费下载链接】pytorch-image-modelsThe largest collection of PyTorch image encoders / backbones. Including train, eval, inference, export scripts, and pretrained weights -- ResNet, ResNeXT, EfficientNet, NFNet, Vision Transformer (ViT), MobileNetV4, MobileNet-V3 V2, RegNet, DPN, CSPNet, Swin Transformer, MaxViT, CoAtNet, ConvNeXt, and more项目地址: https://gitcode.com/GitHub_Trending/py/pytorch-image-models创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考