dlt CLI 输出规范深度解析fmt 统一输出、反引号错误消息与导入分组约定【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt本篇指南基于 dlt 仓库的评审规范文档 .continue/agents/cli-output-conventions.md系统讲解 dlt 命令行位于 dlt/_workspace/cli/的三大核心约定用户可见输出一律通过fmt而非 Pythonlogger发出、错误消息中的标识符必须用反引号包裹、_workspace相关导入需成组书写。读完后你不仅能直接对照仓库源码验证每条规范的落地情况还能掌握为 dlt 的 CLI 模块贡献代码时如何通过代码评审检查如“CLI 模块里出现logging导入即违规”并了解echo/error/warning等输出函数在非交互模式、CI 环境下的底层行为。为什么 CLI 模块禁止使用 logger规范文档给出的最重要规则只有一句话dlt/_workspace/cli/下的模块必须使用fmt做用户可见输出不允许使用 Python 的logging模块。文档还引用了评审者的原话please do not use logger inclimodules. we issue warnings viafmt规范文档中的正误对照原文档给出的判定示例如下# BAD — in CLI module import logging logger logging.getLogger(__name__) logger.warning(Could not find scaffold) # GOOD — in CLI module from dlt._workspace.cli import fmt fmt.warning(Could not find scaffold)需要强调的边界是该规则只针对dlt/_workspace/cli/目录。在dlt/common/、dlt/extract/等非 CLI 的库代码中logger是正常且被鼓励的使用方式——dlt 的日志体系JSON 结构化日志等就构建在logging之上这条约定是为了把「库级日志」与「用户交互输出」两种通道严格分开。用仓库源码验证CLI 目录里确实没有 logging对整个 dlt/_workspace/cli/ 目录检索import logging/logging.getLogger结果为空——规范在存量代码上是完全落实的。与此同时fmt.*的调用遍布各 CLI 命令模块统计结果部分摘录文件fmt.*调用数dlt/_workspace/cli/_init_command.py57dlt/_workspace/cli/_pipeline_command.py57dlt/_workspace/cli/dlthub/ai/commands.py58dlt/_workspace/cli/_deploy_command.py49dlt/_workspace/cli/_pipeline_command_helpers.py46实际仓库中的导入写法规范文档中的示例写作from dlt._workspace.cli import fmt而仓库源码里的统一写法是给echo模块起别名from dlt._workspace.cli import echo as fmt该导入在 _init_command.py、_pipeline_command.py、_telemetry_command.py、commands.py 等所有 CLI 命令模块中保持一致。也就是说评审时的实质标准是输出统一走dlt._workspace.cli.echo暴露的函数族别名习惯是fmt。fmt 输出 API 的底层实现fmt的全部能力集中在 dlt/_workspace/cli/echo.py模块 docstring 为 CLI prompting and output helpers。理解其实现能解释为什么它适合取代logger。基础输出函数基于 clickecho.py在模块末尾直接绑定 click 的打印函数并封装了三个带前缀的语义函数echo click.echo secho click.secho style click.style def bold(msg: str) - str: return click.style(msg, boldTrue, resetFalse) click.style(, boldFalse, resetFalse) def warning_style(msg: str) - str: return click.style(msg, fgyellow, resetTrue) def error(msg: str) - None: click.secho(ERROR: msg, fgred) def warning(msg: str) - None: click.secho(WARNING: msg, fgyellow) def note(msg: str) - None: click.secho(NOTE: msg, fggreen)由此得到的语义约定是fmt.echo(...)普通中性输出fmt.secho(...)需要颜色/样式的输出可配合bold()等fmt.error(...)红色ERROR:前缀fmt.warning(...)黄色WARNING:前缀——这正是规范里warnings via fmt的落点fmt.note(...)绿色NOTE:前缀。真实调用示例来自 dlt/_workspace/cli/commands.pyfmt.warning( ... ) fmt.secho(pip install dlt[cli], boldTrue) fmt.echo( ... )非交互模式CLI 规范的另一半logger无法表达「非交互环境下的降级行为」而这正是echo.py的核心价值之一。文件顶部维护了三个模块级开关ALWAYS_CHOOSE_DEFAULT False ALWAYS_CHOOSE_VALUE: Any None ALWAYS_CONFIRM False并配套一组上下文工具echo.pyset_non_interactive(True)/set_auto_yes(True)分别对应--non-interactive和-y/--yes命令行选项always_choose(...)上下文管理器临时用预设值回答所有confirm/promptsuppress_echo()上下文管理器临时静默全部fmt输出把echo/secho/error/warning/note替换为 noop 并在退出时恢复——这是输出通道集中管理的直接证据logging做不到如此干净的作用域切换maybe_no_stdin()当 stdin 不是 tty如管道、CI时自动切入非交互模式。配套的交互函数confirm()、prompt()、text_input()在拿到预设值时直接返回否则回落到click.confirm/click.prompt若在非交互模式下遇到没有默认值的提示则调用error()打印可操作的报错并抛出 CliCommandExceptionerror( Cannot read %s in non-interactive mode (no default provided). Pass the value via a CLI option, or run interactively. % text ) raise CliCommandException()注意这段报错本身也遵循了下一条规范——标识符%s被反引号包裹并明确告诉用户该怎么做。此外echo.py还提供cli_cmd()帮助函数按当前 CLI 宿主dlt或dlthub重新排版示例命令例如把dlt pipeline my_pipe load-package 123映射为dlthub local pipeline load-package 123 my_pipe的动词前置形式见 echo.py。这使得所有提示用户的命令示例都能随宿主自动改写属于输出规范在可维护性上的延伸。错误消息格式标识符加反引号规范文档对错误消息的要求有三条标识符用反引号包裹写fTable {table_name} not found而不是fTable {table_name} not found语法正确评审会抓 duo - due、Fetche - Fetch 这类拼写错误提供可操作的上下文说明出了什么错、用户应该做什么。仓库中的真实样本反引号包裹标识符的写法在 CLI 源码中是普遍实践例如 dlt/_workspace/cli/commands.pymsg f{cmd} command moved to dlthub, pip install dlt[hub] and dlthub {new_cmd} to usedlt/_workspace/cli/dlthub/ai/commands.py 中的警告同时演示了反引号 可操作指引的完整形态fmt.warning(fMCP server cannot be started. Run {fmt.cli_cmd(ai status)} for details.) # ... fNow you can install your first toolkit. Use {fmt.cli_cmd(ai toolkit list)} fordlt/_workspace/cli/dlthub/utils.py 对路径类标识符同样加反引号f{deleted_dir_type} {deleted_dir} is the same as {label} and cannot be deleted f{deleted_dir_type} {deleted_dir} is not within run dir (workspace root) and cannotdlt/_workspace/cli/_pipeline_command.py 的弃用提示则同时满足了可操作上下文一条——指出新命令名drop-pending-packages is deprecated and now aborts packages. Use %s instead.从这些样本可以归纳出实际执行标准命令、表名、路径、配置项名等一切用户可在终端里敲出或定位的实体都加反引号让终端用户在纯文本输出中一眼区分叙述与标识符。CLI 导入分组与配置类位置_workspace导入成组书写规范文档给出的导入分组要求是_workspace相关导入放在一起不要与其他包的导入交错# GOOD — grouped from dlt._workspace.cli import fmt from dlt._workspace.configuration import WorkspaceConfig # BAD — mixed with other imports from dlt.common import logger from dlt._workspace.cli import fmt from dlt.extract import decorators from dlt._workspace.configuration import WorkspaceConfig仓库源码中可以看到与之对应的组织方式commands.py 的第一条dlt导入即把_workspace入口集中在一起from dlt._workspace.cli import echo as fmt, utils而 dlt/_workspace/cli/init.py 本身只再导出极少数公共符号SupportsCliCommand、CliCommandException、DEFAULT_VERIFIED_SOURCES_REPO其余能力均从子模块echo、utils、source_detection、_pipeline_files等显式按需导入——这与分组、可见、不混用的精神一致。配置类的归属位置规范的最后一条为 CLI 功能新增的配置类应放在dlt/_workspace/configuration/内不要散落在 workspace 模块之外。对应地仓库中的 dlt/_workspace/configuration.py 承载了WorkspaceConfig等 workspace 层配置规格dlt/_workspace/configuration/目录结构在仓库文件清单中可见例如 echo.py 在解析管道命令时就通过PipelineCommand().configure_parser(...)复用命令层的解析定义保持了配置归 configuration、输出归 echo、命令归命令模块的分层。评审自检清单综合规范文档与源码验证为 dlt 的 CLI 模块提交代码时可按以下清单自检检查项判定方法依据无logging用户输出在dlt/_workspace/cli/下检索import logging应为空规范文档当前仓库实测为空警告/错误经fmt发出使用fmt.warning/fmt.error/fmt.note导入写成from dlt._workspace.cli import echo as fmtecho.py、各命令模块标识符加反引号命令名、表名、路径等实体在消息中以包裹commands.py、dlthub/utils.py错误消息可操作说明发生了什么 下一步该做什么echo.py 的_raise_no_default_workspace导入成组不与dlt.common/dlt.extract等导入交错规范文档 第 3 节新配置类放在 workspace 内放入dlt/_workspace/configuration/dlt/_workspace/configuration.py非交互兼容交互提示走confirm/prompt/text_input可被always_choose/suppress_echo统一接管echo.py需要再次强调的适用边界以上全部约定只约束dlt/_workspace/cli/这一层及其dlthub/子包dlt 核心库dlt/common/、dlt/extract/、dlt/load/等仍使用标准logger体系二者是有意区分的两条输出通道。把握住这条边界就能既遵循评审约定又不至于把 CLI 的格式化习惯错误地扩散到库代码中。【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
dlt CLI 输出规范深度解析：fmt 统一输出、反引号错误消息与导入分组约定
dlt CLI 输出规范深度解析fmt 统一输出、反引号错误消息与导入分组约定【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt本篇指南基于 dlt 仓库的评审规范文档 .continue/agents/cli-output-conventions.md系统讲解 dlt 命令行位于 dlt/_workspace/cli/的三大核心约定用户可见输出一律通过fmt而非 Pythonlogger发出、错误消息中的标识符必须用反引号包裹、_workspace相关导入需成组书写。读完后你不仅能直接对照仓库源码验证每条规范的落地情况还能掌握为 dlt 的 CLI 模块贡献代码时如何通过代码评审检查如“CLI 模块里出现logging导入即违规”并了解echo/error/warning等输出函数在非交互模式、CI 环境下的底层行为。为什么 CLI 模块禁止使用 logger规范文档给出的最重要规则只有一句话dlt/_workspace/cli/下的模块必须使用fmt做用户可见输出不允许使用 Python 的logging模块。文档还引用了评审者的原话please do not use logger inclimodules. we issue warnings viafmt规范文档中的正误对照原文档给出的判定示例如下# BAD — in CLI module import logging logger logging.getLogger(__name__) logger.warning(Could not find scaffold) # GOOD — in CLI module from dlt._workspace.cli import fmt fmt.warning(Could not find scaffold)需要强调的边界是该规则只针对dlt/_workspace/cli/目录。在dlt/common/、dlt/extract/等非 CLI 的库代码中logger是正常且被鼓励的使用方式——dlt 的日志体系JSON 结构化日志等就构建在logging之上这条约定是为了把「库级日志」与「用户交互输出」两种通道严格分开。用仓库源码验证CLI 目录里确实没有 logging对整个 dlt/_workspace/cli/ 目录检索import logging/logging.getLogger结果为空——规范在存量代码上是完全落实的。与此同时fmt.*的调用遍布各 CLI 命令模块统计结果部分摘录文件fmt.*调用数dlt/_workspace/cli/_init_command.py57dlt/_workspace/cli/_pipeline_command.py57dlt/_workspace/cli/dlthub/ai/commands.py58dlt/_workspace/cli/_deploy_command.py49dlt/_workspace/cli/_pipeline_command_helpers.py46实际仓库中的导入写法规范文档中的示例写作from dlt._workspace.cli import fmt而仓库源码里的统一写法是给echo模块起别名from dlt._workspace.cli import echo as fmt该导入在 _init_command.py、_pipeline_command.py、_telemetry_command.py、commands.py 等所有 CLI 命令模块中保持一致。也就是说评审时的实质标准是输出统一走dlt._workspace.cli.echo暴露的函数族别名习惯是fmt。fmt 输出 API 的底层实现fmt的全部能力集中在 dlt/_workspace/cli/echo.py模块 docstring 为 CLI prompting and output helpers。理解其实现能解释为什么它适合取代logger。基础输出函数基于 clickecho.py在模块末尾直接绑定 click 的打印函数并封装了三个带前缀的语义函数echo click.echo secho click.secho style click.style def bold(msg: str) - str: return click.style(msg, boldTrue, resetFalse) click.style(, boldFalse, resetFalse) def warning_style(msg: str) - str: return click.style(msg, fgyellow, resetTrue) def error(msg: str) - None: click.secho(ERROR: msg, fgred) def warning(msg: str) - None: click.secho(WARNING: msg, fgyellow) def note(msg: str) - None: click.secho(NOTE: msg, fggreen)由此得到的语义约定是fmt.echo(...)普通中性输出fmt.secho(...)需要颜色/样式的输出可配合bold()等fmt.error(...)红色ERROR:前缀fmt.warning(...)黄色WARNING:前缀——这正是规范里warnings via fmt的落点fmt.note(...)绿色NOTE:前缀。真实调用示例来自 dlt/_workspace/cli/commands.pyfmt.warning( ... ) fmt.secho(pip install dlt[cli], boldTrue) fmt.echo( ... )非交互模式CLI 规范的另一半logger无法表达「非交互环境下的降级行为」而这正是echo.py的核心价值之一。文件顶部维护了三个模块级开关ALWAYS_CHOOSE_DEFAULT False ALWAYS_CHOOSE_VALUE: Any None ALWAYS_CONFIRM False并配套一组上下文工具echo.pyset_non_interactive(True)/set_auto_yes(True)分别对应--non-interactive和-y/--yes命令行选项always_choose(...)上下文管理器临时用预设值回答所有confirm/promptsuppress_echo()上下文管理器临时静默全部fmt输出把echo/secho/error/warning/note替换为 noop 并在退出时恢复——这是输出通道集中管理的直接证据logging做不到如此干净的作用域切换maybe_no_stdin()当 stdin 不是 tty如管道、CI时自动切入非交互模式。配套的交互函数confirm()、prompt()、text_input()在拿到预设值时直接返回否则回落到click.confirm/click.prompt若在非交互模式下遇到没有默认值的提示则调用error()打印可操作的报错并抛出 CliCommandExceptionerror( Cannot read %s in non-interactive mode (no default provided). Pass the value via a CLI option, or run interactively. % text ) raise CliCommandException()注意这段报错本身也遵循了下一条规范——标识符%s被反引号包裹并明确告诉用户该怎么做。此外echo.py还提供cli_cmd()帮助函数按当前 CLI 宿主dlt或dlthub重新排版示例命令例如把dlt pipeline my_pipe load-package 123映射为dlthub local pipeline load-package 123 my_pipe的动词前置形式见 echo.py。这使得所有提示用户的命令示例都能随宿主自动改写属于输出规范在可维护性上的延伸。错误消息格式标识符加反引号规范文档对错误消息的要求有三条标识符用反引号包裹写fTable {table_name} not found而不是fTable {table_name} not found语法正确评审会抓 duo - due、Fetche - Fetch 这类拼写错误提供可操作的上下文说明出了什么错、用户应该做什么。仓库中的真实样本反引号包裹标识符的写法在 CLI 源码中是普遍实践例如 dlt/_workspace/cli/commands.pymsg f{cmd} command moved to dlthub, pip install dlt[hub] and dlthub {new_cmd} to usedlt/_workspace/cli/dlthub/ai/commands.py 中的警告同时演示了反引号 可操作指引的完整形态fmt.warning(fMCP server cannot be started. Run {fmt.cli_cmd(ai status)} for details.) # ... fNow you can install your first toolkit. Use {fmt.cli_cmd(ai toolkit list)} fordlt/_workspace/cli/dlthub/utils.py 对路径类标识符同样加反引号f{deleted_dir_type} {deleted_dir} is the same as {label} and cannot be deleted f{deleted_dir_type} {deleted_dir} is not within run dir (workspace root) and cannotdlt/_workspace/cli/_pipeline_command.py 的弃用提示则同时满足了可操作上下文一条——指出新命令名drop-pending-packages is deprecated and now aborts packages. Use %s instead.从这些样本可以归纳出实际执行标准命令、表名、路径、配置项名等一切用户可在终端里敲出或定位的实体都加反引号让终端用户在纯文本输出中一眼区分叙述与标识符。CLI 导入分组与配置类位置_workspace导入成组书写规范文档给出的导入分组要求是_workspace相关导入放在一起不要与其他包的导入交错# GOOD — grouped from dlt._workspace.cli import fmt from dlt._workspace.configuration import WorkspaceConfig # BAD — mixed with other imports from dlt.common import logger from dlt._workspace.cli import fmt from dlt.extract import decorators from dlt._workspace.configuration import WorkspaceConfig仓库源码中可以看到与之对应的组织方式commands.py 的第一条dlt导入即把_workspace入口集中在一起from dlt._workspace.cli import echo as fmt, utils而 dlt/_workspace/cli/init.py 本身只再导出极少数公共符号SupportsCliCommand、CliCommandException、DEFAULT_VERIFIED_SOURCES_REPO其余能力均从子模块echo、utils、source_detection、_pipeline_files等显式按需导入——这与分组、可见、不混用的精神一致。配置类的归属位置规范的最后一条为 CLI 功能新增的配置类应放在dlt/_workspace/configuration/内不要散落在 workspace 模块之外。对应地仓库中的 dlt/_workspace/configuration.py 承载了WorkspaceConfig等 workspace 层配置规格dlt/_workspace/configuration/目录结构在仓库文件清单中可见例如 echo.py 在解析管道命令时就通过PipelineCommand().configure_parser(...)复用命令层的解析定义保持了配置归 configuration、输出归 echo、命令归命令模块的分层。评审自检清单综合规范文档与源码验证为 dlt 的 CLI 模块提交代码时可按以下清单自检检查项判定方法依据无logging用户输出在dlt/_workspace/cli/下检索import logging应为空规范文档当前仓库实测为空警告/错误经fmt发出使用fmt.warning/fmt.error/fmt.note导入写成from dlt._workspace.cli import echo as fmtecho.py、各命令模块标识符加反引号命令名、表名、路径等实体在消息中以包裹commands.py、dlthub/utils.py错误消息可操作说明发生了什么 下一步该做什么echo.py 的_raise_no_default_workspace导入成组不与dlt.common/dlt.extract等导入交错规范文档 第 3 节新配置类放在 workspace 内放入dlt/_workspace/configuration/dlt/_workspace/configuration.py非交互兼容交互提示走confirm/prompt/text_input可被always_choose/suppress_echo统一接管echo.py需要再次强调的适用边界以上全部约定只约束dlt/_workspace/cli/这一层及其dlthub/子包dlt 核心库dlt/common/、dlt/extract/、dlt/load/等仍使用标准logger体系二者是有意区分的两条输出通道。把握住这条边界就能既遵循评审约定又不至于把 CLI 的格式化习惯错误地扩散到库代码中。【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考