尧图网站建设 
Marimo MR003reusable-definition-order让可复用定义按正确顺序序列化跨模块导入不再踩坑【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimomarimo 的 linter 提供了一条 Runtime 级别的规则MR003reusable-definition-order专门检测本可以标记为可复用reusable、却因单元格顺序错误而无法被序列化到文件顶层的函数或类定义。本篇基于 MR003 规则文档 展开结合 规则源码实现 与 顶层提取逻辑 深入讲解为什么 marimo 里顺序无关的单元格在复用为模块时会变成顺序敏感如何用marimo check检出并自动修复这一问题。一、MR003 检测的是什么marimo 在保存 notebook 时会把满足条件的函数/类序列化到文件的顶层top-level使其可以被其他 Python 脚本或 notebook 以from my_notebook import xxx的方式导入——这是 marimo 纯 Python 文件存储 可作为脚本运行 设计的关键能力详见 复用函数指南。但序列化是按 notebook 中单元格的先后顺序进行的与普通 Python 脚本一样一个可复用函数不能引用一个尚未被定义的变量。marimo 的响应式执行模型中单元格顺序通常无关紧要依赖图会自动决定执行顺序然而一旦以模块或脚本形式复用顶层定义就必须满足 Python 的求值顺序约束。MR003 就是针对这一差异设计的规则。在 Lint 规则总览 中它被归类如下类别CodeName说明可修复性⚠️ RuntimeMR003reusable-definition-order可复用定义依赖于 notebook 中更晚声明的可复用定义⚠️ Unsafe Fixable其中 ⚠️ 表示该问题可用marimo check --fix --unsafe-fixes自动修复但修复可能改变文档结构因此被标记为 unsafe不安全修复。为什么这是个问题当一个可复用定义依赖 notebook 中更靠后声明的另一个可复用定义时会产生两个后果该定义无法被序列化为 reusablemarimo 会把它降级为普通单元格定义而不是文件顶层定义跨 notebook 或 Python 模块的 import 可能失败其他脚本from my_notebook import uses_offset之后在脚本上下文中执行会因依赖符号尚未定义而报错。二、两个典型的问题示例MR003 文档给出了两类典型场景场景 1默认参数引用了后定义的函数app.function def uses_offset(x: int offset()) - int: # This will run in marimo, but will cause an error if run as a script! # offset is not defined! return x 1 app.function def offset() - int: return 1在 marimo 编辑器里这个 notebook 运行完全正常——响应式引擎会先执行offset再求值默认参数。但序列化到文件顶层后uses_offset出现在offset之前任何外部脚本导入并触发默认参数求值时offset还未定义直接报NameError。场景 2类方法使用了后定义的装饰器app.cell def _(): # This could be reusable if it was defined after decorate. class Wrapped: decorate def value(self) - int: return 1 app.function def decorate(fn): return fn类体内部的decorate在类定义执行时就会立即求值。由于Wrapped所在单元格排在decorate之前Wrapped本可以成为可复用类却因顺序问题只能降级为普通单元格定义。三、判定机制从源码看 MR003 如何发现违规规则的完整实现位于 ReusableDefinitionOrderRule它继承自 UnsafeFixRule 基类类属性声明为code MR003、severity Severity.RUNTIME、fixable unsafe与文档标注一一对应。3.1 检测阶段依赖顶层提取的状态机check()方法的核心流程是调用_extract_notebook()将 notebook 序列化为NotebookSerialization逐单元格通过compile_cell编译为CellImpl并单独识别出 setup 单元格setup 单元格不参与普通单元格的顺序判定将编译后的单元格交给 TopLevelExtraction 构建序列化图得到每个单元格的TopLevelStatus遍历状态凡是hint以HINT_ORDER_DEPENDENT前缀开头的单元格就输出一条Diagnostic。其中关键的判定常量定义在 toplevel.pyTopLevelInvalidHints Literal[ ... Signature and decorators depend on {} defined out of correct cell order, ... ]即函数签名或装饰器依赖了顺序不正确的变量。真正的判定发生在 TopLevelStatus.update()order_dependent_refs var.unbounded_refs - allowed_refs if order_dependent_refs and order_dependent_refs - unresolved: self.dependencies order_dependent_refs if not order_dependent_refs - (unresolved | potential_refs): self.demote(HINT_ORDER_DEPENDENT.format(self.dependencies)) else: self.demote(HINT_HAS_REFS.format(self.dependencies)) return从源码结构看判定逻辑可以概括为若某个可复用候选定义的无界引用unbounded_refs即出现在签名/装饰器等定义期位置、必须立即可用的引用不在当前允许的符号集setup 定义 已解析的顶层符号 内建中且这些引用恰好指向 notebook 里其他非顶层单元格定义的符号说明它依赖了一个顺序靠后的定义——此时状态被demote降级为CELL不再是 toplevel并打上HINT_ORDER_DEPENDENT提示。这正是 MR003 文档所说 cannot be serialized as reusable 的底层机制。诊断消息由规则拼接为Reusable definition uses_offset depends on reusable definition(s) declared later in the notebook:offset并附带修复建议 Move the referenced reusable definition(s) earlier in the notebook。3.2 诊断输出长什么样实际marimo check的输出格式可以在 测试快照 中直接看到error[reusable-definition-order]: Reusable definition uses_offset depends on reusable definition(s) declared later in the notebook: offset -- tests/_lint/test_files/reusable_definition_order.py:7:1 7 | app.function 8 | def uses_offset(x: int offset()) - int: | ^ 9 | return x 1 hint: Move the referenced reusable definition(s) earlier in the notebook, before uses_offset.注意诊断精确到定义所在的行和列规则内的_get_definition_line_info()会对单元格代码做 AST 解析定位到FunctionDef/AsyncFunctionDef/ClassDef节点再把单元格起始行号与节点行号相加换算为文件内真实位置。四、手动修复把依赖定义挪到前面最直接的修复方式也是 MR003 文档给出的 Solution把被依赖的可复用定义移动到 notebook 中更靠前的位置使其先于依赖它的定义出现。以场景 1 为例修复后app.function def offset() - int: return 1 app.function def uses_offset(x: int offset()) - int: return x 1现在offset先于uses_offset出现在文件中序列化到顶层后满足 Python 的定义顺序约束两个函数都能被正常导入。一个值得注意的边界setup 单元格中的定义不受此规则影响。在 规则测试 中有一个专门用例test_reusable_definition_order_unsafe_fix_does_not_move_for_setup定义在with app.setup:中的uses_offset引用后定义的offset不会产生 MR003 诊断unsafe fix 也不会移动任何单元格。原因是 setup 单元格本身在所有其他代码之前执行且被整体内联从 TopLevelExtraction 的构造逻辑 看setup 的定义会被直接计入allowed_refs天然不构成顺序依赖。五、自动修复marimo check --fix --unsafe-fixesMR003 支持自动修复但被标记为unsafe必须显式开启--unsafe-fixes才会应用marimo check --fix --unsafe-fixes my_notebook.py5.1 修复做了什么unsafe fix 会把提供方provider单元格重排到 notebook 更早的位置。之所以标记为 unsafe文档给出了明确理由即使修复后的 notebook 仍然有效改变单元格顺序本身就改变了文档结构——用户的 notebook 可能有叙事性的排列先定义工具函数还是先展示数据是作者的编排意图自动重排可能破坏阅读体验。这一点也可以在 CLI 源码 中印证--unsafe-fixes选项的帮助文本就是 Enable fixes that may change code behavior。5.2 排序算法稳定的拓扑排序自动修复的核心在 apply_unsafe_fix() 与 _stable_provider_order()收集所有顶层定义或顺序依赖降级的单元格构建依赖图若定义 A 的dependencies包含定义 B 的名字则连一条 B → A 的边B 必须先于 A使用Kahn 拓扑排序生成一个稳定的线性顺序入度为 0 的节点按索引升序出队保证结果确定且尽量贴近原始顺序将排好序的 provider 单元格整体填入 notebook 的最前面若干位置非 provider 单元格保持相对顺序不变若拓扑排序无法覆盖全部节点存在环返回None放弃修复——循环依赖无法通过重排解决此时仍需要人工介入循环依赖本身另由 MB003 规则处理。测试用例 验证了四类修复行为测试验证点..._reorders_provider_cells单依赖场景修复后offset排在uses_offset之前且复检不再报 MR003..._preserves_provider_order多 provider 场景first、second、uses_both按依赖序排列且保持 provider 间相对顺序..._chained_dependencies链式依赖a → b → c修复后顺序为c、b、a..._does_not_move_for_setupsetup 单元格场景不产生诊断任何单元格都不被移动测试还体现了修复的可验证性每次 fix 后都用lint_notebook(fixed)重新检查断言 MR003 诊断已清零。六、如何检出marimo check 的使用按 Lint 规则总览 的说明linter 通过 CLI 驱动# Check all notebooks in current directory marimo check . # Check specific files marimo check notebook1.py notebook2.py # Auto-fix fixable issues marimo check --fix .针对 MR003 的完整流程是# 1. 检出顺序违规 marimo check my_notebook.py # 2. 查看输出中的 error[reusable-definition-order] 诊断 # 确认是可接受的文档重排后再执行不安全修复 marimo check --fix --unsafe-fixes my_notebook.py # 3. 复验应不再出现 MR003 marimo check my_notebook.pyCLI 的check命令还支持--select/--ignore按规则码过滤如--select MR003、--strict让 warning 也返回非零退出码、--format json输出机器可读结果便于接入 CI详见 CLI 参考。七、与可复用定义整体机制的关系理解 MR003 需要把它放回 marimo 顶层序列化机制的完整图景中参考 Reusing functions 文档中的判据单元格只定义单个函数或类对应源码中HINT_NOT_SINGLE函数/类只能引用 setup 单元格中定义的符号或其他顶层符号对应allowed_refs与HINT_HAS_REFS。MR003 是第 2 条的一个特例分支引用的符号本身也是可复用定义只是顺序不对HINT_ORDER_DEPENDENT如果引用的符号来自普通单元格且无法提升为顶层则触发的是另一类提示HINT_HAS_REFSmove these variables to the setup cell不在 MR003 范围内。其他可复用性约束循环依赖、_前缀私有定义不可复用、命名冲突等的完整讨论见 理解 marimo 错误 与 setup 单元格说明。八、小结MR003 的本质marimo 单元格顺序无关的响应式执行与 Python 模块定义即求值的顺序语义之间的落差规则在序列化层面提前暴露这一落差避免编辑器里跑得好、导入后 NameError。检测依据基于 TopLevelExtraction 对每个单元格状态的判定HINT_ORDER_DEPENDENT是 MR003 的诊断来源。修复手段手动把被依赖定义前移推荐、可控或marimo check --fix --unsafe-fixes触发稳定的拓扑重排存在环时自动放弃修复。适用前提规则作用于可被识别为 marimo notebook 的.py文件setup 单元格内的定义豁免顺序判定修复会重排单元格位置执行前请确认文档重排可接受。【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Marimo MR003（reusable-definition-order）：让可复用定义按正确顺序序列化，跨模块导入不再踩坑
Marimo MR003reusable-definition-order让可复用定义按正确顺序序列化跨模块导入不再踩坑【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimomarimo 的 linter 提供了一条 Runtime 级别的规则MR003reusable-definition-order专门检测本可以标记为可复用reusable、却因单元格顺序错误而无法被序列化到文件顶层的函数或类定义。本篇基于 MR003 规则文档 展开结合 规则源码实现 与 顶层提取逻辑 深入讲解为什么 marimo 里顺序无关的单元格在复用为模块时会变成顺序敏感如何用marimo check检出并自动修复这一问题。一、MR003 检测的是什么marimo 在保存 notebook 时会把满足条件的函数/类序列化到文件的顶层top-level使其可以被其他 Python 脚本或 notebook 以from my_notebook import xxx的方式导入——这是 marimo 纯 Python 文件存储 可作为脚本运行 设计的关键能力详见 复用函数指南。但序列化是按 notebook 中单元格的先后顺序进行的与普通 Python 脚本一样一个可复用函数不能引用一个尚未被定义的变量。marimo 的响应式执行模型中单元格顺序通常无关紧要依赖图会自动决定执行顺序然而一旦以模块或脚本形式复用顶层定义就必须满足 Python 的求值顺序约束。MR003 就是针对这一差异设计的规则。在 Lint 规则总览 中它被归类如下类别CodeName说明可修复性⚠️ RuntimeMR003reusable-definition-order可复用定义依赖于 notebook 中更晚声明的可复用定义⚠️ Unsafe Fixable其中 ⚠️ 表示该问题可用marimo check --fix --unsafe-fixes自动修复但修复可能改变文档结构因此被标记为 unsafe不安全修复。为什么这是个问题当一个可复用定义依赖 notebook 中更靠后声明的另一个可复用定义时会产生两个后果该定义无法被序列化为 reusablemarimo 会把它降级为普通单元格定义而不是文件顶层定义跨 notebook 或 Python 模块的 import 可能失败其他脚本from my_notebook import uses_offset之后在脚本上下文中执行会因依赖符号尚未定义而报错。二、两个典型的问题示例MR003 文档给出了两类典型场景场景 1默认参数引用了后定义的函数app.function def uses_offset(x: int offset()) - int: # This will run in marimo, but will cause an error if run as a script! # offset is not defined! return x 1 app.function def offset() - int: return 1在 marimo 编辑器里这个 notebook 运行完全正常——响应式引擎会先执行offset再求值默认参数。但序列化到文件顶层后uses_offset出现在offset之前任何外部脚本导入并触发默认参数求值时offset还未定义直接报NameError。场景 2类方法使用了后定义的装饰器app.cell def _(): # This could be reusable if it was defined after decorate. class Wrapped: decorate def value(self) - int: return 1 app.function def decorate(fn): return fn类体内部的decorate在类定义执行时就会立即求值。由于Wrapped所在单元格排在decorate之前Wrapped本可以成为可复用类却因顺序问题只能降级为普通单元格定义。三、判定机制从源码看 MR003 如何发现违规规则的完整实现位于 ReusableDefinitionOrderRule它继承自 UnsafeFixRule 基类类属性声明为code MR003、severity Severity.RUNTIME、fixable unsafe与文档标注一一对应。3.1 检测阶段依赖顶层提取的状态机check()方法的核心流程是调用_extract_notebook()将 notebook 序列化为NotebookSerialization逐单元格通过compile_cell编译为CellImpl并单独识别出 setup 单元格setup 单元格不参与普通单元格的顺序判定将编译后的单元格交给 TopLevelExtraction 构建序列化图得到每个单元格的TopLevelStatus遍历状态凡是hint以HINT_ORDER_DEPENDENT前缀开头的单元格就输出一条Diagnostic。其中关键的判定常量定义在 toplevel.pyTopLevelInvalidHints Literal[ ... Signature and decorators depend on {} defined out of correct cell order, ... ]即函数签名或装饰器依赖了顺序不正确的变量。真正的判定发生在 TopLevelStatus.update()order_dependent_refs var.unbounded_refs - allowed_refs if order_dependent_refs and order_dependent_refs - unresolved: self.dependencies order_dependent_refs if not order_dependent_refs - (unresolved | potential_refs): self.demote(HINT_ORDER_DEPENDENT.format(self.dependencies)) else: self.demote(HINT_HAS_REFS.format(self.dependencies)) return从源码结构看判定逻辑可以概括为若某个可复用候选定义的无界引用unbounded_refs即出现在签名/装饰器等定义期位置、必须立即可用的引用不在当前允许的符号集setup 定义 已解析的顶层符号 内建中且这些引用恰好指向 notebook 里其他非顶层单元格定义的符号说明它依赖了一个顺序靠后的定义——此时状态被demote降级为CELL不再是 toplevel并打上HINT_ORDER_DEPENDENT提示。这正是 MR003 文档所说 cannot be serialized as reusable 的底层机制。诊断消息由规则拼接为Reusable definition uses_offset depends on reusable definition(s) declared later in the notebook:offset并附带修复建议 Move the referenced reusable definition(s) earlier in the notebook。3.2 诊断输出长什么样实际marimo check的输出格式可以在 测试快照 中直接看到error[reusable-definition-order]: Reusable definition uses_offset depends on reusable definition(s) declared later in the notebook: offset -- tests/_lint/test_files/reusable_definition_order.py:7:1 7 | app.function 8 | def uses_offset(x: int offset()) - int: | ^ 9 | return x 1 hint: Move the referenced reusable definition(s) earlier in the notebook, before uses_offset.注意诊断精确到定义所在的行和列规则内的_get_definition_line_info()会对单元格代码做 AST 解析定位到FunctionDef/AsyncFunctionDef/ClassDef节点再把单元格起始行号与节点行号相加换算为文件内真实位置。四、手动修复把依赖定义挪到前面最直接的修复方式也是 MR003 文档给出的 Solution把被依赖的可复用定义移动到 notebook 中更靠前的位置使其先于依赖它的定义出现。以场景 1 为例修复后app.function def offset() - int: return 1 app.function def uses_offset(x: int offset()) - int: return x 1现在offset先于uses_offset出现在文件中序列化到顶层后满足 Python 的定义顺序约束两个函数都能被正常导入。一个值得注意的边界setup 单元格中的定义不受此规则影响。在 规则测试 中有一个专门用例test_reusable_definition_order_unsafe_fix_does_not_move_for_setup定义在with app.setup:中的uses_offset引用后定义的offset不会产生 MR003 诊断unsafe fix 也不会移动任何单元格。原因是 setup 单元格本身在所有其他代码之前执行且被整体内联从 TopLevelExtraction 的构造逻辑 看setup 的定义会被直接计入allowed_refs天然不构成顺序依赖。五、自动修复marimo check --fix --unsafe-fixesMR003 支持自动修复但被标记为unsafe必须显式开启--unsafe-fixes才会应用marimo check --fix --unsafe-fixes my_notebook.py5.1 修复做了什么unsafe fix 会把提供方provider单元格重排到 notebook 更早的位置。之所以标记为 unsafe文档给出了明确理由即使修复后的 notebook 仍然有效改变单元格顺序本身就改变了文档结构——用户的 notebook 可能有叙事性的排列先定义工具函数还是先展示数据是作者的编排意图自动重排可能破坏阅读体验。这一点也可以在 CLI 源码 中印证--unsafe-fixes选项的帮助文本就是 Enable fixes that may change code behavior。5.2 排序算法稳定的拓扑排序自动修复的核心在 apply_unsafe_fix() 与 _stable_provider_order()收集所有顶层定义或顺序依赖降级的单元格构建依赖图若定义 A 的dependencies包含定义 B 的名字则连一条 B → A 的边B 必须先于 A使用Kahn 拓扑排序生成一个稳定的线性顺序入度为 0 的节点按索引升序出队保证结果确定且尽量贴近原始顺序将排好序的 provider 单元格整体填入 notebook 的最前面若干位置非 provider 单元格保持相对顺序不变若拓扑排序无法覆盖全部节点存在环返回None放弃修复——循环依赖无法通过重排解决此时仍需要人工介入循环依赖本身另由 MB003 规则处理。测试用例 验证了四类修复行为测试验证点..._reorders_provider_cells单依赖场景修复后offset排在uses_offset之前且复检不再报 MR003..._preserves_provider_order多 provider 场景first、second、uses_both按依赖序排列且保持 provider 间相对顺序..._chained_dependencies链式依赖a → b → c修复后顺序为c、b、a..._does_not_move_for_setupsetup 单元格场景不产生诊断任何单元格都不被移动测试还体现了修复的可验证性每次 fix 后都用lint_notebook(fixed)重新检查断言 MR003 诊断已清零。六、如何检出marimo check 的使用按 Lint 规则总览 的说明linter 通过 CLI 驱动# Check all notebooks in current directory marimo check . # Check specific files marimo check notebook1.py notebook2.py # Auto-fix fixable issues marimo check --fix .针对 MR003 的完整流程是# 1. 检出顺序违规 marimo check my_notebook.py # 2. 查看输出中的 error[reusable-definition-order] 诊断 # 确认是可接受的文档重排后再执行不安全修复 marimo check --fix --unsafe-fixes my_notebook.py # 3. 复验应不再出现 MR003 marimo check my_notebook.pyCLI 的check命令还支持--select/--ignore按规则码过滤如--select MR003、--strict让 warning 也返回非零退出码、--format json输出机器可读结果便于接入 CI详见 CLI 参考。七、与可复用定义整体机制的关系理解 MR003 需要把它放回 marimo 顶层序列化机制的完整图景中参考 Reusing functions 文档中的判据单元格只定义单个函数或类对应源码中HINT_NOT_SINGLE函数/类只能引用 setup 单元格中定义的符号或其他顶层符号对应allowed_refs与HINT_HAS_REFS。MR003 是第 2 条的一个特例分支引用的符号本身也是可复用定义只是顺序不对HINT_ORDER_DEPENDENT如果引用的符号来自普通单元格且无法提升为顶层则触发的是另一类提示HINT_HAS_REFSmove these variables to the setup cell不在 MR003 范围内。其他可复用性约束循环依赖、_前缀私有定义不可复用、命名冲突等的完整讨论见 理解 marimo 错误 与 setup 单元格说明。八、小结MR003 的本质marimo 单元格顺序无关的响应式执行与 Python 模块定义即求值的顺序语义之间的落差规则在序列化层面提前暴露这一落差避免编辑器里跑得好、导入后 NameError。检测依据基于 TopLevelExtraction 对每个单元格状态的判定HINT_ORDER_DEPENDENT是 MR003 的诊断来源。修复手段手动把被依赖定义前移推荐、可控或marimo check --fix --unsafe-fixes触发稳定的拓扑重排存在环时自动放弃修复。适用前提规则作用于可被识别为 marimo notebook 的.py文件setup 单元格内的定义豁免顺序判定修复会重排单元格位置执行前请确认文档重排可接受。【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考