嵌入式语言运行时编程语言解释器编译器物联网系统编程【免费下载链接】micropythonMicroPython - a lean and efficient Python implementation for microcontrollers and constrained systems项目地址https://gitcode.com/gh_mirrors/mi/micropython点击查看免费下载本指南完整解析 MicroPython 仓库的 CODECONVENTIONS.md覆盖 Git 提交信息规范、C/Python 代码风格、tools/codeformat.py格式化流程、uncrustify/ruff 工具链、codespell 拼写检查以及 pre-commit 钩子的安装与使用。读完本文你将掌握向 MicroPython 提交高质量 PR 的全部前置动作写出一行符合 72 字符约束并带 Signed-off-by 的提交信息用正确的工具版本完成 C 与 Python 代码的自动格式化并在本地一键复现 CI 的全部检查项。一、Git Commit 约定前缀、主语与 Sign-offMicroPython 采用单一代码库monorepo结构py/、extmod/、ports/、docs/、drivers/、shared/、tools/、tests/等目录并存因此提交信息的第一行必须能让人一眼看出改动影响范围。1.1 路径前缀指明改动所属区域每个提交信息必须以目录路径或完整文件路径开头改动只涉及单个文件时优先使用文件路径作为前缀改动涉及某子目录下的少量文件时可以使用子目录作为前缀路径较长时可以省略中间层级但省略后仍须保留足够的上下文提示允许去掉文件扩展名。文档中给出的四个正面示例这些也是仓库中真实存在的提交风格py/objstr: Add splitlines() method. py: Rename FOO to BAR. docs/machine: Fix typo in reset() description. ports: Switch to use lib/foo instead of duplicated code.对应到当前仓库的实际提交例如最新一次提交的主旨行即为rp2: Keep machine.RTC ticking while in lightsleep().前缀rp2对应 ports/rp2 端口目录主旨描述了具体行为变更句尾带句号完全符合规范。1.2 主旨行要求在路径前缀之后主旨行应清晰、切中要点地描述本次改动必须是语法完整的句子并以英文句号.结尾整行含前缀不得超过 72 个字符。这些约束并非仅靠自觉仓库提供了机器校验脚本 tools/verifygitlog.py其中的正则^[^!]: [A-Z]. \.$会检查主旨行必须形如path: Subject.并且前缀不能以.或/开头、不能以/结尾前缀不能以ports/开头而应直接使用端口名如esp32、stm32前缀不能以.c、.h、.cpp、.js、.rst、.md等扩展名结尾主旨行超过 72 字符会报错Subject line must be 72 or fewer characters主旨行之后若还有内容第二行必须为空行用于分隔主旨与正文。1.3 正文与行宽主旨行之后空一行再按需补充详细说明正文每行不超过 75 个字符URL 等无法断行的长条目除外。改动超过 5 行时通常就需要撰写详细正文。正文中以Co-authored-by:、Signed-off-by:开头的行以及包含://的 URL 行不受 75 字符限制见 tools/verifygitlog.py。1.4 Signed-off-by法律意义上的签署每次提交都必须签署在提交信息末尾添加Signed-off-by:行最简单的方式是使用git commit -s。签署即代表你确认以下事项代码是你本人所写或取自许可兼容的项目后者须在提交信息乃至源码中注明来源并致谢原作者你有权将这些改动发布到开源项目例如第三方付费工作期间的成果可能需要该第三方明确批准你或你的雇主同意以 MicroPython 的 MIT 许可证发布这些改动。你保留对改动的版权小改动通过提交信息体现版权若对某源码模块做了显著改动欢迎在文件头添加你的名字你的贡献包括提交信息将公开且长期可访问任何人可按项目许可证条款获取与再分发你的签名即Signed-off-by行其中必须包含你的真实全名和有效、可联系的邮箱地址。verifygitlog.py会强制校验最后一行是否以Signed-off-by:开头且包含同时会拒绝包含noreply字样的作者/提交者邮箱。1.5 实践建议与 WIP 机制想获取优秀提交范例直接浏览仓库的git log提交信息被 pre-commit 拒绝时可用git commit -n即--no-verify单次跳过检查需要临时绕过提交信息格式检查时可将主旨行以WIP开头verifygitlog.py的--ignore-rebase模式会跳过squash!、fixup!、amend!、WIP前缀的提交。二、代码自动格式化总览MicroPython 对 C 与 Python 代码的格式实行统一管控C 代码使用 tools/codeformat.py 驱动 uncrustify 配置Python 代码使用 ruff 与ruff format进行 lint 与格式化。改动完成、提交之前运行tools/codeformat.py重新格式化 C 代码对 Python 代码运行ruff format。不带参数执行时工具会格式化全部源码耗时较长也可以把改动的文件作为参数传入仅格式化这些文件。从 tools/codeformat.py 的源码可以看到默认扫描范围drivers/**/*.[ch]、examples/**/*.[ch]、extmod/**/*.[ch]、mpy-cross/*.[ch]、ports/**/*.[ch]、py/**/*.[ch]、shared/**/*.[ch]以及lib/mbedtls_errors/tester.c同时有一组排除项如shared/readline/*.[ch]、drivers/cc3100、ports/cc3200、ports/nrf部分目录、ports/stm32/usbdev、ports/stm32/usbhost及构建产物ports/*/build*这些多是尚未完全格式化或第三方代码。工具支持的关键命令行参数参数作用-c仅格式化 C 代码-p仅格式化 Python 代码-v输出详细信息-f对命令行传入的文件按默认清单过滤只检查清单内文件files指定要格式化的文件 glob缺省为全部默认路径C 代码处理分两步先用uncrustify -c tools/uncrustify.cfg -lC --no-backup批量格式化每 200 个文件一批避免命令行过长再执行fixup_c()做预处理指令缩进修正——它会把#if/#ifdef/#else/#endif的缩进与其后代码行对齐tools/codeformat.py。Python 侧则在仓库根目录执行ruff format配置见 pyproject.toml。三、uncrustify 版本要求与安装MicroPython 只支持 uncrustify v0.71 或 v0.72。不同版本的 uncrustify 输出略有差异且配置文件格式往往互不兼容v0.73 及更新版本将无法工作。如果你的操作系统包管理器提供兼容的预编译版本可以直接安装否则推荐通过 PyPI 安装官方封装的兼容版本。3.1 使用 pip 安装推荐配合虚拟环境pip install micropython-uncrustify该包安装的是一个以 Python 可执行程序形式交付的原生编译 uncrustify 二进制因此可以装进 virtualenv随 venv 管理版本。3.2 使用 pipx 安装若不使用虚拟环境可通过 pipx 安装pipx install micropython-uncrustify在 pre-commit 配置中本地钩子codeformat正是依赖micropython-uncrustify1.0.0.post1来保证所用 uncrustify 版本一致见 .pre-commit-config.yaml。四、代码拼写检查codespellMicroPython 使用 codespell 做代码拼写检查并作为 GitHub Action 在 CI 中运行。codespell 通过 pyproject.toml 配置以避免误报ignore-words-list列出了需要忽略的单词如ans、deques、ser、technic、ure等常见于嵌入式领域的标识符ignore-regex忽略全大写的三字母缩写skip排除了./lib、./tests、第三方驱动与构建产物等目录。手动安装并运行$ pip install codespell tomli $ codespelltomli用于让 codespell 读取 TOML 格式的配置。仓库建议在提交 PR 前先跑一遍 codespell为简化流程它已被配置为 pre-commit 钩子执行pre-commit install后即会自动生效。五、pre-commit 自动钩子本地复现 CI 检查仓库提供 .pre-commit-config.yaml将代码格式与提交信息约定检查接入 pre-commit 工具。pre-commit 会自动安装正确版本的依赖codespell、uncrustify、ruff 等。5.1 安装 pre-commit 本体可从系统包管理器或 pip 安装通过 pip 安装时建议使用虚拟环境$ apt install pre-commit # Ubuntu, Debian $ pacman -Sy python-precommit # Arch Linux $ brew install pre-commit # Brew $ pip install pre-commit # PyPI5.2 注册钩子在 MicroPython 仓库根目录执行$ pre-commit install --hook-type pre-commit --hook-type commit-msg此后git commit时会自动对代码与提交信息执行格式检查。具体而言配置中注册了四个钩子本地钩子codeformat对改动的 C 文件运行tools/codeformat.py -v -c -f本地钩子verifygitlog在commit-msg阶段运行tools/verifygitlog.py --check-file --ignore-rebase校验提交信息格式ruff与ruff-formatrev v0.11.6对 Python 文件做 lint 与格式化codespellrev v2.4.1对改动文件做拼写检查。CI 会对提交到 MicroPython 的每个 Pull Request 运行同样的格式化检查pre-commit 能让你更快发现失败且多数情况下会在本地工作副本中自动修正格式。5.3 卸载与使用技巧卸载钩子$ pre-commit uninstall --hook-type pre-commit --hook-type commit-msg实用技巧单次提交跳过 pre-commit 检查git commit -n--no-verify临时忽略提交信息格式检查主旨行以WIP开头。5.4 手动运行 pre-commit钩子安装后也可按需手动运行$ pre-commit run --all-files # 修正代码库全部文件 $ pre-commit run --file ./path/to/my/file # 只处理单个文件 $ pre-commit run --file ./path/to/my/folder/* # 只处理某个目录六、Python 代码约定Python 代码遵循 PEP 8并使用ruff format自动格式化行宽为 99 字符见 pyproject.toml 的line-length 99。命名约定模块名简短且全小写如pyb、stm类名CamelCase缩写保持全大写如I2C而不是I2c函数与方法名全小写必要时用单个下划线分隔单词提升可读性如mem_read常量全大写单词间用单个下划线分隔如GPIO_IDR。ruff 配置中还包含若干针对 MicroPython 的定制builtins声明了ptr、ptr8、uint、micropython、const、execfile等 MicroPython 特有内建名mccabe.max-complexity 40放宽圈复杂度阈值tests/**/*.py整体豁免 lint部分测试文件因故意违反语法或依赖 REPL 行为也被ruff.format排除见 pyproject.toml。七、C 代码约定C 代码由 uncrustify 依据 tools/uncrustify.cfg 自动格式化并辅以 tools/codeformat.py 的少量修正。编写新 C 代码时请遵循既有风格并用tools/codeformat.py校验改动。需要说明的是MicroPython 代码库已有十余年历史并非每个源文件都完全符合这些约定。对既有代码做小幅修改时跟随该文件现有风格通常即可新代码或大规模改动则应遵循以下约定。7.1 空白White space制表符展开为 4 个空格行尾不得留尾随空白控制块if、for、while关键字与左括号之间留 1 个空格逗号后留 1 个空格运算符两侧各留 1 个空格。7.2 花括号Braces所有块都必须使用花括号即使只有一行代码左花括号放在所属行的行尾Allman 风格不被接受不另起新行else与前一个右花括号同行。7.3 头文件头文件必须用#if预处理指令防止重复包含include guard命名方式参考现有头文件。7.4 命名Names所有名称使用underscore_case不使用 camelCase枚举与宏使用CAPS_WITH_UNDERSCORE定义类型时使用underscore_case并在末尾加_t。公共名称声明在头文件中MicroPython 特有名称尤其是声明在py/与extmod/目录中的一般以mp_或MP_开头。例如 py/obj.h 中声明的一众对象构造接口mp_obj_new_int、mp_obj_new_int_from_uint、mp_obj_new_float、mp_obj_new_bool等头文件中声明的函数与变量通常共享一个较长的公共前缀且前缀一般与文件名一致。例如定义在 py/obj.c 中的条目声明于 py/obj.h前缀为mp_obj_。也存在例外比如一个头文件为方便起见集中声明了多个源文件中的实现。私有名称仅限单个 .c 文件对暴露给 Python 的静态函数与变量即以MP_DEFINE_CONST_FUN_...包装并挂载到模块上的静态 C 函数使用文件级公共前缀命名即按“非静态”的规则命名其他仅在本 .c 文件内使用的静态定义不需要任何前缀明确禁止s_或_前缀一般也避免添加文件级公共前缀。7.5 整数类型MicroPython 运行在 16 位、32 位与 64 位机器上必须使用大小与符号正确的整数类型大多数场景使用mp_int_t有符号与mp_uint_t无符号二者保证为机器字宽足以容纳 MicroPython small-int 对象的值统计字节数/对象大小时使用size_t可以使用int/uint但需牢记它们可能是 16 位宽不确定时使用mp_int_t/mp_uint_t。7.6 注释保持简洁只为不明显的内容写注释使用//前缀不使用/* ... */不写多余废话。7.7 内存分配使用m_new、m_renew、m_del及其系列宏分配与释放堆内存这些宏定义在 py/misc.h。例如m_new(type, num)展开为m_malloc(sizeof(type) * (num))另有m_new0清零、m_new_obj、m_new_obj_var含可变长尾部字段的对象等变体之所以统一走这些宏是因为它们在所有端口上路由到 MicroPython 的 GC 分配器保证内存管理与平台无关。7.8 风格示例花括号、空格、命名与注释#define TO_ADD (123) // This function will always recurse indefinitely and is only used to show // coding style int foo_function(int x, int some_value) { if (x some_value) { foo(some_value, x); } else { foo(x TO_ADD, some_value - 1); } for (int my_counter 0; my_counter x; my_counter) { } }类型声明typedef struct _my_struct_t { int member; void *data; } my_struct_t;注意结构体标签_my_struct_t与 typedef 名my_struct_t的配套写法这也是整个代码库统一的结构体命名模式。八、文档编写约定MicroPython 文档总体上跟随 CPython 的文档流程与约定使用 reStructuredTextreST语法书写文档源文件位于 docs 目录。8.1 参数引用与通用描述用*标记引用函数参数例如 docs/library/select.rst 中真实的写法.. method:: poll.unregister(obj) Unregister *obj* from polling.当多个元素需要共用一段描述时.. function:: foo(x) bar(y) Description common to foo() and bar().8.2 交叉引用语法:func:foo - function foo in current module :func:module1.foo - function foo in module module1 (similarly for other referent types) :class:Foo - class Foo :meth:Class.method1 - method1 in Class :meth:~Class.method1 - method1 in Class, but rendered just as method1(), not Class.method1() :meth:title method1 - reference method1, but render as title (use only if really needed) :mod:module1 - module module1symbol是通用 xref 语法可在无歧义时替代上述任意形式若存在歧义文档生成时会给出警告需要用上面的精确语法修正。8.3 锚点引用与外部链接交叉引用任意位置若 xref 目标后紧跟章节标题可直接写:ref:xref_target.. _xref_target: Normal non-indented text. This is :ref:reference xref_target.链接到外部 URLlink text http://foo.com/..._8.4 内建单例对象引用None、True、False等内建单例对象时使用双反引号字面量None, True, False九、与 CI 的联动一次提交如何通过全部检查综合全仓库的配置一个合规的 MicroPython 提交需要同时满足以下链路全部可在本地通过 pre-commit 复现代码格式C 文件经 uncrustify v0.71/v0.72 tools/codeformat.py 格式化Python 文件经ruff format99 字符行宽格式化静态检查Python 代码经 ruff lint豁免项见 pyproject.tomlC 代码遵循 tools/uncrustify.cfg 的风格约定拼写检查codespell 按 pyproject.toml 的忽略清单扫描提交信息tools/verifygitlog.py 校验前缀、句号结尾、72 字符主旨行、75 字符正文行、第二行空行、Signed-off-by签名与有效邮箱Git 钩子pre-commit install --hook-type pre-commit --hook-type commit-msg将上述检查注册到本地与 CI 保持同版本依赖。由于git commit会触发commit-msg阶段的verifygitlog钩子最常见的失败场景是提交信息不合规此时按钩子输出的错误逐条修正例如补充句号、缩短主旨行、加上Signed-off-by行即可。提交前养成“先tools/codeformat.py 改动文件格式化、再pre-commit run --file 改动文件复查”的习惯就能在本地提前消除绝大多数 CI 报错。十、进一步阅读CONTRIBUTING.md贡献入口指向贡献者指南与本规范.pre-commit-config.yaml四个钩子codeformat、verifygitlog、ruff、codespell的版本与参数定义tools/codeformat.pyC/Python 格式化脚本的完整实现与默认扫描/排除路径tools/verifygitlog.py提交信息校验脚本的完整规则实现tools/uncrustify.cfgC 格式化配置pyproject.tomlruff 与 codespell 的集中配置docs 目录reST 文档源码可用于对照第八节中的交叉引用与描述约定。对于新手贡献者最稳妥的路径是先浏览git log观察既有提交风格 → 用git commit -s书写带前缀、句号与 Signed-off-by 的提交信息 → 运行tools/codeformat.py与pre-commit run --all-files完成本地检查 → 再提交 Pull Request。这套流程覆盖了 CI 中除实际编译与测试外的全部格式类检查能显著减少来回 review 的成本。赞分享嵌入式语言运行时编程语言解释器编译器物联网系统编程【免费下载链接】micropythonMicroPython - a lean and efficient Python implementation for microcontrollers and constrained systems项目地址https://gitcode.com/gh_mirrors/mi/micropython点击查看免费下载相关推荐Angular Commit Message 格式规范详解从提交信息结构到 Changelog 自动生成Angular Commit Message 格式规范详解从提交信息结构到 Changelog 自动生成 Angular 官方仓库 angular/angu前端Web框架Element Plus 提交信息规范实战指南Commit Message 格式、模板与自动化校验Element Plus 提交信息规范实战指南Commit Message 格式、模板与自动化校验 导读 本文基于 Element Plus 官方贡献文档《C前端UI组件变更描述变更描述 简要说明变更内容 实现细节 技术实现方案 测试验证 单元测试覆盖率≥80% 已通过压力测试 benchmark 兼容性测试 Windows/Linu后端网络通信上一篇PrivateGPT API客户端开发Python/JavaScript实战教程下一篇打造统一视觉体验Dracula Theme图标与UI组件库开发指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MicroPython 代码规范与提交约定全指南：从 Commit Message 到自动格式化
嵌入式语言运行时编程语言解释器编译器物联网系统编程【免费下载链接】micropythonMicroPython - a lean and efficient Python implementation for microcontrollers and constrained systems项目地址https://gitcode.com/gh_mirrors/mi/micropython点击查看免费下载本指南完整解析 MicroPython 仓库的 CODECONVENTIONS.md覆盖 Git 提交信息规范、C/Python 代码风格、tools/codeformat.py格式化流程、uncrustify/ruff 工具链、codespell 拼写检查以及 pre-commit 钩子的安装与使用。读完本文你将掌握向 MicroPython 提交高质量 PR 的全部前置动作写出一行符合 72 字符约束并带 Signed-off-by 的提交信息用正确的工具版本完成 C 与 Python 代码的自动格式化并在本地一键复现 CI 的全部检查项。一、Git Commit 约定前缀、主语与 Sign-offMicroPython 采用单一代码库monorepo结构py/、extmod/、ports/、docs/、drivers/、shared/、tools/、tests/等目录并存因此提交信息的第一行必须能让人一眼看出改动影响范围。1.1 路径前缀指明改动所属区域每个提交信息必须以目录路径或完整文件路径开头改动只涉及单个文件时优先使用文件路径作为前缀改动涉及某子目录下的少量文件时可以使用子目录作为前缀路径较长时可以省略中间层级但省略后仍须保留足够的上下文提示允许去掉文件扩展名。文档中给出的四个正面示例这些也是仓库中真实存在的提交风格py/objstr: Add splitlines() method. py: Rename FOO to BAR. docs/machine: Fix typo in reset() description. ports: Switch to use lib/foo instead of duplicated code.对应到当前仓库的实际提交例如最新一次提交的主旨行即为rp2: Keep machine.RTC ticking while in lightsleep().前缀rp2对应 ports/rp2 端口目录主旨描述了具体行为变更句尾带句号完全符合规范。1.2 主旨行要求在路径前缀之后主旨行应清晰、切中要点地描述本次改动必须是语法完整的句子并以英文句号.结尾整行含前缀不得超过 72 个字符。这些约束并非仅靠自觉仓库提供了机器校验脚本 tools/verifygitlog.py其中的正则^[^!]: [A-Z]. \.$会检查主旨行必须形如path: Subject.并且前缀不能以.或/开头、不能以/结尾前缀不能以ports/开头而应直接使用端口名如esp32、stm32前缀不能以.c、.h、.cpp、.js、.rst、.md等扩展名结尾主旨行超过 72 字符会报错Subject line must be 72 or fewer characters主旨行之后若还有内容第二行必须为空行用于分隔主旨与正文。1.3 正文与行宽主旨行之后空一行再按需补充详细说明正文每行不超过 75 个字符URL 等无法断行的长条目除外。改动超过 5 行时通常就需要撰写详细正文。正文中以Co-authored-by:、Signed-off-by:开头的行以及包含://的 URL 行不受 75 字符限制见 tools/verifygitlog.py。1.4 Signed-off-by法律意义上的签署每次提交都必须签署在提交信息末尾添加Signed-off-by:行最简单的方式是使用git commit -s。签署即代表你确认以下事项代码是你本人所写或取自许可兼容的项目后者须在提交信息乃至源码中注明来源并致谢原作者你有权将这些改动发布到开源项目例如第三方付费工作期间的成果可能需要该第三方明确批准你或你的雇主同意以 MicroPython 的 MIT 许可证发布这些改动。你保留对改动的版权小改动通过提交信息体现版权若对某源码模块做了显著改动欢迎在文件头添加你的名字你的贡献包括提交信息将公开且长期可访问任何人可按项目许可证条款获取与再分发你的签名即Signed-off-by行其中必须包含你的真实全名和有效、可联系的邮箱地址。verifygitlog.py会强制校验最后一行是否以Signed-off-by:开头且包含同时会拒绝包含noreply字样的作者/提交者邮箱。1.5 实践建议与 WIP 机制想获取优秀提交范例直接浏览仓库的git log提交信息被 pre-commit 拒绝时可用git commit -n即--no-verify单次跳过检查需要临时绕过提交信息格式检查时可将主旨行以WIP开头verifygitlog.py的--ignore-rebase模式会跳过squash!、fixup!、amend!、WIP前缀的提交。二、代码自动格式化总览MicroPython 对 C 与 Python 代码的格式实行统一管控C 代码使用 tools/codeformat.py 驱动 uncrustify 配置Python 代码使用 ruff 与ruff format进行 lint 与格式化。改动完成、提交之前运行tools/codeformat.py重新格式化 C 代码对 Python 代码运行ruff format。不带参数执行时工具会格式化全部源码耗时较长也可以把改动的文件作为参数传入仅格式化这些文件。从 tools/codeformat.py 的源码可以看到默认扫描范围drivers/**/*.[ch]、examples/**/*.[ch]、extmod/**/*.[ch]、mpy-cross/*.[ch]、ports/**/*.[ch]、py/**/*.[ch]、shared/**/*.[ch]以及lib/mbedtls_errors/tester.c同时有一组排除项如shared/readline/*.[ch]、drivers/cc3100、ports/cc3200、ports/nrf部分目录、ports/stm32/usbdev、ports/stm32/usbhost及构建产物ports/*/build*这些多是尚未完全格式化或第三方代码。工具支持的关键命令行参数参数作用-c仅格式化 C 代码-p仅格式化 Python 代码-v输出详细信息-f对命令行传入的文件按默认清单过滤只检查清单内文件files指定要格式化的文件 glob缺省为全部默认路径C 代码处理分两步先用uncrustify -c tools/uncrustify.cfg -lC --no-backup批量格式化每 200 个文件一批避免命令行过长再执行fixup_c()做预处理指令缩进修正——它会把#if/#ifdef/#else/#endif的缩进与其后代码行对齐tools/codeformat.py。Python 侧则在仓库根目录执行ruff format配置见 pyproject.toml。三、uncrustify 版本要求与安装MicroPython 只支持 uncrustify v0.71 或 v0.72。不同版本的 uncrustify 输出略有差异且配置文件格式往往互不兼容v0.73 及更新版本将无法工作。如果你的操作系统包管理器提供兼容的预编译版本可以直接安装否则推荐通过 PyPI 安装官方封装的兼容版本。3.1 使用 pip 安装推荐配合虚拟环境pip install micropython-uncrustify该包安装的是一个以 Python 可执行程序形式交付的原生编译 uncrustify 二进制因此可以装进 virtualenv随 venv 管理版本。3.2 使用 pipx 安装若不使用虚拟环境可通过 pipx 安装pipx install micropython-uncrustify在 pre-commit 配置中本地钩子codeformat正是依赖micropython-uncrustify1.0.0.post1来保证所用 uncrustify 版本一致见 .pre-commit-config.yaml。四、代码拼写检查codespellMicroPython 使用 codespell 做代码拼写检查并作为 GitHub Action 在 CI 中运行。codespell 通过 pyproject.toml 配置以避免误报ignore-words-list列出了需要忽略的单词如ans、deques、ser、technic、ure等常见于嵌入式领域的标识符ignore-regex忽略全大写的三字母缩写skip排除了./lib、./tests、第三方驱动与构建产物等目录。手动安装并运行$ pip install codespell tomli $ codespelltomli用于让 codespell 读取 TOML 格式的配置。仓库建议在提交 PR 前先跑一遍 codespell为简化流程它已被配置为 pre-commit 钩子执行pre-commit install后即会自动生效。五、pre-commit 自动钩子本地复现 CI 检查仓库提供 .pre-commit-config.yaml将代码格式与提交信息约定检查接入 pre-commit 工具。pre-commit 会自动安装正确版本的依赖codespell、uncrustify、ruff 等。5.1 安装 pre-commit 本体可从系统包管理器或 pip 安装通过 pip 安装时建议使用虚拟环境$ apt install pre-commit # Ubuntu, Debian $ pacman -Sy python-precommit # Arch Linux $ brew install pre-commit # Brew $ pip install pre-commit # PyPI5.2 注册钩子在 MicroPython 仓库根目录执行$ pre-commit install --hook-type pre-commit --hook-type commit-msg此后git commit时会自动对代码与提交信息执行格式检查。具体而言配置中注册了四个钩子本地钩子codeformat对改动的 C 文件运行tools/codeformat.py -v -c -f本地钩子verifygitlog在commit-msg阶段运行tools/verifygitlog.py --check-file --ignore-rebase校验提交信息格式ruff与ruff-formatrev v0.11.6对 Python 文件做 lint 与格式化codespellrev v2.4.1对改动文件做拼写检查。CI 会对提交到 MicroPython 的每个 Pull Request 运行同样的格式化检查pre-commit 能让你更快发现失败且多数情况下会在本地工作副本中自动修正格式。5.3 卸载与使用技巧卸载钩子$ pre-commit uninstall --hook-type pre-commit --hook-type commit-msg实用技巧单次提交跳过 pre-commit 检查git commit -n--no-verify临时忽略提交信息格式检查主旨行以WIP开头。5.4 手动运行 pre-commit钩子安装后也可按需手动运行$ pre-commit run --all-files # 修正代码库全部文件 $ pre-commit run --file ./path/to/my/file # 只处理单个文件 $ pre-commit run --file ./path/to/my/folder/* # 只处理某个目录六、Python 代码约定Python 代码遵循 PEP 8并使用ruff format自动格式化行宽为 99 字符见 pyproject.toml 的line-length 99。命名约定模块名简短且全小写如pyb、stm类名CamelCase缩写保持全大写如I2C而不是I2c函数与方法名全小写必要时用单个下划线分隔单词提升可读性如mem_read常量全大写单词间用单个下划线分隔如GPIO_IDR。ruff 配置中还包含若干针对 MicroPython 的定制builtins声明了ptr、ptr8、uint、micropython、const、execfile等 MicroPython 特有内建名mccabe.max-complexity 40放宽圈复杂度阈值tests/**/*.py整体豁免 lint部分测试文件因故意违反语法或依赖 REPL 行为也被ruff.format排除见 pyproject.toml。七、C 代码约定C 代码由 uncrustify 依据 tools/uncrustify.cfg 自动格式化并辅以 tools/codeformat.py 的少量修正。编写新 C 代码时请遵循既有风格并用tools/codeformat.py校验改动。需要说明的是MicroPython 代码库已有十余年历史并非每个源文件都完全符合这些约定。对既有代码做小幅修改时跟随该文件现有风格通常即可新代码或大规模改动则应遵循以下约定。7.1 空白White space制表符展开为 4 个空格行尾不得留尾随空白控制块if、for、while关键字与左括号之间留 1 个空格逗号后留 1 个空格运算符两侧各留 1 个空格。7.2 花括号Braces所有块都必须使用花括号即使只有一行代码左花括号放在所属行的行尾Allman 风格不被接受不另起新行else与前一个右花括号同行。7.3 头文件头文件必须用#if预处理指令防止重复包含include guard命名方式参考现有头文件。7.4 命名Names所有名称使用underscore_case不使用 camelCase枚举与宏使用CAPS_WITH_UNDERSCORE定义类型时使用underscore_case并在末尾加_t。公共名称声明在头文件中MicroPython 特有名称尤其是声明在py/与extmod/目录中的一般以mp_或MP_开头。例如 py/obj.h 中声明的一众对象构造接口mp_obj_new_int、mp_obj_new_int_from_uint、mp_obj_new_float、mp_obj_new_bool等头文件中声明的函数与变量通常共享一个较长的公共前缀且前缀一般与文件名一致。例如定义在 py/obj.c 中的条目声明于 py/obj.h前缀为mp_obj_。也存在例外比如一个头文件为方便起见集中声明了多个源文件中的实现。私有名称仅限单个 .c 文件对暴露给 Python 的静态函数与变量即以MP_DEFINE_CONST_FUN_...包装并挂载到模块上的静态 C 函数使用文件级公共前缀命名即按“非静态”的规则命名其他仅在本 .c 文件内使用的静态定义不需要任何前缀明确禁止s_或_前缀一般也避免添加文件级公共前缀。7.5 整数类型MicroPython 运行在 16 位、32 位与 64 位机器上必须使用大小与符号正确的整数类型大多数场景使用mp_int_t有符号与mp_uint_t无符号二者保证为机器字宽足以容纳 MicroPython small-int 对象的值统计字节数/对象大小时使用size_t可以使用int/uint但需牢记它们可能是 16 位宽不确定时使用mp_int_t/mp_uint_t。7.6 注释保持简洁只为不明显的内容写注释使用//前缀不使用/* ... */不写多余废话。7.7 内存分配使用m_new、m_renew、m_del及其系列宏分配与释放堆内存这些宏定义在 py/misc.h。例如m_new(type, num)展开为m_malloc(sizeof(type) * (num))另有m_new0清零、m_new_obj、m_new_obj_var含可变长尾部字段的对象等变体之所以统一走这些宏是因为它们在所有端口上路由到 MicroPython 的 GC 分配器保证内存管理与平台无关。7.8 风格示例花括号、空格、命名与注释#define TO_ADD (123) // This function will always recurse indefinitely and is only used to show // coding style int foo_function(int x, int some_value) { if (x some_value) { foo(some_value, x); } else { foo(x TO_ADD, some_value - 1); } for (int my_counter 0; my_counter x; my_counter) { } }类型声明typedef struct _my_struct_t { int member; void *data; } my_struct_t;注意结构体标签_my_struct_t与 typedef 名my_struct_t的配套写法这也是整个代码库统一的结构体命名模式。八、文档编写约定MicroPython 文档总体上跟随 CPython 的文档流程与约定使用 reStructuredTextreST语法书写文档源文件位于 docs 目录。8.1 参数引用与通用描述用*标记引用函数参数例如 docs/library/select.rst 中真实的写法.. method:: poll.unregister(obj) Unregister *obj* from polling.当多个元素需要共用一段描述时.. function:: foo(x) bar(y) Description common to foo() and bar().8.2 交叉引用语法:func:foo - function foo in current module :func:module1.foo - function foo in module module1 (similarly for other referent types) :class:Foo - class Foo :meth:Class.method1 - method1 in Class :meth:~Class.method1 - method1 in Class, but rendered just as method1(), not Class.method1() :meth:title method1 - reference method1, but render as title (use only if really needed) :mod:module1 - module module1symbol是通用 xref 语法可在无歧义时替代上述任意形式若存在歧义文档生成时会给出警告需要用上面的精确语法修正。8.3 锚点引用与外部链接交叉引用任意位置若 xref 目标后紧跟章节标题可直接写:ref:xref_target.. _xref_target: Normal non-indented text. This is :ref:reference xref_target.链接到外部 URLlink text http://foo.com/..._8.4 内建单例对象引用None、True、False等内建单例对象时使用双反引号字面量None, True, False九、与 CI 的联动一次提交如何通过全部检查综合全仓库的配置一个合规的 MicroPython 提交需要同时满足以下链路全部可在本地通过 pre-commit 复现代码格式C 文件经 uncrustify v0.71/v0.72 tools/codeformat.py 格式化Python 文件经ruff format99 字符行宽格式化静态检查Python 代码经 ruff lint豁免项见 pyproject.tomlC 代码遵循 tools/uncrustify.cfg 的风格约定拼写检查codespell 按 pyproject.toml 的忽略清单扫描提交信息tools/verifygitlog.py 校验前缀、句号结尾、72 字符主旨行、75 字符正文行、第二行空行、Signed-off-by签名与有效邮箱Git 钩子pre-commit install --hook-type pre-commit --hook-type commit-msg将上述检查注册到本地与 CI 保持同版本依赖。由于git commit会触发commit-msg阶段的verifygitlog钩子最常见的失败场景是提交信息不合规此时按钩子输出的错误逐条修正例如补充句号、缩短主旨行、加上Signed-off-by行即可。提交前养成“先tools/codeformat.py 改动文件格式化、再pre-commit run --file 改动文件复查”的习惯就能在本地提前消除绝大多数 CI 报错。十、进一步阅读CONTRIBUTING.md贡献入口指向贡献者指南与本规范.pre-commit-config.yaml四个钩子codeformat、verifygitlog、ruff、codespell的版本与参数定义tools/codeformat.pyC/Python 格式化脚本的完整实现与默认扫描/排除路径tools/verifygitlog.py提交信息校验脚本的完整规则实现tools/uncrustify.cfgC 格式化配置pyproject.tomlruff 与 codespell 的集中配置docs 目录reST 文档源码可用于对照第八节中的交叉引用与描述约定。对于新手贡献者最稳妥的路径是先浏览git log观察既有提交风格 → 用git commit -s书写带前缀、句号与 Signed-off-by 的提交信息 → 运行tools/codeformat.py与pre-commit run --all-files完成本地检查 → 再提交 Pull Request。这套流程覆盖了 CI 中除实际编译与测试外的全部格式类检查能显著减少来回 review 的成本。赞分享嵌入式语言运行时编程语言解释器编译器物联网系统编程【免费下载链接】micropythonMicroPython - a lean and efficient Python implementation for microcontrollers and constrained systems项目地址https://gitcode.com/gh_mirrors/mi/micropython点击查看免费下载相关推荐Angular Commit Message 格式规范详解从提交信息结构到 Changelog 自动生成Angular Commit Message 格式规范详解从提交信息结构到 Changelog 自动生成 Angular 官方仓库 angular/angu前端Web框架Element Plus 提交信息规范实战指南Commit Message 格式、模板与自动化校验Element Plus 提交信息规范实战指南Commit Message 格式、模板与自动化校验 导读 本文基于 Element Plus 官方贡献文档《C前端UI组件变更描述变更描述 简要说明变更内容 实现细节 技术实现方案 测试验证 单元测试覆盖率≥80% 已通过压力测试 benchmark 兼容性测试 Windows/Linu后端网络通信上一篇PrivateGPT API客户端开发Python/JavaScript实战教程下一篇打造统一视觉体验Dracula Theme图标与UI组件库开发指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考